|
Coming soon |
1. Introduction
ThreadX is a Real-Time Operating System (RTOS), designed for embedded systems.
It offers two functional modes:
- The common mode: It offers the common RTOS functionalities as threads management and synchronization, memory pool management, messaging, and events handling.
- The module mode: An advanced usage mode that allow loading and unloading pre-linked ThreadX modules on-the-fly through a module manager.
The ThreadX core provide the common RTOS features, like management of threads, semaphores, mutexes and SW timers. The bock diagram below shows the different functional blocks in ThreadX core.
The Azure RTOS ThreadX library is provided with a FreeRTOS compatibility layer. This adaptation layer allow user to develop a ThreadX application using FreeRTOS APIs.
1.1. Unique Features
ThreadX offers a set of unique features that give higher flexibility to the user:
- Various scheduling policies and preemption threshold
- On-fly properties update
- Object notifications
- Event Chaining
- Runtime performance information
- Tracing Mechanism
1.2. Folder/Files structure
- common: contains the implementation of all ThreadX APIs. Added to that it provides some utilities features that are the SW timers, Performance info and tracing features.
- common_modules: contains the implementation of the ThreadX Module feature, allowing the dynamic loading of prelinked ThreadX module. It is basically split into two folders:
- module_lib: implements the txm_*.c API and should be used instead of the tx_*.c when writing a ThreadX module.
- module_manager: implements the functional block to be put on top of the ThreadX core to handle the module loading, unloading, running…
- ports/<core>/<compiler>: contains the implementation of the actual kernel scheduler, mostly in assembly file.
- ports_module/<core>/<compiler>: contains the implementation of ThreadX module related scheduler to fit with Module Manager requirements. This directory files are used instead of the ports ones when the ThreadX Module is enabled.
More details about ThreadX features are available in the official documentation
2. STM32 Integration
To correctly run ThreadX on the STM32 based MCUs, the application should provide 3 user-level files that are:
- tx_initialize_low_level.s: implements the tx_initialize_low_level() function called by the threadX kernel to initialize the RTOS heap base address and setup the SYSTick_Handler().
As tx_initialize_low_level.s is compiler and core dependent, a template of this file is provided for each compiler/core in the ThreadX source tree.
- stm32XXX_hal_timebase_tim.c: Implements a timebase used by the HAL drivers as the systick is reserved for the ThreadX kernel scheduler.
- tx_user.h: configures the ThreadX RTOS using some of defines. A template of this file is provided in the ThreadX source tree. It is included in the ThreadX stack by the define TX_INCLUDE_USER_DEFINE_FILE.
Note: STM32CubeIDE provides specific ThreadX debugging features. More information can be found in STM32CubeIDE user guide.
3. CMSIS-RTOS API Support
The CMSIS-RTOS v2 (CMSIS-RTOS2) provides generic RTOS interfaces for Arm® Cortex® processor-based devices. It provides a standardized API for software components that require RTOS functionality.
The list of features supported for ThreadX is as below:
| Feature | Supported | Short Description |
|---|---|---|
| Kernel Information and Control | Y | It provides version/system information and starts/controls the RTOS Kernel. More… |
| Thread Management | Y | It defines, create, and control thread functions. More… |
| Thread Flags | N | It synchronizes threads using flags. More… |
| Event Flags | Y | It synchronizes threads using event flags. More… |
| Generic Wait Functions | Y | It waits for a certain period of time. More… |
| Timer Management | Y | It creates and controls timer and timer callback functions. More… |
| Mutex Management | Y | It synchronizes resource access using Mutual Exclusion (Mutex). More… |
| Semaphores | Y | It access shared resources simultaneously from different threads. More… |
| Memory Pool | N | It manages thread-safe fixed-size blocks of dynamic memory. More… |
| Message Queue | Y | It exchanges messages between threads in a FIFO-like operation. More… |
For more information about CMSIS-RTOS v2 APIs, please refer to the ARM manual: CMSIS-RTOS API v2.
For more information about the implementation of CMSIS-RTOS wrapper for ThreadX, please refer to its readme.
4. How to use
1. In order to initialize and configure Azure RTOS ThreadX kernel, user needs to include tx_api.h file.
2. Call tx_kernel_enter function from the main.
/* Start the ThreadX kernel */
tx_kernel_enter();
This function initializes the internal ThreadX data structure before calling the application’s definition function (tx_application_define) and starting the scheduler.
3. The user needs as well to define the initial system resources in tx_application_define function. Example of system resources includes threads, queues, memory pools, event flags groups, mutexes, timers and semaphores.
VOID tx_application_define(VOID *first_unused_memory)
{
VOID *memory_ptr = first_unused_memory;
/* USER CODE BEGIN tx_application_define */
/* User can add his own implementation to define the initial ThreadX system resources*/
/* USER CODE END tx_application_define */
}
The input parameter of tx_application_define is the first available RAM address to be used for the run-time memory allocation of thread stacks, queues and memory pools.
4. Initialize system resources initialization using ThreadX APIs :
- Thread creation using ThreadX API :
/* Create ThreadOne. */
if (tx_thread_create(&ThreadOne, "Thread One", ThreadOne_Entry, 0,
pointer, THREAD_ONE_STACK_SIZE,
THREAD_ONE_PRIORITY, THREAD_ONE_PREEMPTION_THRESHOLD,
TX_NO_TIME_SLICE, TX_AUTO_START) != TX_SUCCESS)
{
status = TX_THREAD_ERROR;
}
- Mutex creation using ThreadX API :
/* Create the Mutex */
if (tx_mutex_create(&MutexOne, "Mutex One", TX_NO_INHERIT) != TX_SUCCESS)
{
ret = TX_MUTEX_ERROR;
}
Note: It is also possible to create and delete system resources after starting ThreadX kernel.
5. Define the entry function for each created thread :
void ThreadOne_Entry(ULONG thread_input)
{
/* User can add his own implementation*/
}
5. Applications
STM32Cube FW provides a set of functional applications covering the main features of Azure RTOS ThreadX. Below is the list of ThreadX applications for STM32 MCUs.
| ThreadX application | Overview |
|---|---|
| Tx_Thread_Creation | This application provides an example of Azure RTOS ThreadX stack usage, it shows how to develop an application using the ThreadX thread management APIs. It demonstrates how to create and destroy multiple threads using Azure RTOS ThreadX APIs. In addition, it shows how to use preemption threshold between threads and change priorities on-fly.
For more information please refer to application readme file. |
| Tx_Thread_MsgQueue | This application provides an example of Azure RTOS ThreadX stack usage, it shows how to develop an application using the ThreadX message queue APIs. It demonstrates how to send and receive messages between threads using ThreadX message queue APIs. In addition, it shows how to use the event chaining feature.
For more information please refer to application readme file. |
| Tx_Thread_Sync | This application provides an example of Azure RTOS ThreadX stack usage, it shows how to develop an application using the ThreadX synchronization APIs.
For more information please refer to application readme file. |
| Tx_FreeRTOS_Wrapper | This application provides an example of Azure RTOS ThreadX stack usage, it shows how to develop an application using the FreeRTOS adaptation layer for ThreadX.
For more information please refer to application readme file. |
| Tx_CMSIS_Wrapper | This application provides an example of CMSIS RTOS adaptation layer for Azure RTOS ThreadX, it shows how to develop an application using the CMSIS-RTOS v2 APIs. It demonstrates how to create multiple threads using CMSIS-RTOS v2 for ThreadX APIs.
For more information please refer to application readme file. |