PR #914 caused Posix Port to fail to build on MacOS. This PR fixes
teh build failure.
This PR also adds a Matrix configuration to the GitHub kernel-demo
workflow to build the Posix Demos on MacOS.
---------
Co-authored-by: chinglee-iot <61685396+chinglee-iot@users.noreply.github.com>
Co-authored-by: Gaurav-Aggarwal-AWS <33462878+aggarg@users.noreply.github.com>
Change from pthread_attr_setstack() to pthread_attr_setstacksize(), and automatically adjust the stack size
to be at least PTHREAD_STACK_MIN if it wasn't already, removing the size warning.
This permits the user to increase the pthread stack size beyond the PTHREAD_STACK_MIN default of 16384 if
desired, without producing a warning in the typical case where stacks are minimized for RAM limited targets.
Continue to store thread paramters on the provided stack, for consistency with the MCU targets.
Previously pthread_attr_setstack() was used to enable user defined stacks.
Note that:
1. The stack size can still be specified by the user.
2. pxPortInitialiseStack(), and pthread_addr_setstack() was failing on stacks of typical size, as
these are smaller than PTHREAD_STACK_MIN (16384) bytes, and printing out a series of warnings.
Improve usability by having the posix port automatically increase the stack size to be
at least PTHREAD_STACK_MIN as posix platforms have enough memory for this not to be a concern.
3. Reuse of stack memory will also result in valgrind 'invalid write' errors to what is demonstrably
valid memory. Root cause is that Valgrind is tracking a stack pointer as the stack is used.
Reuse of a stack buffer results in the stack being used at its start, in an area that Valgrind thinks
is far away from the start of the stack. There are ways to notify Valgrind of these changes
however this would require linking against and calling Valgrind functions from the FreeRTOS application using
the posix port, https://valgrind.org/docs/manual/manual-core-adv.html#manual-core-adv.clientreq.
Also, apparently it isn't permitted by posix to reuse stack memory once its been used in a pthread via pthread_attr_setstack(),
see https://stackoverflow.com/a/5422134
For a clean shutdown where memory is freed, it is necessary for all pthreads to be joined
at shutdown.
Previously there was explicit cancellation of the idle task and timer daemon task, however
there may be a number of other tasks in the system, both system created and user created,
and those tasks/threads were being left at shutdown.
This change calls pthread_cancel()/pthread_join() on all FreeRTOS managed pthreads upon
shutdown.
Improve upon the elegant approach of using signals to cause task/pthreads
suspension and scheduler execution by using directed signals.
This fixes:
- Deadlocks in non-FreeRTOS pthreads
- Multiple FreeRTOS tasks(pthreads) incorrectly running at the same time
By directing the signals using pthread_kill() the signal handler in the presently running
FreeRTOS task/pthread will be called, ensuring that the scheduler runs both in the context
of a FreeRTOS task/pthread and from the presently executing FreeRTOS task/pthread.
Details
==============
The POSIX port uses signals to preempt FreeRTOS tasks (implemented as pthreads), a very neat and elegant
approach to forcing tasks/pthreads to suspend and run the scheduler.
Signal handlers are process global.
Posix timers generate signals when the timer expires, and the signal is sent to the currently
running pthread.
In systems where there are pthreads that are NOT a result of creating FreeRTOS tasks, such as the
entry point thread that calls main(), or user created pthreads, this poses a serious issue.
While the POSIX port only allows a single FreeRTOS pthread to run at once, by causing all suspended
threads to not be scheduled due to their waiting on a pthread condition variable,
this isn't the case with non-FreeRTOS pthreads.
Thus it is possible that a non-FreeRTOS pthread is running when the timer expires and the signal
is generated. This results in the signal handler running in the non-FreeRTOS thread.
The sequence of events results in these events from signal handler context:
- vPortSystemTickHandler() being called
- The scheduler running
- Selecting another FreeRTOS task to run and switching the active task
- The newly selected task released from suspension by pthread_cond_signal()
- The presently active thread calling event_wait()
- The pthread calling pthread_cond_wait(), suspending the thread and allowing the host OS scheduler
to schedule another thread to run.
If this occurs from a non-FreeRTOS thread this results in:
- The active FreeRTOS pthread (Task A/Thread A) continuing to run (as the signal handler that calls
event_wait() ran instead in a non-FreeRTOS pthread.
- The pthread where the signal handler did run (Thread B) will call event_wait() and pthread_cond_wait(),
but on the condition variable of the previously active FreeRTOS task, oops. This causes the
non-FreeRTOS pthread to block unexpectedly relative to what the developer might have expected.
- The newly selected FreeRTOS Task (Task C/Thread C) will resume and start running.
At this point Task A/Thread A is running concurrently with Task C/Thread C. While this may not
necessarily be an issue, it does not replicate the expected behavior of a single Task running at
once.
Note that Thread B will resume if/when Task A/ThreadA is switched to. However, this could be delayed
by an arbitrary amount of time, or could never occur.
Also note that if there are multiple non-FreeRTOS pthreads that Thread D, E, F...etc could suffer the
same fate as Thread B, if the scheduler were to suspend Task C/Thread C and resume Task E/Thread E.
Implementation
==============
Timer details
-------------
A standalone pthread for the signal generation thread was chosen, rather than using
a posix timer_settime() handler function because the latter creates a temporary
pthread for each handler callback. This makes debugging much more difficult due to
gdb detecting the creation and destruction of these temporary threads.
Signal delivery
--------------
While signal handlers are per-thread, it is possible for pthreads to selectively block
signals, rather than using thread directed signals. However, the approach of blocking
signals in non-FreeRTOS pthreads adds complexity to each of these non-FreeRTOS pthreads
including ensuring that these signals are blocked at thread creation, prior to the thread
starting up. Directed signals removes the requirement for non-FreeRTOS pthreads to be aware
of and take action to protect against these signals, reducing complexity.
Aligns the stack end to a page boundary before computing its
size, since the size depends on both the start and end.
The original change which introduced stack alignment (#674)
only worked for cases where the round + trunc operation would
wind up within the same area, but would lead to segfaults in
other cases.
Also adds a typecast to the `mach_vm_round_page()` call, as
it is actually a macro which casts to `mach_vm_offset_t` and
the result here is used as a `StackType_t` pointer.
Tested on ARM64 and Intel MacOS, as well as ARM64 and Intel
Linux. The test code included a single-task case, as well
as a case with two tasks passing queue messages.
* Use new version of CI-CD Actions
* Use cSpell spell check, and use ubuntu-20.04 for formatting check
* Format and spell check all files in the portable directory
* Remove the https:// from #errors and #warnings as uncrustify attempts to change it to /*
* Use checkout@v3 instead of checkout@v2 on all jobs
---------
* Fix freertos_kernel cmake property, Posix Port
* Moves the `set_property()` call below the target definition in top level CMakeLists file
* Corrects billion value from `ULL` suffix (not C90 compliant) to `UL` suffix with cast to uint64_t
* Add blank line to CMakeLists.txt
* Fix types in POSIX port
Use TaskFunction_t and StackType_t as other ports do.
* Fix portTICK_RATE_MICROSECONDS in POSIX port
---------
Co-authored-by: Jacques GUILLOU <jacques.guillou.job@gmail.com>
Co-authored-by: Gaurav-Aggarwal-AWS <33462878+aggarg@users.noreply.github.com>
* Adding in ability to support a library for freertos_config and a custom freertos_kernel_port (#558)
* Using single name definition for libraries everywhere. (#558)
* Supporting backwards compatibility with FREERTOS_CONFIG_FILE_DIRECTORY (#571)
* Removing compiler warnings for GNU and Clang. (#571)
* Added in documentation on how to consume from a main project. Added default PORT selection for native POSIX and MINGW platforms.
* Only adding freertos_config if it exists. Removing auto generation of it from a FREERTOS_CONFIG_FILE_DIRECTORY.
* Fixing clang and gnu compiler warnings.
* Adding in project information and how to compile for GNU/clang
* Fixing compiler issue with unused variable - no need to declare variable.
* Adding in compile warnings for linux builds that kernel is okay with using.
* Fixing more extra-semi-stmt clang warnings.
* Moving definition of hooks into header files if features are enabled.
* Fixing formatting with uncrustify.
* Fixing merge conflicts with main merge.
* Fixing compiler errors due to merge issues and formatting.
* Fixing Line feeds.
* Adding 'portNORETURN' into portmacros.h. Other Updates based on PR request
* Further clean-up of clang and clang-tidy issues.
* Removing compiler specific pragmas from common c files.
* Fixing missing lexicon entry and uncrustify formatting changes.
* Resolving merge issue multiple defnitions of proto for prvIdleTask
* Fixing formatting issues that are not covered by uncrustify. Use clang-tidy instead if you want this level of control.
* More uncrustify formatting issues.
* Fixing extra bracket in #if statement.
---------
Co-authored-by: Gaurav-Aggarwal-AWS <33462878+aggarg@users.noreply.github.com>
There's already a portYIELD_FROM_ISR() macro that calls vPortYield() which wraps the FromISR code.
It doesn't appear that vPortYieldFromISR() is intended to be publicly accessible in this port so
I've marked it as private to silence the warning.
event_create() also got flagged due to missing void in prototype.
Co-authored-by: Gaurav-Aggarwal-AWS <33462878+aggarg@users.noreply.github.com>
* Posix: Fix no task switching issue if a task ended
When the main function of a task exits, no task switching happened.
This is because all the remaining tasks are waiting on the condition
variable. The fix is to trigger a task switch and mark the exiting
task as "Dying" to be suspened and exited properly from the scheduler.
* Posix: Assert and stop if the Task function returned
* Posix: just assert if a task returned from its main function
Co-authored-by: alfred gedeon <alfred2g@hotmail.com>
* Posix: Free Idle task resources after ending the scheduler
In case of using Posix simulator and ending the scheduler, it does
not free the resources allocated by the idle task. This
causes the memory checkers (Valgrind, Address Sanitizers, ..) to
complain.
* Posix: Free the condition variable memory in the correct place
In case of deleting a task from another task, the deletion happens
immediately and the thread is canceled but the memory allocated by
the task condition variable is not freed. This causes the memory
checkers (Valgrind, Address sanitizers, ..) to complain.
* Posix: End Timer thread and free its resources after ending the scheduler
* Style: Change FreeRTOS websites in comments
* Style: Change freertos to FreeRTOS in comments
* Style: Remove broken link
Co-authored-by: Alfred Gedeon <gedeonag@amazon.com>
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.
Soren Ptak
Mikhail Paulyshka
Tony Josi
Chris Morgan
Ching-Hsin Lee
Michael Fairman
Zim Kalinowski
Gaurav-Aggarwal-AWS
chinglee-iot
Monika Singh
Kody Stribrny
jacky309
phelter
arshi016
Archit Gupta
Chris Copeland
0xjakob
alfred gedeon
Kevin Thibedeau
Paul Bartell
Evgeny Ermakov
Thomas Pedersen
Cobus van Eeden
alfred gedeon
David Chalco
Reda Maher
David Chalco
Alfred Gedeon
David Vrabel