Developing Applications on STM32Cube with RTOS
Contents
1. e Free forum support or optional commercial support and licensing e No software restriction on the number of tasks that can be created e No software restriction on the number of priorities that can be used e No restrictions imposed on priority assignment more than one task can be assigned the same priority e Free development tools for many supported architectures DoclD025801 Rev 2 5 26 Free RTOS UM1722 e Free embedded software source code e Royalty free e Cross development from a standard Windows host 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 config lOTAL_HEAP_SIZE which is defined in FreeRTOSContfig 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 The FreeRTOS org source code is licensed by the modified GNU General Public License GPL text provided below The FreeRTOS download also includes demo application source code some of which is provided by third parties AND IS LICENSED SEPARATELY FROM FREERTOS ORG For the avoidance of any doubt refer to the comment included at the top o2. lt 7 UM1722 Yy life augmented User manual Developing Applications on STM32Cube with RTOS Introduction The STMCube 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 e The STM32CubeMX a graphical software configuration tool that allows to generate C initialization code using graphical wizards e 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 o
3. 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 e Free RTOS demonstration builder core preemptive cooperative and hybrid configuration options e Official support for 27 architectures counting ARM7 and ARM Cortex M3 as one architecture each e FreeRTOS MPU supports the Cortex M3 Memory Protection Unit MPU e 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 e Very portable code structure predominantly written in C e Supports both tasks and co routines e Queues binary semaphores counting semaphores recursive semaphores and mutexes for communication and synchronization between tasks or between tasks and interrupts e Mutexes with priority inheritance e Supports efficient software timers e Powerful execution traces functionality e Stack overflows detection options e Pre configured demo applications for selected single board computers allowing out of the box operation and fast learning curve
4. copyright to Te Tene INC Errors and omissions should be reported to Richard Barry contact d tails for whom can be obtained from http www FreeRTOS org Tae GPL license teit tollows A special exception to the GPL is included to allow you to distribute a combined work that includes FreeRTOS without being obliged to provide the source code for any proprietary components See the licensing section of http www FreeRTOS org for full details The exception text is also included at the bottom of this file 6 26 DoclD025801 Rev 2 yy UM1722 1 3 1 4 q Free RTOS 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 Jake U01198 115qy SIEMPIEH The core RTOS code is contained in three files called tasks c gueue 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 RTO
5. debugger live watch HighPriority ThreadCycles MediumPriority hreadCycles and LowPriority ThreadCycles these three variables must remain equal LED1 LED2 and LED4 should toggle indefinitely and LED3 will turn on in case of error Queues example Queues are the primary form of intertask communications They can be used to send messages between tasks and between interrupts and tasks In most cases they are used as thread safe FIFO First In First Out buffers with new data being sent to the back of the queue although data can also be sent to the front This example creates two threads that send and receive an incrementing number to from a queue One thread acts as a producer and the other as the consumer DoclD025801 Rev 2 19 26 FreeRTOS applications UM1722 3 9 20 26 The consumer is a higher priority than the producer and is set to block on gueue reads The gueue only has space for one item as soon as the producer posts a message on the dueue the consumer will unblock preempt the producer and remove the item Figure 9 Queue process Thread Producer N Thread Consumer osMessagePut MU 2 Message Queue creation description Define a queue with QUEUE_SIZE items of 2 bytes osMessageQDef osqueue OUEUE SIZE uint16_t Create the queue osMessageQId osQueue osMessageCreate osMessageQ osqueue NULL Using the exampl
6. setting How to use a clock other than SysTick to generate the tick interrupt User can optionally provide its own tick interrupt source by generating an interrupt from a timer other than SysTick e Provide an implementation of vPortSetup Timerlnterrupt that generates an interrupt at the frequency specified by the configTICK RATE HZ FreeRTOSConfig h constant e Install xPortSysTickHandler as the handler for the timer interrupt and ensure xPortSysTickHandler is not mapped to SysTick_Handler in FreeRTOSConfig h or renamed as SysTick_Handler in port c How to enable the tickless idle mode The FreeRTOS tickles mode low power allows reducing the power consumption of the MCU by entering sleep mode and stopping the periodic tick interrupt This functionality is enabled by defining configUSE TICKLESS_IDLE as 1 in FreeRTOSConfig h The tickless idle mode can be enabled when a timer other than SysTick is used to generate the tick interrupt User has to add the following actions to those described in the previous question e SetconfigUSE TICKLESS IDLE to 2 in FreeRTOSConfig h e Define potSUPPRESS TICKS AND _SLEEP as described in the documentation page on the FreeRTOS website DoclD025801 Rev 2 yy UM1722 Revision history 6 Revision history Table 5 Document revision history oe even ae 18 Feb 2014 Initial release On cover page updated 23 Jun 2014 2 document title reference at STM32CubeF4 into STM3
7. 2 CMSIS RTOS module Table 2 CMSIS RTOS API continued Mode IN Deseipion Message Queue osMessageCreate Define and initialize a message queue Management osMessageCreate Put a message into a message queue Sou el SENG MEDE Get a message or suspend thread wait for messages osMessageCreate ue p l execution until message arrives Define and initialize a mail queue with fix osMailCreate size memory blocks osMailAlloc Allocate a memory block Mail Queue Allocate a memory block and zero set this Management osMailCAlloc block Control send receive or wait for mail osMailPut Put a memory block into a mail queue osMailGet Get a mail or suspend thread until mail arrives Return a memory block to the mail queue Modules or APIs marked with are optional DoclD025801 Rev 2 15 26 y FreeRTOS applications UM1722 3 3 1 16 26 FreeRTOS applications The STM32CubeF4 FreeRTOS package comes with several applications that use the stack API sets The applications are divided into two categories Table 3 Free RTOS application categories Mutexes example Queues example Timer example Features Low power example Thread Creation example A real time application that uses an RTOS can be structured as a set of independent threads Each thread executes within its own context with no coincidental dependency on other threads within the system or the RTOS scheduler itself Only one thread within th
8. 2Cube y DoclD025801 Rev 2 25 26 UM1722 Please Read Carefully Information in this document is provided solely in connection with ST products STMicroelectronics NV and its subsidiaries ST reserve the right to make changes corrections modifications or improvements to this document and the products and services described herein at any time without notice All ST products are sold pursuant to ST s terms and conditions of sale Purchasers are solely responsible for the choice selection and use of the ST products and services described herein and ST assumes no liability whatsoever relating to the choice selection or use of the ST products and services described herein No license express or implied by estoppel or otherwise to any intellectual property rights is granted under this document If any part of this document refers to any third party products or services it shall not be deemed a license grant by ST for the use of such third party products or services or any intellectual property contained therein or considered as a warranty covering the use in any manner whatsoever of such third party products or services or any intellectual property contained therein UNLESS OTHERWISE SET FORTH IN ST S TERMS AND CONDITIONS OF SALE ST DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY WITH RESPECT TO THE USE AND OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIED WARRANTIES OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE AND T
9. 32Cube HAL drivers A set of examples have been described to help users developing applications with CMSIS RTOS API based on FreeRTOS operating system ky DoclD025801 Rev 2 23 26 FAQ 24 26 UM1722 FAQ How to port FreeRTOS to different Cortex M cores To port FreeRTOS to the right Cortex M product you have to import the port c from the correct folder For example if the microcontroller has Cortex MO core with IAR tool you have to get the port c file from FreeRTOS Source portable IAR ARM_CMO repository How much ROM RAM does FreeRTOS use This depends on your compiler architecture and RTOS kernel configuration Generally the RTOS kernel itself required about 5 to 10 KBytes of ROM space RAM usage increase if the number of created threads or queues increases How to set the CPU clock The CPU clock is defined by configCPU CLOGK HZ in FreeRTOSConfig h within STM32CubeF4 firmware its provided by SystemCoreClock which represent the HCLK clock AHB bus this value is set when configuring the RCC clock by calling SystemClock_Config function How to set interrupt priorities Any interrupt service routine that uses an RTOS API function must have its priority manually set to a value that is numerically equal to or greater than the configMAX_SYSCALL INTERRUPT PRIORITY setting in FreeRTOSConfig h file This ensures the interrupt s logical priority is equal to or less than the configMAX_SYSCALL INTERRUPT PRIORITY
10. Create the binary semaphore osSemaphoreld osSemaphore osSemaphoreCreate osSemaphore SEM 1 Using the example 1 Build and program the application code into the STM32 Flash memory 2 Run the example and check that LEDs are toggling as described in Figure 7 3 2 2 Semaphore from ISR This example demonstrates how to use semaphores from interrupts It consists of a basic thread waiting undefinedly for a semaphore to toggle a LED The semaphore is released when the STM32 generates an interrupt after pushing the KEY button of the evaluation board by the user Figure 8 Obtaining semaphore from ISR Thread blocked osSemaphoreWait Interrupt Thread running osSemaphoreRelease osSemaphoreWait mM Using the example 1 Build and program the application code into the STM32 Flash memory 2 Run the example and check that LED1 is toggling when pushing KEY button of the evaluation board 18 26 DoclD025801 Rev 2 yy UM1722 3 3 3 4 y FreeRTOS applications Mutexes example Mutexes are binary semaphores that include a priority inheritance mechanism Whereas binary semaphores are the better choice for implementing synchronization between tasks or between tasks and an interrupt mutexes are the better choice for implementing simple mutual exclusion This example creates three threads with different priorities which access to the same mutex Following 1 the High priority threa
11. E ER RE ke 12 2 1 OVEIVISW OE RE AE ae EE HEER IN 12 2 2 CMSIS RTOS API series Si RES e saw dd Re ek ed ER Ee 2S 13 3 FreeRTOS applications EE Ek EE EE RE RE EE RE RE RE RE 16 3 1 Thread Creation example 0 0 00 ee ee ee 16 3 2 Semaphores examples SES ES ES ee ee eee 17 3 2 1 Semaphore between threads 0 000 cee ee eee 17 3 2 2 semaphore from ISR ESE SES ESE ees 18 3 3 Mutexes example 0 ccc ee eee 19 3 4 Queues example EES SE ee ee eee 19 3 5 Timer example SE SE SE SE ee ee eee 20 3 6 Low power example EES ES SE ee eee 21 4 CONGIUSIONS ticctectaebewetedabatedetveheweeenedt he EE DER ue 23 5 FAO E E HE ido e da a a 24 6 Revision history EE EE DER a a a 25 2 26 DoclD025801 Rev 2 yy UM1722 List of tables List of tables Table 1 PICS INOS 2 MOE TE OG EER Ghana Gees OR VERE ER LE AN 8 Table 2 EMS TOS ARPI EE EE ia dos EE NE EE hae nee D ene ee ee N 13 Table 3 Free RTOS application Categories SESSE ee eee eee 16 Table 4 Comparison of power consumption ooo oo ee ee 22 Table 5 Document revision history o o ooooooooonon eee eas 25 ky DocID025801 Rev 2 3 26 List of figures UM1722 List of figures Figure 1 FreerTOSICONSO sis sek ORE EER EE AE KODE HE RE ges bara rias 6 Figure 2 Free RTOS architecture SES Es SS SE ee Ee se Ee eens 7 Figure 3 PICO RIOS DOM EE ida EO See eS eee Sar RSE eGR ES 7 Figure 4 FreeRTO
12. HEIR EQUIVALENTS UNDER THE LAWS OF ANY JURISDICTION OR INFRINGEMENT OF ANY PATENT COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT ST PRODUCTS ARE NOT DESIGNED OR AUTHORIZED FOR USE IN A SAFETY CRITICAL APPLICATIONS SUCH AS LIFE SUPPORTING ACTIVE IMPLANTED DEVICES OR SYSTEMS WITH PRODUCT FUNCTIONAL SAFETY REQUIREMENTS B AERONAUTIC APPLICATIONS C AUTOMOTIVE APPLICATIONS OR ENVIRONMENTS AND OR D AEROSPACE APPLICATIONS OR ENVIRONMENTS WHERE ST PRODUCTS ARE NOT DESIGNED FOR SUCH USE THE PURCHASER SHALL USE PRODUCTS AT PURCHASER S SOLE RISK EVEN IF ST HAS BEEN INFORMED IN WRITING OF SUCH USAGE UNLESS A PRODUCT IS EXPRESSLY DESIGNATED BY ST AS BEING INTENDED FOR AUTOMOTIVE AUTOMOTIVE SAFETY OR MEDICAL INDUSTRY DOMAINS ACCORDING TO ST PRODUCT DESIGN SPECIFICATIONS PRODUCTS FORMALLY ESCC QML OR JAN QUALIFIED ARE DEEMED SUITABLE FOR USE IN AEROSPACE BY THE CORRESPONDING GOVERNMENTAL AGENCY Resale of ST products with provisions different from the statements and or technical features set forth in this document shall immediately void any warranty granted by ST for the ST product or service described herein and shall not create or extend in any manner whatsoever any liability of ST ST and the ST logo are trademarks or registered trademarks of ST in various countries Information in this document supersedes and replaces all information previously supplied The ST logo is a registered trademark of STMicroelectronics All other names are
13. Low power example This example demonstrates how to run FreeRTOS in low power mode using STM32 devices for more information about FreeRTOS low power mode refer to Section 1 7 Built in tickless idle functionality low power is enabled by defining configUSE TICKLESS IDLE as 1 in FreeRTOSConfig h In this example two threads and a queue are created with the following functionality e The first thread RxThread blocks on a queue to wait for data toggles an LED each time data is received turning it on and then off again before returning to block on the queue once more e The second thread TxThread repeatedly enters the blocked state for 500ms On exiting the blocked state the TxThread sends a message through the queue to the RxThread causing the RxThread to exit the blocked state and toggle the LED When the two threads are blocked the kernel stops the tick interrupt and place the STM32 into low power sleep mode to reduce the power consumption Table 4 present power consumption measured on STM32F4 devices in the context of the example described above DoclD025801 Rev 2 21 26 FreeRTOS applications UM1722 Table 4 Comparison of power consumption Hardware platform Sleep mode STM324xG EVAL 62 4 mA 14 2 mA STM324x9I EVAL 80 5 mA 20 8 mA 7 22 26 DoclD025801 Rev 2 UM1722 Conclusions 4 Conclusions This User Manual explains how to integrate the FreeRTOS middleware components within the STM
14. S 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 Porting FreeRTOS on STM32 FreeRTOS supports the following ST processor families STM32 Cortex MO 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 A es HN License Era Source i include EHE portable iy GCC ig LAR BE Kei 8 MemMang E AVDS H Tasking DocIDO25801 Rev 2 7 26 Free RTOS UM1722 1 5 FreeRTOS API Table 1 Free RTOS API Task Creation ad KO TRALG vlaskDelete vlaskDelay vlaskDelayUntil uxTaskPriorityGet vlaskPrioritySet Task Control vlaskSuspend vlaskResume xTaskResumeFromiSR vlaskSetApplicationTag xTaskCallApplicationTaskHook xlaskGetCurrentTaskHandle xTaskGetSchedulerState UxTaskGetNumberOfTasks Task Utilities vlaskList vlaskStartTrace ullaskEndTrace vlaskGetRunTimeStats vlaskStartScheduler vlaskEndScheduler vlaskSuspendAll xTaskResumeAll Ke
15. S configuratiON ss SEE SE EE SE eee ee eee eee 11 Figure 5 CMSIS RTOS architecture SEE preia eens 12 Figure 6 Thread example SESSE SE SE Es EE Es ee ee eet ee 17 Figure 7 Semaphore eXaMpDlO s 2524 danes dera a a Goat 18 Figure 8 Obtaining semaphore from ISR o o ooocococooo ee ee ee 18 Figure Y QUCUCG PrOCOSS sensores uarach inka Bin IE eens ohh yA She SSS EHS S Ew RE IE eed a 20 Figure 10 IPEOGIC WME eses eriad ae N ee due eg eee EE EE HAD oases Samos Age wee Sow e 21 UM1722 1 1 1 y Free RTOS 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
16. This scheme can be used if your application never deletes a task or queue no calls to vTaskDelete or vQueueDelete are ever made e is always deterministic always takes the same amount of time to return a block e is used by the PIC AVR and 8051 demo applications as these do not dynamically create or delete tasks after vlaskStartScheduler 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 configl OTAL_HEAP_SIZE which is defined in FreeRTOSConfig h This scheme e can be used even when the application repeatedly calls vlaskCreate vTaskDelete or vQueueCreate vQueueDelete causing multiple calls to pvPortMalloc and vPortFree e 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 e 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 e sho
17. all blocks even when the memory being allocated and freed is of random size e 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 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 t
18. d executes first and grabs the mutex and sleeps for a short period to let the lower priority threads execute 2 the Medium priority thread attempts to access the mutex by performing a blocking wait This thread blocks when the mutex is already taken by the high priority thread lt does not unblock until the high priority thread has released the mutex and it does not actually run until the high priority thread has suspended itself 3 the Low priority thread spins round a tight loop attempting to obtain the mutex with a non blocking call As the lowest priority thread it will not successfully obtain the mutex until both high and medium priority threads are suspended 4 the High priority thread gives the mutex back before suspending itself 5 the Medium priority thread obtain the mutex all it does is give the mutex back prior to also suspending itself At this point both the high and medium priority threads are suspended 6 the Low priority thread obtain the mutex it first resumes both suspended threads prior to giving the mutex back resulting in the low priority thread temporarily inheriting the highest thread priority Mutex creation description Define the mutex osMutexDef osMutex Create the mutex osMutexId osMutex osMutexCreate osMutex osMutex Using the example 1 Build and program the application code into the STM32 Flash memory 2 When running in debug mode add the following variables to the
19. e 1 Build and program the application code into the STM32 Flash memory 2 Run the example and check that LED1 toggles for each correct message received else LED3 will toggle Timer example A timer allows a function to be executed at a set time in the future The function executed by the timer is called the timer s callback function The time between a timer being started and its callback function being executed is called the timer s period Put simply the timer s callback function is executed when the timer s period expires This example demonstrates how to use timers of CMSIS RTOS API based on FreeRTOS API creating a periodic timer that calls a callback function every 200 ms to toggle the LED1 of the evaluation board 7 DoclD025801 Rev 2 UM1722 Note 3 6 y FreeRTOS applications Figure 10 Periodic timer l Timer expires after 200 ms and Timer started executes its callback function 400 Time ms Periodic timer creation description Define a timer with osTimerCallback as callback process osTimerDef LEDTimer osTimerCallback Create the timer osTimerld osTimer osTimerCreate osTimer LEDTimer osTimerPeriodic NULL Using the example 1 Build and program the application code into the STM32 Flash memory 2 Run the example and check that LED1 toggles every 200 ms Timer expiration To use FreeRTOS software timers please add timers c to your project workspace
20. e application can be executing at any point in time and the RTOS scheduler is responsible for deciding which thread this should be The aim of this example is to explain how to create threads using CMSIS RTOS based on FreeRTOS API The example implements two threads running with the same priority which execute in a periodic cycle Below details about each thread execution Thread 1 this thread toggles the LED1 each 200 ms for 5 seconds and then it suspends itself after 5 seconds the thread 2 resume the execution of thread 1 which toggles the LED1 each 400 ms for the next 5 seconds Thread creation description Thread 1 definition osThreadDef LED1 LED Threadl osPriorityNormal 0 configMINIMAL STACK SIZE Start thread 1 LEDThreadilHandle osThreadCreate osThread LED1 NULL Thread 2 this thread toggles the LED2 each 500 ms for 10 seconds then it suspend itself Thread 1 will resume the execution of thread 2 after 5 seconds 7 DoclD025801 Rev 2 UM1722 FreeRTOS applications Figure 6 Thread example Thread 2 resume Thread 1 Thread 1 toggles LED1 each 200 ms Thread 2 suspend itself Thread 2 toggles LED2 each 500 ms Thread 1 LED1 each 400 ms Thread 1 suspend itself Thread 1 resume Thread 2 End of the cycle Using the example e Build and program the application code into the STM32 Flash memory e Run the example and check that LEDs are toggling as descr
21. efinition ky DoclD025801 Rev 2 11 26 CMSIS RTOS module UM1722 2 2 1 12 26 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 Application Code main thread interrupt CMSIS RTOS API A typical CMSIS RTOS API implementation interfaces to an existing Real Time Kernel The CMSIS RTOS API provides the following attributes and functionality e 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 e Thread Management allow defining creating and controlling threads e 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 e 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 M
22. essage 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 e Mutex Management and Semaphore Management are incorporated e CPU time can be schedule e 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 DoclD025801 Rev 2 yy UM1722 CMSIS RTOS module 2 2 y 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 exist
23. f each source and header file for license and copyright information This is a list of files for which Real Time Engineers Ltd are not the copyright owner and are NOT COVERED BY THE GPL 1 Various header files provided by silicon manufacturers and tool vendors that define processor specific memory addresses and utility macros Permission has been granted by the various copyright holders for these files to be included in the FreeRTOS download Users must ensure license conditions are adhered to for any use other than compilation of the FreeRTOS demo applications The uIP TCP IP stack the copyright of which is held by Adam Dunkels Users must ensure the open source license conditions stated at the top of each uIP source file is understood and adhered to The lwIP TCP IP stack the copyright of which is held by the Swedish Institute of Computer Science Users must ensure the open source license conditions stated at the top oi each wi source file is understood and ddlieted TOs Various peripheral driver source files and binaries provided by silicon manufacturers and tool vendors Permission has been granted by the various copyright holders for these files to be included in the FreeRTOS download Users must ensure license conditions are adhered to for any use other than compilation of the FreeRTOS demo applications The files contained within FreeRTOS Demo WizNET DEMO TERN 186 tern code which are slightly modified versions of code provided by and
24. f 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 STM32Cube M 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 DoclID025801 Rev 2 1 26 www st com Contents UM1722 Contents 1 SEA SE SO OE AE EE OD EO e aa 5 1 1 OvervieW 2 1 ee ee ee ee 5 1 2 LICENSE reparar PR ORS EASELS PEER EE EER EO OE a 6 1 3 Free RTOS source organization 2 0 0 0 cee eee 7 1 4 Porting FreeRTOS on STM32 SS SES SS SE SS ES Se ee es ee T 1 5 FreeRTOS API oase sonne BROER BAAR AO ES HE EBEA 8 1 6 FreeRTOS memory management SS SE SS cee eee eee eens 9 1 7 FreeRTOS low power ES ESE EE SE eee 10 1 8 FreeRTOS configuration 0 0 ccc ee eee 11 2 CMSIS RTOS module c ccccccccccc ER ER R
25. ibed in Figure 6 3 2 Semaphores examples Semaphores are used for both mutual exclusion and synchronization purposes 3 2 1 Semaphore between threads The aim of this example is to explain how to use semaphores through CMSIS RTOS based on FreeRTOS APIs This example implements two threads with different priorities that share a semaphore to toggle LEDs following more details about the execution of the example 1 The thread 1 which has the higher priority obtains the semaphore and toggle the LED1 for 5 seconds 2 The thread 1 releases the semaphore and suspends itself 3 The low priority thread can execute now it obtains the semaphore and resume execution of the thread 2 4 As it has the higher priority the thread 1 will try to obtain the semaphore but it blocks because the semaphore is already taken by the low priority thread 5 Thread 2 will toggle the LED2 for 5 seconds before releasing the semaphore and begin a new cycle DoclD025801 Rev 2 17 26 a FreeRTOS applications UM1722 Figure 7 Semaphore example Thead 1 waiting for semaphore to toggle LED Thread 1 high priority obtains semaphore and toggles LED1 Thread 1 release the semaphore and suspends itself Thread 2 release the semaphore Thread 2 low priority obtains the semaphore End of cycle resume Thread 1 and toggles LED2 Semaphore creation description Define the semaphore osSemaphoreDef SEM
26. ing 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 CMSIS RTOS API The following list provides a brief overview of all CMSIS RTOS API Table 2 CMSIS RTOS API MEEN EN N Control osKernelSys Tick Get RTOS kernel system timer counter osKernelSys TickFrequency RTOS kernel system timer frequency in Hz l a Convert microseconds value to RTOS osKernelSys TickMicroSec kernel system timer value DoclD025801 Rev 2 13 26 CMSIS RTOS module UM1722 Table 2 CMSIS RTOS API continued EEN N N osThreadCreate Start execution of a thread function osThreadTerminate Stop execution of a thread function osThreadYield Pass execution to next ready thread function Thread Management Define create and control osThreadGetld Get the thread identifier to reference this thread functions thread osThreadSetPriority Change the executi
27. iucki ype 1000 unsigned POrTBASE TYPE unsigned shore 128 eize 15 1024 J l6 relse define configPRIO BITS 15 priority leyels y tendif 7 The lowest interrupt priority that san be used in a call co a set priority function 7 7 define Config LIBRARY LOWEST INTERRUPT PRIORITY Osz The highest interrupt priority that can be used by any interrupt service routine that makes calls to interrupt sate FreerTtTOs API functions define conta LIBRAari MAX yy ERLI TNTEREYET BEITORITY 5 e Tnterrupt priorities used by the kernel port layer itself These are generic to all Corrtex M porte and do me rely on any particular library functions 7 define conto ENE INTERRUPT PRIORITY conto le Raco LOWEST INTERRUPT PRIORITY lt lt eon LO MO BITS define conf iLgMAX SYSCALL INTERRUPT PRIORITY COnELGLIBRARY MAX Sys CALE INTERRUPT PRIORITY lt lt CONL IGPRIO BITS Definicions that map the PreeRTOS port interrupt handlers to cheir EMS IS standard names ds tine Po EA SYC Handler dosie xPortPendsVmandiler PendSsy Handler IMPORTANT This define MUST be commented when used with STM32Cube firmware tO prevent oyvyerwrircing SysTick Handler defined within STM3ZCube MAL a pdefine xPort SysTickiandler SysTiek Handler Note SVC_Handler and PendSV_Handler must be removed from stm32f4xx_it c h files when working with FreeRTOS to avoid a duplicate d
28. on priority of a thread function osThreadGetPriority Obtain the current execution priority of a thread function Generic Wait Functions Wait for a specified time Wait for a time period or ats Wait for any event of the type Signal unspecified events 0SWait Message or Mail Timer Management Define attributes of the timer callback l osTimerCreate l Create and control timer function and timer callback l l l l functions osTimerStart Start or restart the timer with a time value osSignalSet Set signal flags of a thread olgnal Management osSignalClear Reset signal flags of a thread Control or wait for signal flags osSignalClear Suspend execution until specific signal flags are set osMutexCreate Define and initialize a mutex Mutex Management osMutexWait Obtain a mutex or Walt until it becomes Synchronize thread available OA ese osMutexDelete Delete a mutex osSemaphoreCreate Define and initialize a semaphore SEAP Ore PEE E NE Obtain a semaphore token or Wait until it Management P becomes available Control access to shared resources osSemaphoreRelease Release a semaphore token osSemaphoreDelete Delete a semaphore osPoolCreate Define and coa fix size memory Memory Pool osPoolAlloc Allocate a memory block Management Define and manage fixed osPooICAlloc Allocate a memory block and zero set this size memory pools block Return a ibi Er to the memory 14 26 DoclD025801 Rev 2 yy UM172
29. ransition a thread into the Ready state DoclD025801 Rev 2 yy 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 Emsure Stdint is only used by tas compiler amd not the assembler eden mead Oca N dees d Mee eA RM dere ene NC ll fFuncilude lt std im hi extern uint32 t SystemCoreClock tendif define configUSE PREEMPTION define configUSE IDLE HOOK define configUSE TICK HOOK define configCPU CLOCK HZ define configTICK RATE HZ define configMAX PRIORITIES oertinas ContigMINIMAL STACK SIAE fdetine coni iigTOTAL HEAP CIZE tdefine configMAX TASK NAME LEN det dus contr gusn TRACE PACILITY fdefime Contiguse 16 BIT TICKS deta CONE gl DLE SHOULD VILD define configUSE MUTEXES oe fame conto UE UE REGISTRY SIZE de ine Conk ugechaek FOR STACK OVERFLOW desire conti o US RECURSIVE MURE ES rdetine conti USE MALLOC FATT ED HOOK de fine eon JU APP MENT EN TA K TAC faeLine comtigusm COUNTING SEMAPHORES pa Cortex M specituwe det iii ies ie vore PR TOR ms EE ae PRIO BITS will be specified en CMSIS is being used 7 ale Els oen iese es ils LAO PRIO EIT SystemCoreClock poorer
30. rnel Control xQueueCreate xQueueSend xQueueReceive xQueuePeek xQueueSendFromlSR xQueueSendToBackFromISR xQueueSendToFrontFromlSR xQueueReceiveFromlSR vQueueAddToRegistry vQueueUnregisterQueue Queue Management vSemaphoreCreateBinary vSemaphoreCreateCounting xSemaphoreCreateMutex xSemaphore Take xSemaphoreGive XSemaphoreGiveFromlSR Semaphores 7 8 26 DoclD025801 Rev 2 UM1722 1 6 Free RTOS 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
31. the property of their respective owners 2014 STMicroelectronics All rights reserved STMicroelectronics group of companies Australia Belgium Brazil Canada China Czech Republic Finland France Germany Hong Kong India Israel Italy Japan Malaysia Malta Morocco Philippines Singapore Spain Sweden Switzerland United Kingdom United States of America www st com 26 26 DoclD025801 Rev 2 yy
32. uld be kept in mind e 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 DoclD025801 Rev 2 9 26 Free RTOS 1 7 10 26 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 e Requires the linker to setup a heap and the compiler library to provide malloc and free implementations e Is not deterministic e Will probably considerably increase the kernel code size e ls used by the PC x86 single board computer demo application Scheme 4 heap d4 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 e Can be used even when the application repeatedly deletes tasks queues semaphores mutexes etc e Is much less likely than the heap 2 implementation to result in a heap space that is badly fragmented into multiple sm
Download Pdf Manuals
Related Search