UM1722 User manual - STMicroelectronics

1 October 2019UM1722 Rev 31/28UM1722 User manualDeveloping applications on STM32 Cube with RTOSI ntroductionThe STM32 Cube is an STMicroelectronics original initiative to significantly improve developer productivity by reducing development effort, time and cost. STM32 Cube covers the whole STM32 includes STM32 CubeMX, a graphical software configuration tool that allows the generation of C initialization code using graphical wizards. A comprehensive embedded software platform, delivered per Series (such as STM32 CubeF4 for STM32F4 Series) The STM32 Cube HAL, STM32 abstraction layer embedded software ensuring maximized portability across the STM32 portfolio, Low-layer APIs (LL) offering a fast light-weight expert-oriented layer, which is closer to the hardware than the HAL. LL APIs are available only for a set of peripherals. A consistent set of middleware components such as RTOS, USB, TCP/IP, Graphics, All embedded software utilities, delivered with a full set of real-time operating system is an operating system optimized for use in embedded/real-time applications.

2 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 user manual is intended for developers who use STM32 Cube firmware on STM32 microcontrollers and microprocessors. It provides a full description of how to use the STM32 Cube 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 STM32 Cube 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 directly ported on any other RTOS without modifying the high level APIs, only the CMSIS-OS wrapper has to be changed in this case. Refer to the release notes of the package to know the version of FreeRTOS and CMSIS-RTOS firmware components used with the document is applicable to all STM32 devices; however for simplicity reason, the STM32F4xx devices and STM32 CubeF4 are used as reference platform.

3 To know more about the examples implementation on your STM32 device, please refer to the readme file provided within the associated STM32 Cube firmware package. Rev 3 Contents1 FreeRTOS .. source organization .. FreeRTOS on STM32 .. API .. memory management .. low power management .. configuration .. 122 CMSIS-RTOS module .. API .. 153 FreeRTOS applications .. creation example .. examples .. between threads .. from ISR .. example .. example .. example .. example .. 234 Conclusion .. 255 FAQs .. 266 Revision history .. 27UM1722 Rev 33/28UM1722 List of tables3 List of tablesTable API .. 9 Table API .. 15 Table application categories .. 18 Table of power consumption .. 24 Table revision history .. 27 List of figuresUM17224/28UM1722 Rev 3 List of figuresFigure license.. 7 Figure architecture .. 8 Figure port .. 9 Figure configuration.

4 13 Figure architecture .. 14 Figure example .. 19 Figure example .. 20 Figure semaphore from ISR .. 20 Figure process .. 22 Figure timer .. 23UM1722 Rev 35/28UM1722 FreeRTOS 271 FreeRTOS OverviewFreeRTOS is a class of RTOS that is designed to be small enough to run on a microcontroller or microprocessor, although its use is not limited to microcontroller and microprocessor microcontroller or a microprocessor is a small and resource real-time 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 and microprocessor 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.

5 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 is a scalable real-time demonstration builder core designed specifically for small embedded systems. Highlights include FreeRTOS 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 Arm Cortex -M3 Memory Protection Unit (MPU). Designed to be small, simple and easy to use.

6 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 UM17226/28UM1722 Rev 3 No restrictions imposed on priority assignment - more than one task can be assigned the same priority.

7 Free development tools for many supported architectures. Free embedded software source code. Royalty free. Cross development from a standard Windows 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 LicenseThe 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: UM1722 Rev 37/28UM1722 FreeRTOS 27 Figure 1. FreeRTOS FreeRTOS source organizationThe 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.

8 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).The 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 For the avoidance of any doubt refer to the comment included at the topof each source and header file for license and copyright is a list of files for which Real Time Engineers Ltd are not the copyright owner and are NOT COVERED BY THE ) 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 ) The uIP TCP/IP stack the copyright of which is held by Adam Dunkels.

9 Users must ensure the open source license conditions stated at the top of each uIP source file is understood and adhered ) 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 of each lwIP source file is understood and adhered ) 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 ) The files contained within FreeRTOS\Demo\WizNET_DEMO_TERN_186\tern_ code, which are slightly modified versions of code provided by and copyright to Tern and omissions should be reported to Richard Barry, contact details forwhom can be obtained from GPL license text special exception to the GPL is included to allow you to distribute a combined work that includes FreeRTOS without being obliged to providethe source code for any proprietary components.

10 See the licensing sectionof for full details. The exception text is alsoincluded at the bottom of this UM17228/28UM1722 Rev 3 Figure 2. FreeRTOS architectureThe core RTOS code is contained in three files, called , and , in the FreeRTOS/Source directory. The same directory contains two optional files called and 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]/[arc hitecture] sub directories, where [compiler] and [architecture] are the compiler used to create the port, and the architecture on which the port runs, sample heap allocation schemes are also located in the portable layer. The various sample files are located in the FreeRTOS/Source/portable/MemMang Porting FreeRTOS on STM32 FreeRTOS supports the following ST processor families: STM32 (Arm (a) Cortex -M0, Arm Cortex -M3 and Arm Cortex -M4F), STR7 (ARM7) and STR9 (ARM9), and can be used with the following tools: IAR, Atollic TrueStudio , GCC, Keil , Rowley FatFs middleware runs on STM32 32-bit microcontrollers based on the -M Abstraction Layer (HAL)a.