| 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 |
 |
| 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 |
 |
| 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 |
|