1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
# FreeRTOS
[FreeRTOS][1] is real-time operating system kernel for embedded devices. Think
of it as a thread library rather than a general purpose operating system like
Linux or Microsoft Windows. Out-of-the-box, FreeRTOS provides support for
tasks (threads), mutexes, semaphores and software times. Third-party modules
are available to add features. e.g. [lwIP][2] can be used to add networking.
> FreeRTOS+lwIP is currently supported by Eclipse Cyclone DDS. Support for other
> network stacks, e.g. [FreeRTOS+TCP][3], may be added in the future.
> Eclipse Cyclone DDS does not make use of [FreeRTOS+POSIX][4] because it was
> not available at the time. Future versions of Eclipse Cyclone DDS may or may
> not require FreeRTOS+POSIX for compatibility when it becomes stable.
[1]: https://www.freertos.org/
[2]: https://savannah.nongnu.org/projects/lwip/
[3]: https://www.freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/index.html
[4]: https://www.freertos.org/FreeRTOS-Plus/FreeRTOS_Plus_POSIX/index.html
## Target
FreeRTOS provides an operating system kernel. Batteries are not included. i.e.
no C library or device drivers. Third-party distributions, known as board
support packages (BSP), for various (hardware) platforms are available though.
Board support packages, apart from FreeRTOS, contain:
* C library. Often ships with the compiler toolchain, e.g.
[IAR Embedded Workbench][5] includes the DLIB runtime, but open source
libraries can also be used. e.g. The [Xilinx Software Development Kit][6]
includes newlib.
* Device drivers. Generally available from the hardware vendor, e.g. NXP or
Xilinx. Device drivers for extra components, like a real-time clock, must
also be included in the board support package.
[5]: https://www.iar.com/iar-embedded-workbench/
[6]: https://www.xilinx.com/products/design-tools/embedded-software/sdk.html
A board support package is linked with the application by the toolchain to
generate a binary that can be flashed to the target.
### Requirements
Eclipse Cyclone DDS requires certain compile-time options to be enabled in
FreeRTOS (`FreeRTOSConfig.h`) and lwIP (`lwipopts.h`) for correct operation.
The compiler will croak when a required compile-time option is not enabled.
Apart from the aforementioned compile-time options, the target and toolchain
must provide the following.
* Support for thread-local storage (TLS) from the compiler and linker.
* Berkeley socket API compatible socket interface.
* Real-time clock (RTC). A high-precision real-time clock is preferred, but
the monotonic clock can be combined with an offset obtained from e.g. the
network if the target lacks an actual real-time clock. A proper
`clock_gettime` implementation is required to retrieve the wall clock time.
### Thread-local storage
FreeRTOS tasks are not threads and compiler supported thread-local storage
(tls) might not work as desired/expected under FreeRTOS on embedded targets.
i.e. the address of a given variable defined with *__thread* may be the same
for different tasks.
The compiler generates code to retrieve a unique address per thread when it
encounters a variable defined with *__thread*. What code it generates depends
on the compiler and the target it generates the code for. e.g. `iccarm.exe`
that comes with IAR Embedded Workbench requires `__aeabi_read_tp` to be
implemented and `mb-gcc` that comes with the Xilinx SDK requires
`__tls_get_addr` to be implemented.
The implementation for each of these functions is more-or-less the same.
Generally speaking they require the number of bytes to allocate, call
`pvTaskGetThreadLocalStoragePointer` and return the address of the memory
block to the caller.
## Simulator
FreeRTOS ports for Windows and POSIX exist to test compatibility. How to
cross-compile Eclipse Cyclone DDS for the [FreeRTOS Windows Port][7] or
the unofficial [FreeRTOS POSIX Port][8] can be found in the msvc and
[posix](/ports/freertos-posix) port directories.
[7]: https://www.freertos.org/FreeRTOS-Windows-Simulator-Emulator-for-Visual-Studio-and-Eclipse-MingW.html
[8]: https://github.com/shlinym/FreeRTOS-Sim.git
## Known Limitations
Triggering the socket waitset is not (yet) implemented for FreeRTOS+lwIP. This
introduces issues in scenarios where it is required.
* Receive threads require a trigger to shutdown or a thread may block
indefinitely if no packet arrives from the network.
* Sockets are created dynamically if ManySocketsMode is used and a participant
is created, or TCP is used. A trigger is issued after the sockets are added
to the set if I/O multiplexing logic does not automatically wait for data
on the newly created sockets as well.
|
