CMSIS-FreeRTOS  Version 10.2.0
CMSIS-RTOS2 compliant FreeRTOS Implementation
 All Functions Groups Pages
Create a FreeRTOS project

You can basically choose between two option when creating a FreeRTOS project:

  1. Create a native FreeRTOS project using the FreeRTOS API and kernel.
  2. Create a CMSIS-FreeRTOS project using the CMSIS-RTOS2 API with an underlying FreeRTOS kernel.

Create a native FreeRTOS project

The steps to create a microcontroller application using FreeRTOS are:

  • Create a new project and select a microcontroller device.
  • In the Manage Run-Time Environment window, select ::Device:Startup, ::RTOS:CORE and ::RTOS:Config in the FreeRTOS variant and an applicable ::RTOS:Heap scheme (for more information on the heap schemes, visit the FreeRTOS documentation):

    manage_rte_freertos_native.png


  • If the Validation Output requires other components to be present, try to use the Resolve button.
  • Click OK. In the Project window, you will see the files that have been automatically added to you project, such as FreeRTOSConfig.h, the source code files, as well as the system and startup files:

    project_window_freertos_native.png

Configure FreeRTOS

When you have created the native FreeRTOS project, you can configure the real-time operating system using the FreeRTOSConfig.h file. Please refer to the FreeRTOS documentation for more information on the specific settings.

freertos_config_h_native.png

Add Event Recorder Visibility

  • To use the Event Recorder together with FreeRTOS, add the software component ::Compiler:Event Recorder to your project.
  • Open FreeRTOSConfig.h and
    • verify the header file freertos_evr.h is included
    • add Event Recorder configuration definitions (see Configure Event Recorder)
  • Call EvrFreeRTOSSetup() in your application code (ideally in main()).
  • If you are using simulation mode, add an initialization file with the following content:
    MAP 0xE0001000, 0xE0001007 READ WRITE
    signal void DWT_CYCCNT (void) {
    while (1) {
    rwatch(0xE0001004);
    _WWORD(0xE0001004, states);
    }
    }
    DWT_CYCCNT()
  • Build the application code and download it to the debug hardware or run it in simulation.

Once the target application generates event information, it can be viewed in the µVision debugger using the Event Recorder.

Create a CMSIS-FreeRTOS project

The steps to create a microcontroller application using CMSIS-FreeRTOS are:

  • Create a new project and select a microcontroller device.
  • In the Manage Run-Time Environment window, select ::Device:Startup, ::CMSIS::RTOS2 (API)::FreeRTOS, ::RTOS:CORE in the FreeRTOS variant, ::RTOS:Config in the CMSIS RTOS2 variant, ::RTOS:Timers, ::RTOS:Event Groups, and an applicable ::RTOS:Heap scheme (for more information on the heap schemes, visit the FreeRTOS documentation):

    manage_rte_freertos_rtos2.png


  • If the Validation Output requires other components to be present, try to use the Resolve button.
  • Click OK. In the Project window, you will see the files that have been automatically added to you project, such as FreeRTOSConfig.h, the source code files, as well as the system and startup files:

    project_window_freertos_rtos2.png

Configure CMSIS-FreeRTOS

When you have created the CMSIS-FreeRTOS project, you can configure the real-time operating system using the FreeRTOSConfig.h file. It can be opened using the Configuration Wizard view:

freertos_config_h_cmsis_rtos.png

The following settings are available:

