Azure RTOS ThreadX and ThreadX CDI Port
The Open IoT SDK gives your application the options to use
- the Azure RTOS ThreadX API
- the CMSIS-RTOS v2 API, through a wrapper (named ThreadX CDI Port) on top of Azure RTOS ThreadX
A single application has the flexibility of using software components that are based on the two different RTOS APIs.
The sections below explain how to use each of the two options.
If you are new to CMake and the Open IoT SDK, you are advised to familiarized yourself with How to create an application and use the Open IoT SDK before continuing.
Azure RTOS ThreadX
Fetching
In your application's CMakeLists.txt
, include threadx
in the IOTSDK_FETCH_LIST
variable, alongside any other components you need to fetch:
Configuration
Note: This is optional. If you do not intend to override the default configuration, you can skip this section and jump to Linking.
In your application's directory, create a threadx-config/tx_user.h
file for the Azure RTOS ThreadX configuration. Define any ThreadX configuration macros you want to override in the tx_user.h
you have created. You can refer to the list of configuration macros.
Then, in your application's CMakeLists.txt
, set TX_USER_FILE
to the full path to the tx_user.h
file you have created:
Linking
Link your application to the library named threadx
, alongside any other libraries you need:
Examples
To see the full context of where to put each of the above code snippet in CMakeLists.txt
, as well as how to call the API from your application, you are advised to take a look at the examples showing how to use Azure RTOS ThreadX.
Documentation
For more details, see the Azure RTOS ThreadX documentation website.
ThreadX CDI Port
Fetching
Include threadx-cdi-port
in the IOTSDK_FETCH_LIST
variable, alongside any other components you need to fetch:
Configuration
In your application's directory, create a threadx-config/tx_user.h
file for the Azure RTOS ThreadX configuration. At minimum, it must contain the following definitions:
#define TX_PORT_SPECIFIC_PRE_SCHEDULER_INITIALIZATION return;
#define TX_THREAD_USER_EXTENSION VOID *tx_cmsis_extension;
You can also define additional macros for both the ThreadX CDI Port configuration and the underlying ThreadX configuration.
In your application's CMakeLists.txt
, set TX_USER_FILE
to the full path to the tx_user.h
file you have created:
Linking
Link the library cmsis-rtos-api
to the library threadx-cdi-port
:
cmsis-rtos-api
provides the API declaration only, whereasthreadx-cdi-port
is a concrete implementation (definition). Without thistarget_link_libraries()
directive, any libraries that depend oncmsis-rtos-api
may fail to pick up the definition and produceundefined reference
errors.
Finally, link your application to the library named cmsis-rtos-api
, alongside any other libraries you need:
Examples
To see the full context of where to put each of the above code snippet in CMakeLists.txt
, as well as how to call the API from your application, you are advised to take a look at the examples showing how to use the ThreadX CDI Port.
Documentation
For additional configuration options, see the documentation for ThreadX CDI Port.
To learn how to use the CMSIS-RTOS v2 API, see the API's documentation.
Mixed usage of the two APIs
In your application's CMakeLists.txt
, enabling the ThreadX CDI Port also enables the underlying Azure RTOS ThreadX API, so no additional CMake configuration is needed.
If your application and/or libraries use both of the RTOS APIs, the RTOS kernel must be initialized and started via the CMSIS-RTOS v2 API only, by calling osKernelInitialize()
and osKernelStart()
. Once the kernel has started, both the CMSIS-RTOS v2 API and the Azure RTOS ThreadX API become available for use.