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