1.. _module-pw_third_party_freertos: 2 3======== 4FreeRTOS 5======== 6 7The ``$dir_pw_third_party/freertos/`` module contains various helpers to use 8FreeRTOS, including Pigweed backend modules which depend on FreeRTOS. 9 10------------- 11Build Support 12------------- 13This module provides support to compile FreeRTOS with GN, CMake, and Bazel. 14This is required when compiling backends modules for FreeRTOS. 15 16GN 17== 18In order to use this you are expected to configure the following variables from 19``$dir_pw_third_party/freertos:freertos.gni``: 20 21#. Set the GN ``dir_pw_third_party_freertos`` to the path of the FreeRTOS 22 installation. 23#. Set ``pw_third_party_freertos_CONFIG`` to a ``pw_source_set`` which provides 24 the FreeRTOS config header. 25#. Set ``pw_third_party_freertos_PORT`` to a ``pw_source_set`` which provides 26 the FreeRTOS port specific includes and sources. 27 28After this is done a ``pw_source_set`` for the FreeRTOS library is created at 29``$dir_pw_third_party/freertos``. 30 31CMake 32===== 33In order to use this you are expected to set the following variables from 34``third_party/freertos/CMakeLists.txt``: 35 36#. Set ``dir_pw_third_party_freertos`` to the path of the FreeRTOS installation. 37#. Set ``pw_third_party_freertos_CONFIG`` to a library target which provides 38 the FreeRTOS config header. 39#. Set ``pw_third_party_freertos_PORT`` to a library target which provides 40 the FreeRTOS port specific includes and sources. 41 42Bazel 43===== 44Pigweed provides its own BUILD.bazel file for FreeRTOS, at 45``third_party/freertos/freertos.BUILD.bazel``. You can use it directly in 46your ``WORKSPACE``, like so: 47 48.. code-block:: python 49 50 http_archive( 51 name = "freertos", 52 build_file = "@pigweed//third_party/freertos:freertos.BUILD.bazel", 53 sha256 = "89af32b7568c504624f712c21fe97f7311c55fccb7ae6163cda7adde1cde7f62", 54 strip_prefix = "FreeRTOS-Kernel-10.5.1", 55 urls = ["https://github.com/FreeRTOS/FreeRTOS-Kernel/archive/refs/tags/V10.5.1.tar.gz"], 56 ) 57 58The FreeRTOS build is configured through `constraint_settings 59<https://bazel.build/reference/be/platforms-and-toolchains#constraint_setting>`_. 60The `platform <https://bazel.build/extending/platforms>`_ you are building for 61must specify values for the following settings: 62 63* ``@freertos//:port``, to set which FreeRTOS port to use. You can 64 select a value from those defined in 65 ``third_party/freertos/freertos.BUILD.bazel`` (for example, 66 ``@freertos//:port_ARM_CM4F``). 67* ``@freertos//:malloc``, to set which FreeRTOS malloc implementation to use. 68 You can select a value from those defined in 69 ``third_party/freertos/BUILD.bazel`` (for example, 70 ``@freertos//:malloc_heap_1``). 71* ``@freertos//:disable_task_statics_setting``, to determine whether statics 72 should be disabled during compilation of the tasks.c source file (see next 73 section). This setting has only two possible values, also defined in 74 ``third_party/freertos/BUILD.bazel``: ``@freertos//:disable_task_statics`` 75 and ``@freertos//:no_disable_task_statics``. 76 77In addition, you need to set the ``@freertos//:freertos_config`` label flag to 78point to the library target providing the FreeRTOS config header. See 79:ref:`docs-build_system-bazel_configuration` for a discussion of how to work 80with our label flags. 81 82 83.. _third_party-freertos_disable_task_statics: 84 85Linking against FreeRTOS kernel's static internals 86================================================== 87In order to link against internal kernel data structures through the use of 88extern "C", statics can be optionally disabled for the tasks.c source file 89to enable use of things like pw_thread_freertos/util.h's ``ForEachThread``. 90 91To facilitate this, Pigweed offers an opt-in option which can be enabled, 92 93* in GN through ``pw_third_party_freertos_DISABLE_TASKS_STATICS = true``, 94* in CMake through ``set(pw_third_party_freertos_DISABLE_TASKS_STATICS ON 95 CACHE BOOL "" FORCE)``, 96* in Bazel through ``@freertos//:disable_task_statics``. 97 98This redefines ``static`` to nothing for the ``Source/tasks.c`` FreeRTOS source 99file when building through ``$dir_pw_third_party/freertos`` in GN and through 100``pw_third_party.freertos`` in CMake. 101 102.. attention:: If you use this, make sure that your FreeRTOSConfig.h and port 103 does not rely on any statics inside of tasks.c. For example, you cannot use 104 ``PW_CHECK`` for ``configASSERT`` when this is enabled. 105 106As a helper ``PW_THIRD_PARTY_FREERTOS_NO_STATICS=1`` is defined when statics are 107disabled to help manage conditional configuration. 108 109We highly recommend :ref:`our configASSERT wrapper 110<third_party-freertos_config_assert>` when using this configuration, which 111correctly sets ``configASSERT`` to use ``PW_CHECK`` and ``PW_ASSERT`` for you. 112 113----------------------------- 114OS Abstraction Layers Support 115----------------------------- 116Support for Pigweed's :ref:`docs-os` are provided for FreeRTOS via the following 117modules: 118 119* :ref:`module-pw_chrono_freertos` 120* :ref:`module-pw_sync_freertos` 121* :ref:`module-pw_thread_freertos` 122 123.. _third_party-freertos_config_assert: 124 125-------------------------- 126configASSERT and pw_assert 127-------------------------- 128To make it easier to use :ref:`module-pw_assert` with FreeRTOS a helper header 129is provided under ``pw_third_party/freertos/config_assert.h`` which defines 130``configASSERT`` for you using Pigweed's assert system for your 131``FreeRTOSConfig.h`` if you chose to use it. 132 133.. code-block:: cpp 134 135 // Instead of defining configASSERT, simply include this header in its place. 136 #include "pw_third_party/freertos/config_assert.h" 137 138--------------------------------------------- 139FreeRTOS application function implementations 140--------------------------------------------- 141.. doxygengroup:: FreeRTOS_application_functions 142