Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-c-shared-utility/devdoc/porting_guide.md

raw
1 # How to Port the Azure IoT C SDK to Other Platforms
2
3 The purpose of this document is to provide guidance on how to port the C Shared utility library to platforms not supported out of the box.
4 The C shared utility library is used by C SDKs like IoTHub client SDK and EventHub client SDK.
5
6 The document does not cover the specifics of any particular platform.
7
8 ## References
9
10 ###### Specifications
11 - [tickcounter FreeRTOS reference](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/tickcounter_freertos_requirement.md)<br/>
12 - [agenttime adapter specification](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/agenttime_requirements.md)<br/>
13 - [threadapi and sleep adapter specification](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/threadapi_and_sleep_requirements.md)<br/>
14 - [platform adapter specification](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/platform_requirements.md)<br/>
15 - [tlsio specification](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/tlsio_requirements.md)<br/>
16 - [xio specification](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/xio_requirements.md)<br/>
17 - [lock adapter specification](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/lock_requirements.md)<br/>
18
19 ###### Header files
20 - [tickcounter.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/tickcounter.h)<br/>
21 - [threadapi.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/threadapi.h)<br/>
22 - [xio.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/xio.h)<br/>
23 - [tlsio.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/tlsio.h)<br/>
24 - [socketio.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/socketio.h)<br/>
25 - [lock.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/lock.h)<br/>
26 - [platform.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/platform.h)<br/>
27
28
29
30 # Table of contents
31
32 - [Overview](#Overview)
33 - [tickcounter adapter](#tickcounter-adapter)
34 - [agenttime adapter](#agenttime-adapter)
35 - [sleep adapter](#sleep-adapter)
36 - [platform adapter](#platform-adapter)
37 - [tlsio adapter overview](#tlsio-adapter-overview)
38 - [socketio adapter overview (optional)](#socketio-adapter)
39 - [tlsio adapter implementation](#tlsio-adapter-implementation)
40 - [threadapi and lock adapters (optional)](#threadapi-and-lock-adapters)
41
42 ## Overview
43
44
45 The C shared utility library is written in C99 for the purpose of portability to most platforms.
46 However, several components rely on platform-specific resources in order to achieve the functionality required.
47 Thus, porting the C shared utility library is done by porting the PAL components (adapters) that are
48 part of the library. Below is a rough overview of the components:
49
50 ![](img/porting_guide_overview.png)
51
52 There are several mandatory components for which an adapter must be provided:
53
54 - A `tickcounter` implementation: this provides the SDK an adapter for getting a tick counter expressed in ms.
55 The precision does not have to be milliseconds, but rather the value provided to the SDK has to be
56 expressed in milliseconds.
57
58 - An `agenttime` implementation: this provides the SDK adapters for the C time management functions like
59 `time`, `difftime`, etc. This is needed due to the very wide spread differences in the way time is
60 handled by different platforms.
61
62 - A `sleep` implementation to provide a device-independent sleep function.
63
64 - A `platform` implementation to perform global init and de-init.
65
66 - A `tlsio` implementation to allow the SDK to communicate over TLS. The IoT Hub does not support insecure
67 communication.
68
69 Additionally, there are two optional components, `threadapi` and `lock`, that allow the SDK to communicate with
70 an IoT Hub on a dedicated thread. Yet another optional component is the `socketio` adapter, which is used with
71 some kinds of `tlsio` adapter implementations.
72
73 There are several existing adapters that can be found under the SDK's
74 [adapters directory](https://github.com/Azure/azure-c-shared-utility/blob/master/adapters)
75 and
76 [source directory](https://github.com/Azure/azure-c-shared-utility/blob/master/src).
77 If any of these adapters work for your device, simply include that file in your project directly.
78
79 ### tickcounter adapter
80
81 Tickcounter behavior is exemplified by the
82 [tickcounter FreeRTOS reference](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/tickcounter_freertos_requirement.md).
83
84 To get started, copy
85 [this version of tickcounter.c](https://github.com/Azure/azure-c-shared-utility/blob/master/pal/freertos/tickcounter.c)
86 file and modify it to suit your device.
87
88 ### agenttime adapter
89
90 The agenttime adapter is specified in
91 [agenttime adapter specification](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/agenttime_requirements.md)
92 and provides platform-independent time functions.
93
94 For most platforms/OSs you can include the standard [agenttime.c](https://github.com/Azure/azure-c-shared-utility/blob/master/pal/agenttime.c)
95 file in your build. This adapter simply calls the C functions `time`, `difftime`, `ctime`, etc.
96
97 If this file does not work for your implementation, make a copy of it and modify it appropriately.
98
99 The Azure IoT SDK only requires the `get_time` and `get_difftime` functions. The other functions
100 in this adapter -- `get_gmtime`, `get_mktime`, and `get_ctime` -- are deprecated and
101 may be omitted or left non-functional.
102
103 ### sleep adapter
104
105 The sleep adapter is a single function that provides a device-independent thread sleep. Unlike other
106 adapters, it does not have its own header file. Instead, its declaration is contained in the
107 [threadapi.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/threadapi.h)
108 file along with the declarations for the optional threadapi adapter, and its implementation is typically
109 contained in an associated threadapi.c file.
110
111 Unlike the rest of the functions in
112 [threadapi.h](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/threadapi.h),
113 however, `ThreadAPI_Sleep` is required by the SDK and must always be functional.
114
115 The specification for the sleep adapter is found in the
116 [threadapi and sleep adapter specification](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/threadapi_and_sleep_requirements.md).
117
118 ### platform adapter
119
120 The platform adapter performs one time initialization and deinitialization for the platform and also supplies the SDK with an appropriate TLSIO.
121
122 The
123 [platform adapter specification](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/platform_requirements.md)
124 gives full instructions for writing the platform adapter.
125
126 To get started creating your platform adapter, copy
127 [this Windows platform.c file](https://github.com/Azure/azure-c-shared-utility/blob/master/adapters/platform_win32.c)
128 and modify it to suit your needs.
129
130 ### threadapi and lock adapters
131
132 The **threadapi** and **lock** adapters must exist for the SDK to compile, but their functionality is optional.
133 Their specification documents (see below) detail what each empty function should do if threading functionality
134 is not needed.
135
136 These components that allow the SDK to
137 communicate with an IoT Hub within a dedicated thread. The use of a dedicated thread has some cost
138 in memory consumption because of the
139 need for a separate stack, which may make the dedicated thread difficult to use on devices with little free
140 memory.
141
142 The upside of the dedicated thread is that all current tlsio adapters may repeatedly
143 block for some fraction
144 of a minute when attempting to connect to their IoT Hub when the network is unavailable, and having a thread
145 dedicated to the Azure IoT SDK will allow other device functions to remain responsive while the SDK is blocked.
146
147 Future versions of the SDK may eliminate this potential blocking behavior, but for now, devices which must
148 be responsive will need to use a dedicated thread for the SDK, which requires implementing the ThreadApi
149 and Lock adapters.
150
151 Here are the specs for the threadapi and lock adapters:
152 - [threadapi and sleep adapter specification](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/threadapi_and_sleep_requirements.md)<br/>
153 - [lock adapter specification](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/lock_requirements.md)<br/>
154
155 These specs explain how to create null _lock_ and _threadapi_ adapters for when threading is not desired.
156
157 To get started creating your threadapi and lock adapters, copy these Windows adapter files and modify
158 them appropriately:
159 - [threadapi.c](https://github.com/Azure/azure-c-shared-utility/blob/master/adapters/threadapi_win32.c)
160 - [lock.c](https://github.com/Azure/azure-c-shared-utility/blob/master/adapters/lock_win32.c)
161
162
163 ### tlsio adapter overview
164
165 A **tlsio** adapter provides the SDK with secure TLS communication wtih the Azure IoT Hub.
166
167 Tlsio adapters expose their functionality to the SDK via `xio`, which
168 is a generic C-language bits-in-bits-out interface
169 [defined here](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/xio.h).
170
171 A tlsio adapter instance is created via the adapter's
172 [`xio_create`](https://github.com/Azure/azure-c-shared-utility/blob/bc5d4eb8f9dbe3092c9cf046db9b7187b5baad4b/inc/azure_c_shared_utility/xio.h#L64)
173 function, and the configuration parameter `const void* io_create_parameters`
174 must be of the specialized type
175 [`TLSIO_CONFIG`](https://github.com/Azure/azure-c-shared-utility/blob/master/inc/azure_c_shared_utility/tlsio.h)
176 when creating the tlsio instance.
177
178 Implementation of tlsio adapters for new devices is done by selecting the existing tlsio adapter (and perhaps also
179 a socketio adapter) that most closely fits your needs and modifying it accordingly.
180
181 ##### The two styles of tlsio
182
183 There are two possible design patterns for a tlsio adapter: _direct_, and _chained_. In the _direct_ style, the
184 tlsio adapter owns a TCP socket which it uses to directly perform TLS communication with the remote host. In the
185 _chained_ style, the tlsio adapter does not own a TCP socket and does not communicate directly with the remote host.
186 Instead, it still does all the TLS chores like encryption, decryption, and negotiation, but it communicates with
187 the remote host indirectly via yet another xio-style adapter of some sort.
188
189 The _direct_ style adapters require less code and avoid extra memory buffer copying, so they are more suited to
190 microcontrollers. The tlsio adapters for Arduino and ESP32 are both _direct_ types. The _chained_ style adapters
191 are more resource-hungry, but they offer more flexibilty. The tlsio adapters for Windows, Linux, and Mac
192 are all _chained_ style adapters.
193
194 The choice of TLS implementation may dictate the style of tlsio. For example, the TLS implementations for Arduino and
195 Espressif's OpenSSL implementation for ESP32 can only work directly with their own internal TCP socket,
196 so they can only be used as part of a _direct_ style tlsio. By contrast, the full official version
197 of OpenSSL can be used either way.
198
199
200 ### socketio adapter overview
201
202 In order to connect to the internet, a _chained_ tlsio must at some point talk through an `xio` adapter
203 that contains
204 a TCP socket. In the Azure IoT SDK, an `xio` adapter managing a TCP socket is called a `socketio` adapter.
205
206 Multiple xio components can be chained together if desired. Here is a diagram illustrating the differences
207 between a _direct_ tlsio, a _chained_
208 tlsio, and a _chained_ tlsio with an xio-based http proxy component:
209 ![](img/xio_chain.png)
210 The `xio_http_proxy` component is only shown to illustrate xio capability. Its details are beyond the
211 scope of this document.
212
213 ### tlsio adapter implementation
214
215 Adapters other than tlsio are easy to implement, even for inexperienced developers. The tlsio adapters, however,
216 are quite complicated, and writing a tlsio adapter is a task only for experienced developers who are comfortable
217 setting up include directories and external libraries without instruction.
218
219 The most up-to-date information on tlsio implementation is contained in the
220 [tlsio specification](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/tlsio_requirements.md).
221
222 All of the existing tlsio adapters use TLS libraries that are not part of the Azure IoT SDK. Refer to the
223 documentation for the specific TSL libraries for instructions on library usage such as setting include
224 directories and linking library files.
225
226 #### Existing _direct_ tlsio implementations
227 There are two existing _direct_ adapter implementations:
228 - [tlsio_openssl_compact for ESP32](https://github.com/Azure/azure-iot-pal-esp32/blob/master/pal/src/tlsio_openssl_compact.c)
229 - [tlsio_arduino for Arduino](https://github.com/Azure/azure-iot-pal-arduino/blob/master/pal/src/tlsio_arduino.c)
230
231 Of these two, the
232 [tlsio_openssl_compact for ESP32](https://github.com/Azure/azure-iot-pal-esp32/blob/master/pal/src/tlsio_openssl_compact.c)
233 is probably the better candidate for copying for re-use because it is more likely to resemble newer devices,
234 and it was written in tandem with the
235 [tlsio specification](https://github.com/Azure/azure-c-shared-utility/blob/master/devdoc/tlsio_requirements.md).
236
237 The
238 [tlsio_openssl_compact for ESP32](https://github.com/Azure/azure-iot-pal-esp32/blob/master/pal/src/tlsio_openssl_compact.c)
239 abstracts its operating system dependencies using these two files:
240 - [socket_async.c](https://github.com/Azure/azure-c-shared-utility/blob/master/pal/socket_async.c)
241 - [dns_resolver_ares.c](https://github.com/Azure/azure-c-shared-utility/blob/master/src/dns_resolver_ares.c)
242
243 It is recommended that all _direct_ tlsio implementatons follow this pattern.
244
245 The
246 [socket_async.c](https://github.com/Azure/azure-c-shared-utility/blob/master/pal/socket_async.c)
247 and
248 [dns_resolver_ares.c](https://github.com/Azure/azure-c-shared-utility/blob/master/src/dns_resolver_ares.c)
249 files can be re-used without change for most socket implementations by merely changing the content of
250 the included "socket_async_os.h" file, which contains os-specific headers.
251
252 #### Existing _chained_ tlsio implementations
253 _Chained_ adapter implementations include:
254 - [tlsio_openssl for Windows, Linux, and Mac](https://github.com/Azure/azure-c-shared-utility/blob/master/adapters/tlsio_openssl.c)
255 - [tlsio_schannel for Windows only](https://github.com/Azure/azure-c-shared-utility/blob/master/adapters/tlsio_schannel.c)
256 - [tlsio_wolfssl for embedded devices](https://github.com/Azure/azure-c-shared-utility/blob/master/adapters/tlsio_wolfssl.c)
257 - [tlsio_mbedtls for embedded devices](https://github.com/Azure/azure-c-shared-utility/blob/master/adapters/tlsio_mbedtls.c)
258
259 #### Existing socketio implementations for _chained_ tlsio adapters
260 There is no spec for socketio adapters, so it is necessary to copy the behavior of an existing one, and
261 [socketio_berkeley](https://github.com/Azure/azure-c-shared-utility/blob/master/adapters/socketio_berkeley.c)
262 is the best candidate for copying. However, be aware that all existing socketio adapters including
263 [socketio_berkeley](https://github.com/Azure/azure-c-shared-utility/blob/master/adapters/socketio_berkeley.c)
264 purge their pending io lists during socketio_destroy, which is incorrect. The pending io
265 lists should be purged during socketio_close instead.
266 - [socketio_berkeley for Linux, easily adapted to any Berkeley socket](https://github.com/Azure/azure-c-shared-utility/blob/master/adapters/socketio_berkeley.c)
267 - [socketio_win32 for Windows](https://github.com/Azure/azure-c-shared-utility/blob/master/adapters/socketio_win32.c)
268 - [tlsio_cyclonessl_socket for use with cyclonessl](https://github.com/Azure/azure-c-shared-utility/blob/master/src/tlsio_cyclonessl_socket.c)
269
270 ### Adding device support repositories
271
272 Newly supported devices are likely to use a wide variety of possible build systems, so no single standard source
273 tree can be prescribed. The [support repository for ESP32](https://github.com/Azure/azure-iot-pal-esp32) is the
274 one we recommend considering as a model for creating a new device support repository.
275
276
277