104 lines
4.6 KiB
Markdown
104 lines
4.6 KiB
Markdown
|
# 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.
|
||
|
|
|