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 123Backend group 124============= 125In GN, import ``pw_targets_FREERTOS_BACKEND_GROUP`` to set backends for 126:ref:`module-pw_chrono`, :ref:`module-pw_sync`, and :ref:`module-pw_thread` for 127FreeRTOS. The backends can be overridden individually if needed. 128 129.. code-block:: none 130 131 # Toolchain configuration 132 import("$dir_pigweed/targets/common/freertos.gni") 133 134 _backend_setting_example = { 135 # Since this target is using FreeRTOS, adopt FreeRTOS backends by default. 136 forward_variables_from(pw_targets_FREERTOS_BACKEND_GROUP, "*") 137 138 # Set other backends or override the default FreeRTOS selections if needed. 139 ... 140 } 141 142.. _third_party-freertos_config_assert: 143 144-------------------------- 145configASSERT and pw_assert 146-------------------------- 147To make it easier to use :ref:`module-pw_assert` with FreeRTOS a helper header 148is provided under ``pw_third_party/freertos/config_assert.h`` which defines 149``configASSERT`` for you using Pigweed's assert system for your 150``FreeRTOSConfig.h`` if you chose to use it. 151 152.. code-block:: cpp 153 154 // Instead of defining configASSERT, simply include this header in its place. 155 #include "pw_third_party/freertos/config_assert.h" 156 157--------------------------------------------- 158FreeRTOS application function implementations 159--------------------------------------------- 160.. doxygengroup:: FreeRTOS_application_functions 161