Name #define Description
Minimal stack size [words] configMINIMAL_STACK_SIZE Stack for idle task and default task stack in words.
Total heap size [bytes] configTOTAL_HEAP_SIZE Heap memory size in bytes.
Kernel tick frequency [Hz] configTICK_RATE_HZ Kernel tick rate in Hz.
Timer task stack depth [words] configTIMER_TASK_STACK_DEPTH Stack for timer task in words.
Timer task priority configTIMER_TASK_PRIORITY Timer task priority.
Timer queue length configTIMER_QUEUE_LENGTH Timer command queue length.
Preemption interrupt priority configMAX_SYSCALL_INTERRUPT_PRIORITY Maximum priority of interrupts that are safe to call FreeRTOS API.
Use time slicing configUSE_TIME_SLICING Enable setting to use time slicing.
Idle should yield configIDLE_SHOULD_YIELD Control Yield behavior of the idle task.
Check for stack overflow configCHECK_FOR_STACK_OVERFLOW Enable or disable stack overflow checking.
Use idle hook configUSE_IDLE_HOOK Enable callback function call on each idle task iteration.
Use tick hook configUSE_TICK_HOOK Enable callback function call during each tick interrupt.
Use daemon task startup hook configUSE_DAEMON_TASK_STARTUP_HOOK Enable callback function call when timer service starts.
Use malloc failed hook configUSE_MALLOC_FAILED_HOOK Enable callback function call when out of dynamic memory.
Queue registry size configQUEUE_REGISTRY_SIZE Define maximum number of queue objects registered for debug purposes.

Event Recorder Configuration

The following settings are available (see Configure Event Recorder for details):

Name #define Description
Initialize Event Recorder configEVR_INITIALIZE Initialize Event Recorder before FreeRTOS kernel start.
Setup recording level filter configEVR_SETUP_LEVEL Enable configuration of FreeRTOS events recording level.
Task functions configEVR_LEVEL_TASKS Define event recording level bitmask for events generated from Tasks functions.
Queue functions configEVR_LEVEL_QUEUE Define event recording level bitmask for events generated from Queue functions.
Timer functions configEVR_LEVEL_TIMERS Define event recording level bitmask for events generated from Timer functions.
Event Groups functions configEVR_LEVEL_EVENTGROUPS Define event recording level bitmask for events generated from Event Groups functions.
Heap functions configEVR_LEVEL_HEAP Define event recording level bitmask for events generated from Heap functions.
Stream Buffer functions configEVR_LEVEL_STREAMBUFFER Define event recording level bitmask for events generated from Stream Buffer functions.

Add Event Recorder Visibility

  • To use the Event Recorder together with FreeRTOS, add the software component ::Compiler:Event Recorder to your project.
  • Open FreeRTOSConfig.h and
    • verify the header file freertos_evr.h is included
    • modify Event Recorder configuration definitions (see Configure Event Recorder) to change default configuration
  • Call osKernelInitialize() in your application code (ideally in main()) to setup Event Recorder according to configuration settings.
  • If you are using simulation mode, add an initialization file with the following content:
    MAP 0xE0001000, 0xE0001007 READ WRITE
    signal void DWT_CYCCNT (void) {
    while (1) {
    rwatch(0xE0001004);
    _WWORD(0xE0001004, states);
    }
    }
    DWT_CYCCNT()
  • Build the application code and download it to the debug hardware or run it in simulation.

Once the target application generates event information, it can be viewed in the µVision debugger using the Event Recorder.

Configure Event Recorder

This section describes the configuration settings for the Event Recorder annotations. For more information refer to section Add Event Recorder Visibility to native FreeRTOS project or Add Event Recorder Visibility to CMSIS-FreeRTOS project.

Use below definitions to configure Event Recorder initialization and recording level filter setup.

#define configEVR_INITIALIZE
Value Description
0 Disable Event Recorder initialization
1 Enable Event Recorder initialization

Definition configEVR_INITIALIZE enables Event Recorder initialization during execution of function EvrFreeRTOSSetup. Default value is 1.

#define configEVR_SETUP_LEVEL
Value Description
0 Disable recording level filter setup
1 Enable recording level filter setup

Definition configEVR_SETUP_LEVEL enables setup of recording level filter for events generated by FreeRTOS. Recording level is configured during execution of function EvrFreeRTOSSetup. Default value is 1.

#define configEVR_LEVEL_TASKS
#define configEVR_LEVEL_QUEUE
#define configEVR_LEVEL_TIMERS
#define configEVR_LEVEL_EVENTGROUPS
#define configEVR_LEVEL_HEAP
#define configEVR_LEVEL_STREAMBUFFER
Value Description
0x00 Disable event generation
0x01 Enable generation of error events
0x05 Enable generation of error and operational events
0x0F Enable generation of all events

Definitions configEVR_LEVEL_x set the recording level bitmask for events generated by each function group. They are taken into account only when recording level filter setup is enabled. Default value is 0x05.