niklas/cyclonedds
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add support for FreeRTOS and lwIP (#166)

Browse source 
Add support for FreeRTOS and lwIP

Signed-off-by: Jeroen Koekkoek <jeroen@koekkoek.nl>
This commit is contained in:
Jeroen Koekkoek 2019-05-23 14:27:56 +02:00 • committed by eboasson
parent dba4e6d391
commit aa2715f4fe
67 changed files with 3691 additions and 200 deletions
Download patch file Download diff file Expand all files Collapse all files

103
docs/dev/freertos.md Normal file
View file

@ -0,0 +1,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.