/*=======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
*/
/*=======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
\todo Do we add user code templates for the native FreeRTOS implementation?
- You can add template files to the project by right-clicking on Source Group 1 and selecting
Add New Item to 'Source Group 1'. In the new window, click on User Code Template. On the right-hand side
you will see all available template files for CMSIS-RTOS RTX:
\todo Do we offer an SCVD file for the native FreeRTOS implementation?
\subsection native_freertos_er Add Event Recorder Visibility
- To use the Event Recorder together with RTX5, select the software component Compiler:Event Recorder.
- Select the \b Source variant of the software component CMSIS:RTOS2 (API):Keil RTX5.
- Call the function EventRecorderInitialize() in your application code (ideally in \c main()).
- Build the application code and download it to the debug hardware.
Once the target application generates event information, it can be viewed in the µVision debugger using the \b Event
\b 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:FreeRTOS:Timers, \::RTOS:FreeRTOS: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
\todo Do we add user code templates for the RTOS2 FreeRTOS implementation?\
- You can add template files to the project by right-clicking on Source Group 1 and selecting
Add New Item to 'Source Group 1'. In the new window, click on User Code Template. On the right-hand side
you will see all available template files for CMSIS-RTOS RTX:
\todo Do we offer an SCVD file for the RTOS2 FreeRTOS implementation?
\subsection cmsis_freertos_er Add Event Recorder Visibility
- To use the Event Recorder together with RTX5, select the software component Compiler:Event Recorder.
- Select the \b Source variant of the software component CMSIS:RTOS2 (API):Keil RTX5.
- Call the function EventRecorderInitialize() in your application code (ideally in \c main()).
- Build the application code and download it to the debug hardware.
Once the target application generates event information, it can be viewed in the µVision debugger using the \b Event
\b Recorder.
*/
/*=======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.
*/
/*=======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 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.
*/
/*=======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
*/