Configuration and linking FreeRTOS

FreeRTOS needs configuration. It needs a FreeRTOSConfig.h header file that defines various application-specific configuration parameters for the kernel, such as the tick rate, stack size, and other settings.

Copy two files from the Pico examples to your project’s directory, specifically:

• FreeRTOSConfig.h and
• FreeRTOSConfig_examples_common.h.

These files contain the necessary configuration code for FreeRTOS to run on the Pico platform. You might want to remove the “examples” moniker from the common header file name since it’s no longer an example; up to you.

Next, add the following line to your CMakeLists.txt file to include FreeRTOS in your build:

# Pull in FreeRTOS-Kernel
set(FREERTOS_KERNEL_IMPORT_CMAKE
    ${CMAKE_CURRENT_LIST_DIR}/FreeRTOS-Kernel/portable/ThirdParty/GCC/RP2350_ARM_NTZ/FreeRTOS_Kernel_import.cmake)
if(EXISTS ${FREERTOS_KERNEL_IMPORT_CMAKE})
    include(${FREERTOS_KERNEL_IMPORT_CMAKE})
else()
    message(FATAL_ERROR
        "Missing FreeRTOS kernel import file: ${FREERTOS_KERNEL_IMPORT_CMAKE}\n"
        "The FreeRTOS-Kernel submodule may not be initialised.\n"
        "Run: git submodule update --init --recursive")
endif()

This code checks for the existence of the FreeRTOS kernel import file and includes it in the build process. If the file is missing, it raises a fatal error with instructions on how to initialise the submodule.

Finally, link the firmware’s executable target to the FreeRTOS kernel by adding its target libraries to your firmware target’s link libraries:

# Link the FreeRTOS kernel to the firmware executable
target_link_libraries(FreeRTOS-on-RP2350
    PRIVATE
        FreeRTOS-Kernel-Heap4
        pico_stdlib)

This completes the FreeRTOS-Pico SDK integration. You can now start developing your FreeRTOS application on the RP2350 using the Pico SDK. You can use the FreeRTOS API to create tasks, manage synchronisation, and utilise the RTOS features while still leveraging the hardware capabilities of the RP2350 through the Pico SDK.

Fetching as a build dependency

There is an alternative: using CMake’s FetchContent module to pull in the FreeRTOS kernel during the build step. This approach avoids the need to manage the FreeRTOS kernel as a Git submodule, but it does require an active internet connection during the build process. To use FetchContent, add the following code to your CMakeLists.txt file:

# Download FreeRTOS
include(FetchContent)
FetchContent_Declare(freertos_kernel
  GIT_REPOSITORY https://github.com/raspberrypi/FreeRTOS-Kernel.git
  GIT_TAG main # or specify a specific tag or commit
  SOURCE_SUBDIR portable/ThirdParty/GCC/RP2350_ARM_NTZ
)
FetchContent_MakeAvailable(freertos_kernel)

Note that the SOURCE_SUBDIR parameter specifies the FreeRTOS kernel subdirectory containing the files required for the RP2350 port. After fetching the FreeRTOS kernel, you can link it to your firmware target as before. Arguably, this is the easiest way to integrate FreeRTOS into your project. It obviates Git submodule management, but requires an active internet connection during a build.

High-resolution run-time statistics with DWT cycle counter

Ideally, this feature requires a high-resolution timer. The RP2350 has a built-in DWT cycle counter that can serve for this purpose. Each Cortex-M33 core equips its own Data Watchpoint and Trace (DWT) unit, which includes a cycle counter that can be used for high-resolution timing. To use the DWT cycle counter for run-time statistics, simply implement the portCONFIGURE_TIMER_FOR_RUN_TIME_STATS and portGET_RUN_TIME_COUNTER_VALUE macros as follows:

#include "hardware/structs/m33.h"

void m33_dwt_cyc_ena(void) {
  /*
   * Enable the DWT cycle counter. This is necessary for the clock to function
   * correctly, as it relies on the DWT cycle counter to provide the tick count.
   * The DWT cycle counter is typically disabled by default, so it must be
   * explicitly enabled before using this clock.
   */
  m33_hw->demcr |= M33_DEMCR_TRCENA_BITS;          /* Enable the DWT (Data Watchpoint and Trace) unit. */
  m33_hw->dwt_cyccnt = 0;                          /* Reset the cycle counter to start counting from 0. */
  m33_hw->dwt_ctrl |= M33_DWT_CTRL_CYCCNTENA_BITS; /* Enable the cycle counter. */
}

uint32_t m33_dwt_cyc_cnt(void) {
  /*
   * Return the current value of the DWT cycle counter. This provides a
   * high-resolution tick count based on the number of CPU cycles.
   */
  return m33_hw->dwt_cyccnt;
}

With this configuration, FreeRTOS will use the DWT cycle counter to gather run-time statistics, allowing the system to monitor the CPU time consumed by each task with high precision. Simply redefine the macros in the FreeRTOSConfig.h file to call these functions:

#define portCONFIGURE_TIMER_FOR_RUN_TIME_STATS()    m33_dwt_cyc_ena()
#define portGET_RUN_TIME_COUNTER_VALUE()            m33_dwt_cyc_cnt()

