/*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/ /** \mainpage Introduction FreeRTOS is one of the market leading real-time operating systems (RTOS) for embedded microcontrollers. It is professionally developed, strictly quality controlled, robust, supported, free to use in commercial products without a requirement to expose proprietary source code, and has no IP infringement risk. CMSIS-RTOS v2 is a common API for real-time operating systems (RTOS). It provides a standardized programming interface that is portable to many RTOS and enables software components that can work across multiple RTOS systems. It supports the Armv8-M architecture, dynamic object creation, for multi-core systems, and has a binary compatible interface across ABI compliant compilers. Using this software pack, users can choose between a native FreeRTOS implementation or one that is adhering to the CMSIS-RTOS2 API and using FreeRTOS under the hood. The CMSIS-RTOS2 API enables programmers to create portable application code to be used with different RTOS kernels (for example Keil RTX5). This documentation shows you: - how to \ref cre_freertos_proj "create a new microcontroller project" using FreeRTOS from scratch. - Various \ref examples show you the usage of FreeRTOS in native and CMSIS-RTOS2 mode. - the \ref tech_data of this implementation. \section License License The CMSIS-FreeRTOS implementation is provided free of charge by Arm under the FreeRTOS license. \section CMFR_Pack_Content ARM::CMSIS-FreeRTOS Pack The ARM::CMSIS-FreeRTOS pack contains the following: File/Directory |Content :--------------------------|:--------------------------------------------------------------------------------- \b ARM.CMSIS-FreeRTOS.pdsc | Package description file in CMSIS-Pack format. \b License | FreeRTOS license agreement. \b CMSIS | CMSIS-RTOS2 compliant implementation of FreeRTOS. \b Config | FreeRTOS configuration header file. \b Demo | FreeRTOS demo projects. \b Documentation | This documentation. \b DoxyGen | Source of the documentation. \b Source | FreeRTOS source code. \b Utilities | Utilities to build the pack. */ /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/ /** \page cm_revisionHistory Revision History
10.0.2-dev4

FreeRTOS V10.1.1

Maintenance release for CMSIS 5.4.0:

  • Updated ARM standard C library interface
  • Added reset option for \ref EvrFreeRTOSSetup
10.0.2-dev3

FreeRTOS V10.1.1

Maintenance release for CMSIS 5.4.0:

  • Added Event Recorder configuration
  • Corrected CMSIS-FreeRTOS component viewer linked list processing
10.0.2-dev2

FreeRTOS V10.1.1

Maintenance release for CMSIS 5.4.0:

  • RTOS2 API 2.1.3
  • Corrected osDelayUntil execution duration
  • Corrected SysTick_Handler when kernel not started
  • Corrected critical section for osKernelGetSysTimerCount
10.0.1

FreeRTOS V10.0.0

Maintenance release for CMSIS 5.3.0:

  • RTOS2 API 2.1.2
  • OS Tick API 1.0.1
  • Enhanced context switch response latency for API calls from ISR.
  • Enhanced debug awareness in SCVD.
9.1.0

FreeRTOS 9.0.0

Maintenance release for CMSIS 5.1.0:

  • Added support for ARM Compiler 6 (Limitations: Not available for Cortex-M0!)
  • Updated Cortex-A example to use IRQ Controller component
  • Corrected stack size allocation in RTOS2 osThreadNew function
  • Added support for OS Tick component
  • Added documentation for configuration options (native/CMSIS-RTOS2)
  • Debug event TaskIncrementTick level set to Detail
9.0.0 Initial release
*/ /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/ /** \page cre_freertos_proj Create a FreeRTOS project You can basically choose between two option when creating a FreeRTOS project: -# \ref native_freertos using the FreeRTOS API and kernel. -# \ref cmsis_freertos using the CMSIS-RTOS2 API with an underlying FreeRTOS kernel. \section native_freertos 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 \b FreeRTOS variant and an applicable \::RTOS:Heap scheme (for more information on the heap schemes, visit the FreeRTOS documentation): \image html manage_rte_freertos_native.png \n - If the Validation Output requires other components to be present, try to use the \b Resolve button. - Click \b OK. In the \b Project window, you will see the files that have been automatically added to you project, such as \b %FreeRTOSConfig.h, the source code files, as well as the system and startup files: \image html project_window_freertos_native.png \subsection native_freertos_config Configure FreeRTOS When you have created the native FreeRTOS project, you can configure the real-time operating system using the \b FreeRTOSConfig.h file. Please refer to the FreeRTOS documentation for more information on the specific settings. \image html freertos_config_h_native.png \subsection native_freertos_er Add Event Recorder Visibility - To use the Event Recorder together with FreeRTOS, add the software component \::Compiler:Event Recorder to your project. - Open \ref native_freertos_config "FreeRTOSConfig.h" and - verify the header file \b freertos_evr.h is included - add Event Recorder configuration definitions (see \ref cmsis_freertos_evr_config) - Call EvrFreeRTOSSetup() in your application code (ideally in \c main()). - If you are using simulation mode, add an initialization file with the following content: \code MAP 0xE0001000, 0xE0001007 READ WRITE signal void DWT_CYCCNT (void) { while (1) { rwatch(0xE0001004); _WWORD(0xE0001004, states); } } DWT_CYCCNT() \endcode - 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. \section cmsis_freertos 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 \b FreeRTOS variant, \::RTOS:Config in the \b CMSIS \b RTOS2 variant, \::RTOS:Timers, \::RTOS:Event Groups, and an applicable \::RTOS:Heap scheme (for more information on the heap schemes, visit the FreeRTOS documentation): \image html manage_rte_freertos_rtos2.png \n - If the Validation Output requires other components to be present, try to use the \b Resolve button. - Click \b OK. In the \b Project window, you will see the files that have been automatically added to you project, such as \b %FreeRTOSConfig.h, the source code files, as well as the system and startup files: \image html project_window_freertos_rtos2.png \subsection cmsis_freertos_config Configure CMSIS-FreeRTOS When you have created the CMSIS-FreeRTOS project, you can configure the real-time operating system using the \b FreeRTOSConfig.h file. It can be opened using the Configuration Wizard view: \image html 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 \ref cmsis_freertos_evr_config 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. | \subsection cmsis_freertos_er Add Event Recorder Visibility - To use the Event Recorder together with FreeRTOS, add the software component \::Compiler:Event Recorder to your project. - Open \ref native_freertos_config "FreeRTOSConfig.h" and - verify the header file \b freertos_evr.h is included - modify Event Recorder configuration definitions (see \ref cmsis_freertos_evr_config) to change default configuration - Call osKernelInitialize() in your application code (ideally in \c main()) to setup Event Recorder according to configuration settings. - If you are using simulation mode, add an initialization file with the following content: \code MAP 0xE0001000, 0xE0001007 READ WRITE signal void DWT_CYCCNT (void) { while (1) { rwatch(0xE0001004); _WWORD(0xE0001004, states); } } DWT_CYCCNT() \endcode - 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. \section cmsis_freertos_evr_config Configure Event Recorder This section describes the configuration settings for the Event Recorder annotations. For more information refer to section \ref native_freertos_er "Add Event Recorder Visibility to native FreeRTOS project" or \ref cmsis_freertos_er "Add Event Recorder Visibility to CMSIS-FreeRTOS project". Use below definitions to configure Event Recorder initialization and recording level filter setup. \code #define configEVR_INITIALIZE \endcode Value | Description | -------|---------------------------------------| 0 | Disable Event Recorder initialization | 1 | Enable Event Recorder initialization | Definition configEVR_INITIALIZE enables Event Recorder initialization during execution of function \ref EvrFreeRTOSSetup. Default value is \token{1}. \code #define configEVR_SETUP_LEVEL \endcode 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 \ref EvrFreeRTOSSetup. Default value is \token{1}. \code #define configEVR_LEVEL_TASKS #define configEVR_LEVEL_QUEUE #define configEVR_LEVEL_TIMERS #define configEVR_LEVEL_EVENTGROUPS #define configEVR_LEVEL_HEAP #define configEVR_LEVEL_STREAMBUFFER \endcode 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 \token{0x05}. */ /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/ /** \page examples Example projects This pack contains two example projects: - \ref examples_native - \ref examples_cmsis The first example shows how to use FreeRTOS standalone, whereas the second example shows how to use the CMSIS-RTOS2 API with an underlying FreeRTOS. The examples simulate a step-motor driver. Four phase variables are simulating the activation of the four output driver stages. The state changes are shown in the Watch window variable \c g_phases. All four phases are displayed in the Logic Analyzer: \image html blinky_example_simu.png \section examples_native Blinky example using FreeRTOS natively This example shows how to use FreeRTOS natively in a µVision project. This makes your code portable and you can choose to use a different RTOS kernel anytime during development (even only for evaluation purposes). To open the example, go to Pack Installer, select \b ARM in the \b Devices tab, and click on \b Copy next to the Native FreeRTOS Blinky (uVision Simulator) project on the \b Examples tab. Select the location on your hard drive where you want to copy the project to and press OK. µVision opens. \section examples_cmsis Blinky example using CMSIS-FreeRTOS This example shows how to use the CMSIS-RTOS2 API with an underlying FreeRTOS. This makes your code portable and you can choose to use a different RTOS kernel anytime during development (even only for evaluation purposes). To open the example, go to Pack Installer, select \b ARM in the \b Devices tab, and click on \b Copy next to the CMSIS-RTOS2 FreeRTOS Blinky (uVision Simulator) project on the \b Examples tab. Select the location on your hard drive where you want to copy the project to and press OK. µVision opens. \section examples_cmsis_a9 Blinky example using CMSIS-FreeRTOS running on Arm Cortex-A9 This example shows how to use the CMSIS-RTOS2 API with an underlying FreeRTOS running on an NXP i.MX6 equipped with an Arm Cortex-A9 code. This example only works in DS-MDK, the Eclipse-based development environment from Arm. For information on setting up the target connection, please refer to NXP i.MX 6SoloX SABRE Reference. \note you need to have the i.MX6 device family pack installed to see the example in the \b Examples tab of Pack Installer. To open the example, open the Pack Installer perspective, select \b NXP in the \b Devices tab, and click on \b Copy next to the CMSIS-RTOS2 FreeRTOS Blinky CA9 (MCIMX6SX-SABRE) project on the \b Examples tab. \image html copy_a9_example.png Confirm the default location in the Eclipse Workspace by pressing Copy. \image html copy_a9_example_ws.png Right-click on the project and select \b Build \b Project. Then, right-click on the project and select \b Debug \b As and then \b Debug \b Configurations. The Debug Configurations dialog opens: \image html dbg_conf.png The project is already set up for running from the SDRAM of the i.MX6 SABRE board. Press \b Debug. DS-MDK will switch to the debug perspective. After a successful connection to the target, press \b F8 to run the application. In the \b App \b Console you will see the output of the phases: \image html dbg_output.png */ /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/ /** \page tech_data Technical data and limitations This lists the technical data of CMSIS-FreeRTOS. \section td_limitations Limitations The following list briefly describes the limitations and unsupported features of the CMSIS-RTOS2 wrapper for FreeRTOS: - Static memory allocation will only work if \a all memory (from attributes structure) is provided statically. In order to allocate object memory statically, you need to: - provide the memory for control blocks and stack in the \c osThreadAttr_t structure for threads. - provide the memory for control blocks and message data in the \c osMessageQueueAttr_t structure for memory queues. - provide the memory for control blocks for other objects in the object's attributes structure. - Each timer object requires additional 8 bytes of dynamic memory. - \c osKernelSuspend and \c osKernelResume are not supported. - \c osKernelGetTickCount is limited to a 32-bit return value. - \c osThreadDetach, \c osThreadJoin() and attribute \c osThreadJoinable are not supported (\c osThreadNew returns NULL when osThreadJoinable attribute is specified). - \c osThreadGetStackSize is not implemented. - Event flags are limited to 24 bits. - \c osEventFlagsGetName is not implemented. - \c osEventFlagsWait cannot be called from an ISR. - Priority inherit protocol is used as default mutex behavior (\c osMutexNew creates priority inherit mutex object by default and ignores \c osMutexPrioInherit attribute when specified). - Robust mutex objects are not supported (\c osMutexNew returns NULL when \c osMutexRobust attribute is specified). - \c osMutexGetName is not implemented and always returns NULL. - \c osSemaphoreGetName is not implemented and always returns NULL. - Memory Pool functions are not implemented and will always return with error. - \c osMessageQueueGetName is not implemented and always returns NULL. - \c osMessageQueuePut and \c osMessageQueueGet always ignore message priority. \section td_validation CMSIS-RTOS validation suite results CMSIS provides a validation suite that can be used to test a real-time operating system for compliance to the standard. The test suite has been run successfully on the CMSIS-FreeRTOS implementation with the following exceptions: \b TC_ThreadParam: - Reason: unsupported feature - Test attempts to test \c osThreadJoin and \c osThreadDetach functions for invalid parameter input. These two functions are not implemented. \b TC_ThreadInterrupts: - Reason: unsupported feature - Test attempts to call \c osThreadJoin and \c osThreadDetach from the ISR. These two functions are not implemented. \b TC_EventFlagsInterrupts: - Reason: unsupported feature - Test attempts to call \c osEventFlagsWait from the ISR. Wrapper implementation does not allow function \c osEventFlagsWait to be called from interrupts. \b TC_MutexRobust: - Reason: unsupported feature - Test attempts to create robust mutex. FreeRTOS implementation does not support robust mutexes. \b TC_MutexOwnership: - Reason: unsupported feature - Test attempts to release a mutex from a thread which is not the mutex owner. Test fails, because FreeRTOS implementation does not verify ownership on mutex release. */ /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/ /** \page functionOverview Function Overview \section rtos_api2 CMSIS-RTOS2 API Overview of all CMSIS-RTOS C API v2 functions that are implemented in CMSIS-FreeRTOS. Kernel Information and Control ------------------------------ - \b osKernelGetInfo: supported - \b osKernelGetState: supported - \b osKernelGetSysTimerCount: supported - \b osKernelGetSysTimerFreq: supported - \b osKernelInitialize: supported - \b osKernelLock: supported - \b osKernelUnlock: supported - \b osKernelRestoreLock: supported - \b osKernelResume: \token{not implemented} - \b osKernelStart: supported - \b osKernelSuspend: \token{not implemented} - \b osKernelGetTickCount: limited to 32-bit return value. - \b osKernelGetTickFreq: supported Thread Management ----------------- - \b osThreadDetach: \token{not implemented} - \b osThreadEnumerate: supported - \b osThreadExit: supported - \b osThreadGetCount: supported - \b osThreadGetId: supported - \b osThreadGetName: supported - \b osThreadGetPriority: supported - \b osThreadGetStackSize: \token{not implemented} - \b osThreadGetStackSpace: supported - \b osThreadGetState: supported - \b osThreadJoin: \token{not implemented} - \b osThreadNew: supported - \b osThreadResume: supported - \b osThreadSetPriority: supported - \b osThreadSuspend: supported - \b osThreadTerminate: supported - \b osThreadYield: supported Thread Flags ------------ - \b osThreadFlagsSet: supported - \b osThreadFlagsClear: supported - \b osThreadFlagsGet: supported - \b osThreadFlagsWait: supported Event Flags ----------- All event flags are limited to 24 bits. - \b osEventFlagsGetName: \token{not implemented} - \b osEventFlagsNew: supported - \b osEventFlagsDelete: supported - \b osEventFlagsSet: supported - \b osEventFlagsClear: supported - \b osEventFlagsGet: supported - \b osEventFlagsWait: cannot be called from an ISR. Generic Wait Functions ---------------------- - \b osDelay: supported - \b osDelayUntil: supported Timer Management ---------------- - \b osTimerDelete: supported - \b osTimerGetName: supported - \b osTimerIsRunning: supported - \b osTimerNew: supported - \b osTimerStart: supported - \b osTimerStop: supported Mutex Management ---------------- Priority inherit protocol is used as default mutex behavior (osMutexNew creates priority inherit mutex object by default and ignores osMutexPrioInherit attribute when specified).\n Robust mutex objects are not supported (osMutexNew returns NULL when osMutexRobust attribute is specified). - \b osMutexAcquire: supported - \b osMutexDelete: supported - \b osMutexGetName: \token{not implemented} - \b osMutexGetOwner: supported - \b osMutexNew: supported - \b osMutexRelease: supported Semaphores ---------- - \b osSemaphoreAcquire: supported - \b osSemaphoreDelete: supported - \b osSemaphoreGetCount: supported - \b osSemaphoreGetName: \token{not implemented} - \b osSemaphoreNew: supported - \b osSemaphoreRelease: supported Memory Pool ----------- Memory Pool functions are not implemented and will always return with error. - \b osMemoryPoolAlloc: \token{not implemented} - \b osMemoryPoolDelete: \token{not implemented} - \b osMemoryPoolFree: \token{not implemented} - \b osMemoryPoolGetBlockSize: \token{not implemented} - \b osMemoryPoolGetCapacity: \token{not implemented} - \b osMemoryPoolGetCount: \token{not implemented} - \b osMemoryPoolGetName: \token{not implemented} - \b osMemoryPoolGetSpace: \token{not implemented} - \b osMemoryPoolNew: \token{not implemented} Message Queue ------------- - \b osMessageQueueDelete: supported - \b osMessageQueueGet: ignores message priority. - \b osMessageQueueGetCapacity: supported - \b osMessageQueueGetCount: supported - \b osMessageQueueGetMsgSize: supported - \b osMessageQueueGetName: \token{not implemented} - \b osMessageQueueGetSpace: supported - \b osMessageQueueNew: supported - \b osMessageQueuePut: ignores message priority. - \b osMessageQueueReset: supported */ /* ======================================================================================================================== */ // Group creation for Reference /** \addtogroup freertos_specific CMSIS-FreeRTOS Specifics \brief This section describes CMSIS-FreeRTOS specifics. \details CMSIS-FreeRTOS interfaces to the Event Recorder to provide event information which helps you to understand and analyze the operation. Refer to \ref freertos_evr for more information. */