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:

  1. Set the GN dir_pw_third_party_freertos to the path of the FreeRTOS installation.

  2. Set pw_third_party_freertos_CONFIG to a pw_source_set which provides the FreeRTOS config header.

  3. 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:

  1. Set dir_pw_third_party_freertos to the path of the FreeRTOS installation.

  2. Set pw_third_party_freertos_CONFIG to a library target which provides the FreeRTOS config header.

  3. Set pw_third_party_freertos_PORT to a library target which provides the FreeRTOS port specific includes and sources.

Bazel#

Pigweed provides its own BUILD.bazel file for FreeRTOS, at third_party/freertos/freertos.BUILD.bazel. You can use it directly in your WORKSPACE, like so:

http_archive(
   name = "freertos",
   build_file = "@pigweed//third_party/freertos:freertos.BUILD.bazel",
   sha256 = "89af32b7568c504624f712c21fe97f7311c55fccb7ae6163cda7adde1cde7f62",
   strip_prefix = "FreeRTOS-Kernel-10.5.1",
   urls = ["https://github.com/FreeRTOS/FreeRTOS-Kernel/archive/refs/tags/V10.5.1.tar.gz"],
)

The FreeRTOS build is configured through constraint_settings. The platform you are building for must specify values for the following settings:

  • @freertos//:port, to set which FreeRTOS port to use. You can select a value from those defined in third_party/freertos/freertos.BUILD.bazel (for example, @freertos//:port_ARM_CM4F).

  • @freertos//:malloc, to set which FreeRTOS malloc implementation to use. You can select a value from those defined in third_party/freertos/BUILD.bazel (for example, @freertos//:malloc_heap_1).

  • @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: @freertos//:disable_task_statics and @freertos//:no_disable_task_statics.

In addition, you need to set the @freertos//:freertos_config label flag to point to the library target providing the FreeRTOS config header. See Facades and backends tutorial for a discussion of how to work with our label flags.

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 @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 our configASSERT wrapper 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 OS support are provided for FreeRTOS via the following modules:

Backend group#

In GN, import pw_targets_FREERTOS_BACKEND_GROUP to set backends for pw_chrono, pw_sync, and pw_thread for FreeRTOS. The backends can be overridden individually if needed.

# Toolchain configuration
import("$dir_pigweed/targets/common/freertos.gni")

_backend_setting_example = {
  # Since this target is using FreeRTOS, adopt FreeRTOS backends by default.
  forward_variables_from(pw_targets_FREERTOS_BACKEND_GROUP, "*")

  # Set other backends or override the default FreeRTOS selections if needed.
  ...
}

configASSERT and pw_assert#

To make it easier to use 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.

// Instead of defining configASSERT, simply include this header in its place.
#include "pw_third_party/freertos/config_assert.h"

FreeRTOS application function implementations#

group FreeRTOS_application_functions

FreeRTOS requires the application to implement certain functions, depending on its configuration.

If static allocation (configSUPPORT_STATIC_ALLOCATION) is enabled and configKERNEL_PROVIDED_STATIC_MEMORY is disabled, FreeRTOS requires applications to implement functions that provide static memory for the idle task and timer task. See https://www.freertos.org/a00110.html for details.

Link against "//third_party/freertos:support" to include these function implementations.

Functions

void vApplicationStackOverflowHook(TaskHandle_t, char *pcTaskName)#

If configCHECK_FOR_STACK_OVERFLOW is enabled, FreeRTOS requires applications to implement vApplicationStackOverflowHook, which is called when a stack overflow is detected. This implementation invokes PW_CRASH with the task name.

void vApplicationGetIdleTaskMemory(
StaticTask_t **ppxIdleTaskTCBBuffer,
StackType_t **ppxIdleTaskStackBuffer,
uint32_t *pulIdleTaskStackSize,
)#

Allocates static memory for the idle task. Provides a configMINIMAL_STACK_SIZE stack.

void vApplicationGetTimerTaskMemory(
StaticTask_t **ppxTimerTaskTCBBuffer,
StackType_t **ppxTimerTaskStackBuffer,
uint32_t *pulTimerTaskStackSize,
)#

Allocates static memory for the timer task. Provides a configTIMER_TASK_STACK_DEPTH stack.

On this page