The FreeRTOS kernel will call portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() to set up the DWT cycle counter when the scheduler starts, and it will call portGET_RUN_TIME_COUNTER_VALUE() whenever it needs to retrieve the current tick count for run-time statistics. It’s important to note that the DWT cycle counter is a 32-bit counter, which means it will wrap around after a certain number of cycles. Depending on the clock speed of the RP2350, this could happen relatively quickly, so it’s essential to handle this wrap-around correctly in your application if you rely on the run-time statistics for long-running tasks.

Resolution too high

Could the DWT have too high a resolution for run-time statistics?

It depends on the application. For some applications, the high resolution provided by the DWT cycle counter may be beneficial for accurately measuring task execution times. However, for other applications, especially those with long-running tasks or those that do not require such precision, the DWT’s high resolution may lead to rapid wrap-around of the counter, which can complicate the interpretation of run-time statistics. In such cases, it may be more appropriate to use a lower-resolution timer or implement additional logic to handle the wrap-around effectively.

Scanning an I²C bus with Pico SDK

To implement an I²C bus scanner as a FreeRTOS task, the application needs a function to perform the scan. Here’s an example of how a Pico SDK-based application might implement this:

void i2c_scan(i2c_inst_t *i2c) {
  (void)printf("I2C%d Bus Scan\n"
               "   0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F\n",
               I2C_NUM(i2c));
  for (uint8_t addr = 0; addr < (1 << 7); ++addr) {
    if (addr % 0x10U == 0) {
      (void)printf("%02x ", addr);
    }
    int rc;
    /*
     * Address 0x00-0x07 and 0x78-0x7F are reserved for general call,
     * start byte, and high-speed mode and hence are not valid for
     * normal devices, so skip them in the scan to avoid false
     * positives.
     */
    if ((addr & 0x78U) == 0x00U || (addr & 0x78U) == 0x78U) {
      rc = PICO_ERROR_GENERIC;
    } else {
      uint8_t data[1];
      rc = i2c_read_blocking(i2c, addr, data, sizeof(data), false);
    }
    (void)printf("%s%s", rc < 0 ? "." : "@", addr % 0x10U == 0xfU ? "\n" : "  ");
  }
}

The code performs a scan of a given I²C bus by attempting to read a byte from each possible 7-bit address, \(00\) to \(7F\) hexadecimal. For each address, it checks if a device acknowledges the read request. If a device acknowledges, the function prints @; otherwise, a dot . is printed. The output is formatted in a way that shows the addresses in a grid, making it easier to identify which addresses are occupied by devices.

Pretty standard stuff for an I²C scanner. But there are some caveats to be aware of when running this in a FreeRTOS task. The i2c_read_blocking() function is a blocking call; it blocks in the worst way possible, by busy-waiting for the I²C transaction to complete. This means that while the task is performing the scan, it will not yield control to other tasks. The scan can take a significant amount of time to complete, especially if there are many devices on the bus or if the bus is slow. This can lead to a long blocking period for the task, which may affect the responsiveness of other tasks in the system.

It blocks the task, but it does not block the entire system. The FreeRTOS scheduler will still run other tasks on the other core while the scan is running, or even on the same core if there are other tasks with higher priority. Hence, the task has idle level priority, so it will yield to any other tasks that are ready to run. This allows the system to remain responsive even while the scan is running, as other tasks can still execute on the other core or on the same core if they have higher priority.

Initialising the I²C bus

The scan presumes that the I²C bus has been properly initialised. It does not happen automatically. You need to set up the I²C bus before creating the task. To initialise the I²C bus on the RP2350, you can use the following code:

  i2c_init(i2c1, 400 * 1000);
  gpio_set_function(I2C1_SDA, GPIO_FUNC_I2C);
  gpio_set_function(I2C1_SCL, GPIO_FUNC_I2C);
  gpio_pull_up(I2C1_SDA);
  gpio_pull_up(I2C1_SCL);

It initialises the I²C bus at a baud rate of 400 kHz, configures the GPIO pins for I²C functionality, and enables pull-up resistors on the SDA and SCL lines.

Scheduling an I²C scanner task

Next, wrap the scanning function in a FreeRTOS task function, and create a task that runs this function. For example:

static void prvI2CScannerTask(void *pvParameters) {
  i2c_inst_t *i2c = (i2c_inst_t *)pvParameters;
  for (;;) {
    i2c_scan(i2c);
    vTaskDelay(pdMS_TO_TICKS(1000));
  }
}

This task can be launched using the FreeRTOS API, and it will run concurrently with other tasks in the system, including tasks that perform other I²C operations. The scheduler will manage the execution of this task alongside any other tasks you create, ensuring that they all get a chance to run based on their priority and the scheduling algorithm; as follows.

  BaseType_t xResult = xTaskCreate(prvI2CScannerTask, "scanI2C1", configMINIMAL_STACK_SIZE, (void *)i2c1, tskIDLE_PRIORITY, NULL);
  configASSERT(xResult != pdFAIL);

After setting up the I²C bus, this code creates a FreeRTOS task to run the I²C scanner function. The task is created with a name “scanI2C1”, a minimal stack size, and a priority equal to the idle task. The I²C instance is passed as a parameter to the task function. The configASSERT macro is used to check if the task creation was successful. If the task creation fails, it will trigger an assertion failure; helps with debugging.