Developing Applications on STM32Cube with RTOS

UM1722 User manual
Developing Applications on STM32Cube with RTOS
Introduction
The STMCubeTM initiative was originated by STMicroelectronics to ease developers life by reducing development efforts, time and cost. STM32Cube covers the STM32 portfolio. STM32Cube Version 1.x includes: ? ? The STM32CubeMX, a graphical software configuration tool that allows to generate C initialization code using graphical wizards. A comprehensive embedded software platform, delivered per series (namely, STM32CubeF4 for STM32F4 series) – – – The STM32Cube HAL, an STM32 abstraction layer embedded software, ensuring maximized portability across STM32 portfolio A consistent set of middleware components such as RTOS, USB, TCP/IP, Graphics All embedded software utilities coming with a full set of examples.
A Real Time Operating System is an operating system optimized for use in embedded/real time applications. Their primary objective is to ensure a timely and deterministic response to events. Using a real time operating system allows applications to be written as a set of independent threads that inter-communicate using message queues and semaphores. This user manual is intended for developers who use STM32Cube firmware on STM32 microcontrollers. It provides a full description of how to use the STM32Cube firmware components with a real time operating system (RTOS); this user manual comes also with description of a set of examples based on FreeRTOS using the common APIs provided by the CMSIS-OS wrapping layer. In the STM32Cube firmware FreeRTOS is used as real time operating system through the generic CMSIS-OS wrapping layer provided by ARM. Examples and applications using the FreeRTOS can be direcltly ported on any other RTOS without modifying the high level APIs, only the CMSIS-OS wrapper has to be changed in this case. Please refer to the release notes of the package to know the version of FreeRTOS and CMSIS-RTOS firmware components used with the STM32CubeTM. This document is applicable to all STM32 devices; however for simplicity reason, the STM32F4xx devices and STM32CubeF4 are used as reference platform. To know more about the examples implementation on your STM32 device, please refer to the readme file provided within the associated STM32Cube FW package.
June 2014
DocID025801 Rev 2
1/26
https://www.wendangku.net/doc/4f1865593.html,

Contents
UM1722
Contents
1 Free RTOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1 1.2 1.3 1.4 1.5 1.6 1.7 1.8 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Free RTOS source organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Porting FreeRTOS on STM32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 FreeRTOS API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 FreeRTOS memory management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 FreeRTOS low power . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 FreeRTOS configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
2
CMSIS-RTOS module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.1 2.2 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 CMSIS-RTOS API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3
FreeRTOS applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
3.1 3.2 Thread Creation example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Semaphores examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2.1 3.2.2 Semaphore between threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Semaphore from ISR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.3 3.4 3.5 3.6
Mutexes example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Queues example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Timer example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Low power example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4 5 6
Conclusions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2/26
DocID025801 Rev 2

UM1722
List of tables
List of tables
Table 1. Table 2. Table 3. Table 4. Table 5. Free RTOS API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 CMSIS-RTOS API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Free RTOS application categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Comparison of power consumption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Document revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
DocID025801 Rev 2
3/26
3

List of figures
UM1722
List of figures
Figure 1. Figure 2. Figure 3. Figure 4. Figure 5. Figure 6. Figure 7. Figure 8. Figure 9. Figure 10. FreeRTOS license . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Free RTOS architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Free RTOS port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 FreeRTOS configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 CMSIS-RTOS architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Thread example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Semaphore example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Obtaining semaphore from ISR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Queue process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Periodic timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4/26
DocID025801 Rev 2

