portable/GCC/Posix: add new port for Posix (Linux) applications

This is similar to the Windows port, allowing FreeRTOS kernel
applications to run as regular applications on Posix (Linux) systems.

You can use this in a 32-bit or 64-bit application (although there are
dynamic memory allocation trace points that do not support 64-bit
addresses).

Many of the same caveats of running an RTOS on a non-real-time system
apply, but this is still very useful for easy debugging/testing
applications in a simulated environment. In particular, it allows easy
use of tools such as valgrind.

You can call standard library functions from tasks but care must be
taken with any that internally take mutexes or block. This includes
malloc()/free() and many stdio functions (e.g., printf()).

Replacement malloc(), free(), realloc(), and calloc() functions are
provided which are safe. printf() needs to be called with a FreeRTOS
mutex help (or called from only a single task).

Each task is run in its own pthread, which makes debugging with
standard tools (such as GDB) easier backtraces for individual tasks
are available. Threads for non-running tasks are blocked in sigwait().

The stack for each task (thread) is allocated when the thread is
created, and the stack provided during task creation is not used. This
is so the stack has guard pages, to help with detecting stack
overflows.

Task switch is done by resuming the thread for the next task by
sending it the resume signal (SIGUSR1) and then suspending the current
thread.

The timer interrupt uses SIGALRM and care is taken to ensure that the
signal handler runs only on the thread for the current task.

The additional data needed per-thread is stored at the top on the
task's stack.

When a running task is being deleted, its thread is marked it as dying
so when we switch away from it it exits instead of suspending. This
ensures that even if the idle task doesn't run, threads are deleted
which allows for more threads to be created (if many tasks are being
created and deleted in rapid succession).

To further aid debugging, SIGINT (^C) is not blocked inside critical
sections. This allows it to be used break into GDB while in a critical
section. This means that care must be taken with any custom SIGINT
handlers as these are like NMIs.

This is somewhat inspired by an existing port by William Davy
(https://www.freertos.org/FreeRTOS-simulator-for-Linux.html) but it
takes a number of different approaches to make it switch tasks
reliableand there's little similarly with the original implementation.

- Critical sections block scheduling/"interrupts" by blocking signals
  using pthread_sigmask(). This is more expensive than attempting to
  use flags but works reliably and is analogous to the interrupt
  enable/disable on real hardware.

- Care is take to ensure that the SIGALRM handler (for the timer tick)
  is runnable only on the pthread for the running task. This makes
  tasks switches more straight-forward and reliable as we can suspend
  the thread while in the signal handler.

- Task switches save/restore the critical nesting on the stack.

- Only uses a single (SIGUSR1) signal which is ignored and thus GDB's
  default signal handling options won't trap/print on this signal.

- Extra per-thread data is stored on the task's stack, making it
  accessible in O(1) instead of performing a O(n) lookup of the array.

- Uses the task create/delete hooks in a similar way to the Windows
  port, rather than overloading trace points.
2 files changed
tree: 81732f40a0708078e5a2269001d07bd4a67ee0a9
  1. .github/
  2. include/
  3. portable/
  4. CONTRIBUTING.md
  5. croutine.c
  6. event_groups.c
  7. GitHub-FreeRTOS-Kernel-Home.url
  8. History.txt
  9. LICENSE.md
  10. list.c
  11. queue.c
  12. Quick_Start_Guide.url
  13. README.md
  14. SECURITY.md
  15. stream_buffer.c
  16. tasks.c
  17. timers.c
README.md

Getting started

This repository contains FreeRTOS kernel source/header files and kernel ports only. This repository is referenced as a submodule in FreeRTOS/FreeRTOS repository, which contains pre-configured demo application projects under FreeRTOS/Demo directory.

The easiest way to use FreeRTOS is to start with one of the pre-configured demo application projects. That way you will have the correct FreeRTOS source files included, and the correct include paths configured. Once a demo application is building and executing you can remove the demo application files, and start to add in your own application source files. See the FreeRTOS Kernel Quick Start Guide for detailed instructions and other useful links.

Additionally, for FreeRTOS kernel feature information refer to the Developer Documentation, and API Reference.

Getting help

If you have any questions or need assistance troubleshooting your FreeRTOS project, we have an active community that can help on the FreeRTOS Community Support Forum.

Cloning this repository

To clone using HTTPS:

git clone https://github.com/FreeRTOS/FreeRTOS-Kernel.git

Using SSH:

git clone git@github.com:FreeRTOS/FreeRTOS-Kernel.git

Repository structure

  • The root of this repository contains the three files that are common to every port - list.c, queue.c and tasks.c. The kernel is contained within these three files. croutine.c implements the optional co-routine functionality - which is normally only used on very memory limited systems.

  • The ./portable directory contains the files that are specific to a particular microcontroller and/or compiler. See the readme file in the ./portable directory for more information.

  • The ./include directory contains the real time kernel header files.