 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The Azure RTOSThreadX kernel (tx) is integrated into the SSP. The Azure RTOS ThreadX kernel is the foundation of multi-threaded SSP applications. It provides thread creation and synchronization services, including message queues, counting semaphores, mutexes, event flags, memory block pools, memory byte pools, and application timers.
The Azure RTOS ThreadX on tx module implements the ThreadX RTOS kernel within the Synergy Software Package. It provides all the scheduling, inter-process communications, memory management, interrupt management and a variety of other RTOS related functions. Typically, application code simply makes use of the functions provided by the kernel. The following operational notes outline some of the areas where the application may benefit from a more detailed interaction with ThreadX and ThreadX source.
Preemption Threshold
The preemption threshold feature is disabled in the provided ThreadX library to reduce code size. If preemption support is needed, then ThreadX source should be included in the project and Preemption Threshold should be set to Enabled in the ThreadX source properties. The preemption threshold for a thread is initially set by the configurator to the thread priority. It can be changed by the tx_thread_preemption_change function.
IAR Library Support (IAR Only)
Thread-safe support for the IAR tools is easily enabled by making the following setting in the Properties of the ThreadX Source Module. In the table, ISDE Property refers to the Properties tab name in the e2 studio ISDE.
ThreadX Source IAR Library Support Configuration
| ISDE Property | Setting | Description |
|---|---|---|
| IAR Library Support | Enabled, Disabled (Default: Disabled) | If enabled, defines TX_ENABLE_IAR_LIBRARY_SUPPORT to provide thread safe access to IAR standard library functions such as malloc() and printf(). |
Also, add the following line to the linker control file (if not already in place):
@ code
initialize by copy with packing = none { section __DLIB_PERTHREAD };
// Required in a multi-threaded application.
@endcode
TX_ENABLE_IAR_LIBRARY_SUPPORT.TX_ENABLE_IAR_LIBRARY_SUPPORT macro enables thread creation and destruction extensions which are required for thread safe access to the IAR runtime library. The TLS (Thread Local Storage) memory is allocated from the heap for each instance. Currently, SSP does not implement the synchronization mechanisms that are required to use the library functions in a thread safe manner. Using the library with just the features provided is safe only if the library functions are accessed in a non-reentrant manner, that is, only a single thread makes calls to this library. To get full multithreaded support, refer to the IAR Dlib Thread Support document from IAR for more information on how to implement the synchronization mechanisms. The implementation will need to be done in the tx_src_user.h file which is an SSP generated file.ThreadX Source Advanced Configurations
If the ThreadX Source module is added to the project, the Properties window provides advanced configurations for the ThreadX source library. Highlight a configuration option to view a description of the option in the bottom left corner of the e2 studio GUI. If the configuration option entry field is empty, the default value will be used. Refer to the Configuration Options chapter of the ThreadX User Guide for more information.
At the end of the advanced properties, there are TX_<COMPONENT>_EXTENSION macros, where <COMPONENT> identifies the type of extension. These extension macros are for advanced use cases only. In most projects, they are not modified. Some cases, such as BSD support for NetX, require use of extension macros and explicitly describe how they should be used.
During the configuration of the project, ThreadX is added automatically when a new Thread is created.
ThreadX objects, including mutexes, semaphores, event flags and queues can be added to Threads in the <Thread Name> Objects section, where <Thread Name> represents the name of an application thread. For example, to add a new queue to a thread, highlight the thread and select New Object > Queue.
To access the queue from a different thread, include the header file of the thread where the queue is defined. For example, if an application has a thread named main_thread with a queue named message_queue, a file named main_thread.h will be generated with an extern for message_queue. If the application also has a thread named background_thread, and the background_thread requires access to the message_queue, main_thread.h should be included in background_thread_entry.c to ensure background_thread_entry.c has access to the definition of message_queue.
Threadx Source configurator property Memory section for Trace Buffer relocates the trace buffer to the memory section indicated by the property. This requires enabling the property Event Trace. By default the trace buffer will be placed in the .bss section of memory
To relocate the trace buffer:
If the selected device is from a family of MCUs that have less memory, please resize the trace buffer from default size = 65536 to a lesser size so as to avoid RAM overflows by using configurator property Trace Buffer Size before enabling the Event Trace.
To restart a user defined thread created by Synergy
Applications trying to restart a thread after tx_thread_terminate/tx_thread_reset/tx_thread_resume call have to use tx_semaphore_put (&g_ssp_common_initialized_semaphore) before restarting.