UM1722
Free RTOS
1
1.1
Free RTOS
Overview
FreeRTOS is a class of RTOS that is designed to be small enough to run on a microcontroller, although its use is not limited to microcontroller applications. A microcontroller is a small and resource constrained processor that incorporates, on a single chip, the processor itself, read only memory (ROM or Flash) to hold the program to be executed, and the random access memory (RAM) needed by the programs it executes. Typically the program is executed directly from the read only memory. Microcontrollers are used in deeply embedded applications (those applications where you never actually see the processors themselves or the software they are running) that normally have a very specific and dedicated job to do. The size constraints, and dedicated end application nature, rarely warrant the use of a full RTOS implementation - or indeed make the use of a full RTOS implementation possible. FreeRTOS therefore provides the core real time scheduling functionality, inter-task communication, timing and synchronization primitives only. This means it is more accurately described as a real time kernel, or real time executive. Additional functionality, such as a command console interface, or networking stacks, can be then be included with add-on components. FreeRTOS is a scalable real time demonstration builder core designed specifically for small embedded systems. Highlights include ? ? ? ? ? ? ? Free RTOS demonstration builder core-preemptive, cooperative and hybrid configuration options. Official support for 27 architectures (counting ARM7 and ARM Cortex M3 as one architecture each). FreeRTOS-MPU supports the Cortex M3 Memory Protection Unit (MPU). Designed to be small, simple and easy to use. Typically a demonstration builder core binary image will be in the region of 4K to 9K bytes. Very portable code structure predominantly written in C. Supports both tasks and co-routines. Queues, binary semaphores, counting semaphores, recursive semaphores and mutexes for communication and synchronization between tasks, or between tasks and interrupts. Mutexes with priority inheritance. Supports efficient software timers. Powerful execution traces functionality. Stack overflows detection options. Pre-configured demo applications for selected single board computers allowing out of the box operation and fast learning curve. Free forum support, or optional commercial support and licensing. No software restriction on the number of tasks that can be created. No software restriction on the number of priorities that can be used. No restrictions imposed on priority assignment - more than one task can be assigned the same priority. Free development tools for many supported architectures.
? ? ? ? ? ? ? ? ? ?
DocID025801 Rev 2
5/26
25

Free RTOS ? ? ? Free embedded software source code. Royalty free. Cross development from a standard Windows host.
UM1722
The heap2 scheme of FreeRTOS is used for the memory allocation management, this scheme uses a best fit algorithm allows previously allocated blocks to be freed. It does not however combine adjacent free blocks into a single large block. The total amount of available RAM is set by the definition configTOTAL_HEAP_SIZE - which is defined in FreeRTOSConfig.h.
1.2
License
The FreeRTOS source code is licensed by a modified GNU General Public License. The modification takes the form of an exception. The full text of the GNU General Public License is shown here: Figure 1. FreeRTOS license
7KH)UHH5726RUJVRXUFHFRGHLVOLFHQVHGE\WKHPRGLILHG*18*HQHUDO3XEOLF /LFHQVH*3/

WH[WSURYLGHGEHORZ7KH)UHH5726GRZQORDGDOVRLQFOXGHV GHPRDSSOLFDWLRQVRXUFHFRGHVRPHRIZKLFKLVSURYLGHGE\WKLUGSDUWLHV $1',6/,&(16('6(3$5$7(/<)520)5((572625* )RUWKHDYRLGDQFHRIDQ\GRXEWUHIHUWRWKHFRPPHQWLQFOXGHGDWWKHWRS RIHDFKVRXUFHDQGKHDGHUILOHIRUOLFHQVHDQGFRS\ULJKWLQIRUPDWLRQ 7KLVLVDOLVWRIILOHVIRUZKLFK5HDO7LPH(QJLQHHUV/WGDUHQRWWKH FRS\ULJKWRZQHUDQGDUH127&29(5('%<7+(*3/


9DULRXVKHDGHUILOHVSURYLGHGE\VLOLFRQPDQXIDFWXUHUVDQGWRROYHQGRUV WKDWGHILQHSURFHVVRUVSHFLILFPHPRU\DGGUHVVHVDQGXWLOLW\PDFURV 3HUPLVVLRQKDVEHHQJUDQWHGE\WKHYDULRXVFRS\ULJKWKROGHUVIRUWKHVH ILOHVWREHLQFOXGHGLQWKH)UHH5726GRZQORDG8VHUVPXVWHQVXUHOLFHQVH FRQGLWLRQVDUHDGKHUHGWRIRUDQ\XVHRWKHUWKDQFRPSLODWLRQRIWKH )UHH5726GHPRDSSOLFDWLRQV 

7KHX,37&3,3VWDFNWKHFRS\ULJKWRIZKLFKLVKHOGE\$GDP'XQNHOV 8VHUVPXVWHQVXUHWKHRSHQVRXUFHOLFHQVHFRQGLWLRQVVWDWHGDWWKHWRS RIHDFKX,3VRXUFHILOHLVXQGHUVWRRGDQGDGKHUHGWR 

7KHOZ,37&3,3VWDFNWKHFRS\ULJKWRIZKLFKLVKHOGE\WKH6ZHGLVK ,QVWLWXWHRI&RPSXWHU6FLHQFH8VHUVPXVWHQVXUHWKHRSHQVRXUFHOLFHQVH FRQGLWLRQVVWDWHGDWWKHWRSRIHDFKOZ,3VRXUFHILOHLVXQGHUVWRRGDQG DGKHUHGWR 

9DULRXVSHULSKHUDOGULYHUVRXUFHILOHVDQGELQDULHVSURYLGHGE\VLOLFRQ PDQXIDFWXUHUVDQGWRROYHQGRUV3HUPLVVLRQKDVEHHQJUDQWHGE\WKH YDULRXVFRS\ULJKWKROGHUVIRUWKHVHILOHVWREHLQFOXGHGLQWKH)UHH5726 GRZQORDG8VHUVPXVWHQVXUHOLFHQVHFRQGLWLRQVDUHDGKHUHGWRIRUDQ\ XVHRWKHUWKDQFRPSLODWLRQRIWKH)UHH5726GHPRDSSOLFDWLRQV 

7KHILOHVFRQWDLQHGZLWKLQ)UHH5726?'HPR?:L]1(7B'(02B7(51B?WHUQBFRGH ZKLFKDUHVOLJKWO\PRGLILHGYHUVLRQVRIFRGHSURYLGHGE\DQGFRS\ULJKWWR 7HUQ,QF (UURUVDQGRPLVVLRQVVKRXOGEHUHSRUWHGWR5LFKDUG%DUU\FRQWDFWGHWDLOVIRU ZKRPFDQEHREWDLQHGIURPKWWSZZZ)UHH5726RUJ
7KH*3/OLFHQVHWH[WIROORZV $VSHFLDOH[FHSWLRQWRWKH*3/LVLQFOXGHGWRDOORZ\RXWRGLVWULEXWHD FRPELQHGZRUNWKDWLQFOXGHV)UHH5726ZLWKRXWEHLQJREOLJHGWRSURYLGH WKHVRXUFHFRGHIRUDQ\SURSULHWDU\FRPSRQHQWV6HHWKHOLFHQVLQJVHFWLRQ RIKWWSZZZ)UHH5726RUJIRUIXOOGHWDLOV7KHH[FHSWLRQWH[WLVDOVR LQFOXGHGDWWKHERWWRPRIWKLVILOH
6/26
DocID025801 Rev 2

UM1722
Free RTOS
1.3
Free RTOS source organization
The FreeRTOS download includes source code for every processor port, and every demonstration application. Placing all the ports in a single download greatly simplifies distribution, but the number of files may seem daunting. The directory structure is however very simple, and the FreeRTOS real time kernel is contained in just 4 files (additional files are required if software timer or co-routine functionality is required). Figure 2. Free RTOS architecture
)UHH5726
'HPR
6RXUFH
7DVNF
3RUWDEOH
4XHXHF &RPSLOHU /LVWF 3ODWIRUP ,??ě∥??? ??????????>???? ?,>?
3RUWF
The core RTOS code is contained in three files, called tasks.c, queue.c and list.c., in the FreeRTOS/Source directory. The same directory contains two optional files called timers.c and croutine.c which implement software timer and co-routine functionality. Each supported processor architecture requires a small amount of architecture specific RTOS code. This is the RTOS portable layer, located in the FreeRTOS/Source/Portable/[compiler]/[architecture] sub directories, where [compiler] and [architecture] are the compiler used to create the port, and the architecture on which the port runs, respectively. The sample heap allocation schemes are also located in the portable layer. The various sample heap_x.c files are located in the FreeRTOS/Source/portable/MemMang directory.
1.4
Porting FreeRTOS on STM32
FreeRTOS supports the following ST processor families: STM32 (Cortex-M0, Cortex-M3 and Cortex-M4F), STR7 (ARM7) and STR9 (ARM9), and can be used with the following tools: IAR, Atollic TrueStudio, GCC, Keil, Rowley CrossWorks. Figure 3. Free RTOS port
DocID025801 Rev 2
7/26
25

Free RTOS
UM1722
1.5
FreeRTOS API
Table 1. Free RTOS API
APIs Categories Task Creation – xTaskCreate – vTaskDelete – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – – vTaskDelay vTaskDelayUntil uxTaskPriorityGet vTaskPrioritySet vTaskSuspend vTaskResume xTaskResumeFromISR vTaskSetApplicationTag xTaskCallApplicationTaskHook xTaskGetCurrentTaskHandle xTaskGetSchedulerState uxTaskGetNumberOfTasks vTaskList vTaskStartTrace ulTaskEndTrace vTaskGetRunTimeStats vTaskStartScheduler vTaskEndScheduler vTaskSuspendAll xTaskResumeAll xQueueCreate xQueueSend xQueueReceive xQueuePeek xQueueSendFromISR xQueueSendToBackFromISR xQueueSendToFrontFromISR xQueueReceiveFromISR vQueueAddToRegistry vQueueUnregisterQueue vSemaphoreCreateBinary vSemaphoreCreateCounting xSemaphoreCreateMutex xSemaphoreTake xSemaphoreGive xSemaphoreGiveFromISR API
Task Control
Task Utilities
Kernel Control
Queue Management
Semaphores
8/26
DocID025801 Rev 2

UM1722
Free RTOS
1.6
FreeRTOS memory management
Four sample RAM allocation schemes are included in the FreeRTOS source code download (V2.5.0 onwards). These are used by the various demo applications as appropriate. The following sub-sections describe the available schemes, when they should be used, and highlight the demo applications that demonstrate their use. Each scheme is contained in a separate source file (heap_1.c, heap_2.c, heap_3.c and heap_4.c respectively) which can be located in the Source/Portable/MemMang directory. Other schemes can be added if required.
Scheme 1 - heap_1.c
This is the simplest scheme of all. It does not permit memory to be freed once it has been allocated, but despite this is suitable for a surprisingly large number of applications. The algorithm simply subdivides a single array into smaller blocks as requests for RAM are made. The total size of the array is set by the definition configTOTAL_HEAP_SIZE - which is defined in FreeRTOSConfig.h. This scheme: can be used if your application never deletes a task or queue (no calls to vTaskDelete () or vQueueDelete () are ever made). ? ? is always deterministic (always takes the same amount of time to return a block). is used by the PIC, AVR and 8051 demo applications - as these do not dynamically create or delete tasks after vTaskStartScheduler() has been called.
heap_1.c is suitable for a lot of small real time systems provided that all tasks and queues are created before the kernel is started. Scheme 2 - heap_2.c
This scheme uses a best fit algorithm and, unlike scheme 1, allows previously allocated blocks to be freed. It does not however combine adjacent free blocks into a single large block. Again the total amount of available RAM is set by the definition configTOTAL_HEAP_SIZE which is defined in FreeRTOSConfig.h. This scheme: ? can be used even when the application repeatedly calls vTaskCreate ()/vTaskDelete () or vQueueCreate ()/vQueueDelete () (causing multiple calls to pvPortMalloc() and vPortFree()). should not be used if the memory being allocated and freed is of a random size - this would only be the case if tasks being deleted each had a different stack depth, or queues being deleted were of different lengths. could possibly result in memory fragmentation problems should your application create blocks of queues and tasks in an unpredictable order. This would be unlikely for nearly all applications but should be kept in mind. is not deterministic - but is also not particularly inefficient.
?
?
? ?
heap_2.c is suitable for most small real time systems that have to dynamically create tasks.
DocID025801 Rev 2
9/26
25

Free RTOS
UM1722
Scheme 3 - heap_3.c
This is just a wrapper for the standard malloc() and free() functions. It makes them thread safe. This scheme: ? ? ? ? Requires the linker to setup a heap, and the compiler library to provide malloc() and free() implementations. Is not deterministic. Will probably considerably increase the kernel code size.
Is used by the PC (x86 single board computer) demo application.
Scheme 4 - heap_4.c
This scheme uses a first fit algorithm and, unlike scheme 2, does combine adjacent free memory blocks into a single large block (it does include a coalescence algorithm). The total amount of available heap space is set by configTOTAL_HEAP_SIZE - which is defined in FreeRTOSConfig.h. The xPortGetFreeHeapSize() API function returns the total amount of heap space that remains unallocated (allowing the configTOTAL_HEAP_SIZE setting to be optimised), but does not provide information on how the unallocated memory is fragmented into smaller blocks. This implementation: ? ? Can be used even when the application repeatedly deletes tasks, queues, semaphores, mutexes, etc.. Is much less likely than the heap_2 implementation to result in a heap space that is badly fragmented into multiple small blocks - even when the memory being allocated and freed is of random size. Is not deterministic - but is much more efficient that most standard C library malloc implementations.
?
heap_4.c is particularly useful for applications that want to use the portable layer memory allocation schemes directly in the application code (rather than just indirectly by calling API functions that themselves call pvPortMalloc() and vPortFree()).
1.7
FreeRTOS low power
It is common to reduce the power consumed by the microcontroller on which FreeRTOS is running by using the Idle task hook to place the microcontroller into a low power state. The power saving that can be achieved by this simple method is limited by the necessity to periodically exit and then re-enter the low power state to process tick interrupts. Further, if the frequency of the tick interrupt is too high, the energy and time consumed entering and then exiting a low power state for every tick will outweigh any potential power saving gains for all but the lightest power saving modes. The FreeRTOS tickless idle mode stops the periodic tick interrupt during idle periods (periods when there are no application threads that are able to execute), then makes a correcting adjustment to the RTOS tick count value when the tick interrupt is restarted. Stopping the tick interrupt allows the microcontroller to remain in a power saving state until either an interrupt occurs, or it is time for the RTOS kernel to transition a thread into the Ready state.
10/26
DocID025801 Rev 2

UM1722
Free RTOS
1.8
FreeRTOS configuration
A number of configurable parameters exist that allow the FreeRTOS kernel to be tailored to your particular application. These items are located in a file called FreeRTOSConfig.h. Each demo application included in the FreeRTOS source code download has its own FreeRTOSConfig.h file. Here is a typical example Figure 4. FreeRTOS configuration
/* Ensure stdint is only used by the compiler, and not the assembler. */ #if defined(__ICCARM__) || defined(__CC_ARM) || defined(__GNUC__) #include extern uint32_t SystemCoreClock; #endif #define configUSE_PREEMPTION 1 #define configUSE_IDLE_HOOK 0 #define configUSE_TICK_HOOK 0 #define configCPU_CLOCK_HZ ( SystemCoreClock ) #define configTICK_RATE_HZ ( ( portTickType ) 1000 ) #define configMAX_PRIORITIES ( ( unsigned portBASE_TYPE ) 7 ) #define configMINIMAL_STACK_SIZE ( ( unsigned short ) 128 ) #define configTOTAL_HEAP_SIZE ( ( size_t ) ( 15 * 1024 ) ) #define configMAX_TASK_NAME_LEN ( 16 ) #define configUSE_TRACE_FACILITY 1 #define configUSE_16_BIT_TICKS 0 #define configIDLE_SHOULD_YIELD 1 #define configUSE_MUTEXES 1 #define configQUEUE_REGISTRY_SIZE 8 #define configCHECK_FOR_STACK_OVERFLOW 0 #define configUSE_RECURSIVE_MUTEXES 1 #define configUSE_MALLOC_FAILED_HOOK 0 #define configUSE_APPLICATION_TASK_TAG 0 #define configUSE_COUNTING_SEMAPHORES 1 /* Cortex-M specific definitions. */ #ifdef __NVIC_PRIO_BITS /* __BVIC_PRIO_BITS will be specified when CMSIS is being used. */ #define configPRIO_BITS __NVIC_PRIO_BITS #else #define configPRIO_BITS 4 /* 15 priority levels */ #endif /* The lowest interrupt priority that can be used in a call to a "set priority" function. */ #define configLIBRARY_LOWEST_INTERRUPT_PRIORITY 0xf /* The highest interrupt priority that can be used by any interrupt service routine that makes calls to interrupt safe FreeRTOS API functions */ #define configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY 5 /* Interrupt priorities used by the kernel port layer itself. These are generic to all Cortex-M ports, and do not rely on any particular library functions. */ #define configKERNEL_INTERRUPT_PRIORITY ( configLIBRARY_LOWEST_INTERRUPT_PRIORITY << (8 - configPRIO_BITS) ) #define configMAX_SYSCALL_INTERRUPT_PRIORITY ( configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY << (8 - configPRIO_BITS) ) /* Definitions that map the FreeRTOS port interrupt handlers to their CMSIS standard names. */ #define vPortSVCHandler SVC_Handler #define xPortPendSVHandler PendSV_Handler /* IMPORTANT: This define MUST be commented when used with STM32Cube firmware, to prevent overwriting SysTick_Handler defined within STM32Cube HAL */ /* #define xPortSysTickHandler SysTick_Handler */
Note:
SVC_Handler and PendSV_Handler must be removed from stm32f4xx_it.c/.h files when working with FreeRTOS to avoid a duplicate definition
DocID025801 Rev 2 11/26
25

CMSIS-RTOS module
UM1722
2
2.1
CMSIS-RTOS module
Overview
The CMSIS-RTOS is a common API for Real-Time operating systems. It provides a standardized programming interface that is portable to many RTOS and enables therefore software templates, middleware, libraries, and other components that can work across supported the RTOS systems. This module is represented by cmsis_os.c/h files located under the following repository “Middlewares\Third_Party\FreeRTOS\CMSIS_RTOS”. Figure 5. CMSIS-RTOS architecture
A typical CMSIS-RTOS API implementation interfaces to an existing Real-Time Kernel. The CMSIS-RTOS API provides the following attributes and functionality: ? Function names, identifiers, and parameters are descriptive and easy to understand. The functions are powerful and flexible which reduces the number of functions exposed to the user. Thread Management allow defining, creating, and controlling threads. Interrupt Service Routines (ISR) can call many CMSIS-RTOS functions. When a CMSIS-RTOS function cannot be called from ISR context it rejects the invocation. Three different thread event types support communication between multiple threads and/or ISR: – – – – Signals: are flags that may be used to signal specific conditions to a thread. Signals can be modified in an ISR or set from other threads. Message: is a 32-bit value that can be sent to a thread or an ISR. Messages are buffered in a queue. The message type and queue size are defined in a descriptor. Mail: is a fixed-size memory block that can be sent to a thread or an ISR. Mails are buffered in a queue and memory allocation is provided. The mail type and queue size are defined in a descriptor.
? ? ?
– ? ? ?
Mutex Management and Semaphore Management are incorporated. CPU time can be schedule d with the following functionality: – A timeout parameter is incorporated in many CMSIS-RTOS functions to avoid system lockup. When a timeout is specified the system waits until a resource is available or event occurs. While waiting, other threads are scheduled.
DocID025801 Rev 2
12/26

UM1722 – – –
CMSIS-RTOS module The osDelay function puts a thread into the state WAITING for a specified period of time. The generic osWait function waits for events that are assigned to a thread. The osThreadYield provides co-operative thread switching and passes execution to another thread of the same priority.
The CMSIS-RTOS API is designed to optionally incorporate multi-processor systems and/or access protection via the Cortex-M Memory Protection Unit (MPU). In some RTOS implementation threads may execute on different processors and Mail and Message queues can therefore reside in shared memory resources. The CMSIS-RTOS API encourages the software industry to evolve existing RTOS implementations. Kernel objects are defined and accessed using macros. This allows differentiation. RTOS implementations can be different and optimized in various aspects towards the Cortex-M processors. Optional features may be for example: ? ? ? ? ? ? ? ? ? Generic Wait function; i.e. with support of time intervals. Support of the Cortex-M Memory Protection Unit (MPU). Zero-copy mail queue. Support of multi-processor systems. Support of a DMA controller. Deterministic context switching. Round-robin context switching. Deadlock avoidance, for example with priority inversion. Zero interrupt latency by using the Cortex-M3/M4 instructions LDEX and STEX.
2.2
CMSIS-RTOS API
The following list provides a brief overview of all CMSIS-RTOS API:
Table 2. CMSIS-RTOS API
Module API osKernelInitialize osKernelStart osKernelRunning Kernel Information and osKernelSys Tick (*) Control Description Initialize the RTOS kernel Start the RTOS kernel Query if the RTOS kernel is running Get RTOS kernel system timer counter
osKernelSys TickFrequency (*) RTOS kernel system timer frequency in Hz osKernelSys TickMicroSec (*) Convert microseconds value to RTOS kernel system timer value
DocID025801 Rev 2
13/26
25

CMSIS-RTOS module Table 2. CMSIS-RTOS API (continued)
Module API osThreadCreate osThreadTerminate osThreadYield Thread Management: Define, create and control osThreadGetId thread functions osThreadSetPriority osThreadGetPriority Generic Wait Functions: osDelay Wait for a time period or osWait (*) unspecified events. Timer Management (*): Create and control timer and timer callback functions. Signal Management: Control or wait for signal flags. osTimerCreate osTimerStart osSignalSet osSignalClear osSignalClear osMutexCreate Mutex Management (*): osMutexWait Synchronize thread execution with a Mutex. osMutexRelease osMutexDelete osSemaphoreCreate Semaphore osSemaphoreWait Management (*): Control access to shared osSemaphoreRelease resources. osSemaphoreDelete osPoolCreate Memory Pool osPoolAlloc Management (*): Define and manage fixed- osPoolCAlloc size memory pools. osPoolFree Description
UM1722
Start execution of a thread function. Stop execution of a thread function. Pass execution to next ready thread function. Get the thread identifier to reference this thread. Change the execution priority of a thread function. Obtain the current execution priority of a thread function. Wait for a specified time. Wait for any event of the type Signal, Message, or Mail. Define attributes of the timer callback function Start or restart the timer with a time value. Set signal flags of a thread. Reset signal flags of a thread. Suspend execution until specific signal flags are set. Define and initialize a mutex Obtain a mutex or Wait until it becomes available. Release a mutex Delete a mutex Define and initialize a semaphore. Obtain a semaphore token or Wait until it becomes available. Release a semaphore token. Delete a semaphore. Define and initialize a fix-size memory pool. Allocate a memory block. Allocate a memory block and zero-set this block. Return a memory block to the memory pool.
14/26
DocID025801 Rev 2