This chapter contains a description of all ThreadX SMP services in alphabetic order. Their names are designed so all similar services are grouped together. In the “Return Values” section in the following descriptions, values in BOLD are not affected by the TX_DISABLE_ERROR_CHECKING define used to disable API error checking; while values shown in nonbold are completely disabled. In addition, a “Yes” listed under the “Preemption Possible” heading indicates that calling the service may resume a higher-priority thread, thus preempting the calling thread.
Allocate fixed-size block of memory
UINT tx_block_allocate(TX_BLOCK_POOL *pool_ptr, VOID **block_ptr,
ULONG wait_option);
This service allocates a fixed-size memory block from the specified memory pool. The actual size of the memory block is determined during memory pool creation.
Warning: It is important to ensure application code does not write outside the allocated memory block. If this happens, corruption occurs in an adjacent (usually subsequent) memory block. The results are unpredictable and are often fatal!
Selecting TX_NO_WAIT results in an immediate return from this service regardless if it was successful or not. This is the only valid option if the service is called from a non-thread; e.g., Initialization, timer, or ISR.
Selecting TX_WAIT_FOREVER causes the calling thread to suspend indefinitely until a memory block is available.
Selecting a numeric value (1-0xFFFFFFFE) specifies the maximum number of timer-ticks to stay suspended while waiting for a memory block.
Initialization, threads, timers, and ISRs
Yes
TX_BLOCK_POOL my_pool;
unsigned char*memory_ptr;
UINT status;
/* Allocate a memory block from my_pool. Assume that the
pool has already been created with a call to
tx_block_pool_create. */
status = tx_block_allocate(&my_pool, (VOID **) &memory_ptr,
TX_NO_WAIT);
/* If status equals TX_SUCCESS, memory_ptr contains the
address of the allocated block of memory. */
Create pool of fixed-size memory blocks
UINT tx_block_pool_create(TX_BLOCK_POOL *pool_ptr,
CHAR *name_ptr, ULONG block_size,
VOID *pool_start, ULONG pool_size);
This service creates a pool of fixed-size memory blocks. The memory area specified is divided into as many fixed-size memory blocks as possible using the formula:
total blocks = (total bytes) / (block size + sizeof(void *))
Important: Each memory block contains one pointer of overhead that is invisible to the user and is represented by the “sizeof(void *)” in the preceding formula.
Initialization and threads
No
TX_BLOCK_POOL my_pool;
UINT status;
/* Create a memory pool whose total size is 1000 bytes
starting at address 0x100000. Each block in this
pool is defined to be 50 bytes long. */
status = tx_block_pool_create(&my_pool, "my_pool_name",
50, (VOID *) 0x100000, 1000);
/* If status equals TX_SUCCESS, my_pool contains 18
memory blocks of 50 bytes each. The reason
there are not 20 blocks in the pool is
because of the one overhead pointer associated with each
block. */
Delete memory block pool
UINT tx_block_pool_delete(TX_BLOCK_POOL *pool_ptr);
This service deletes the specified block-memory pool. All threads suspended waiting for a memory block from this pool are resumed and given a TX_DELETED return status.
Important: It is the application’s responsibility to manage the memory area associated with the pool, which is available after this service completes. In addition, the application must prevent use of a deleted pool or its former memory blocks.
Threads
Yes
TX_BLOCK_POOLmy_pool;
UINT status;
/* Delete entire memory block pool. Assume that the pool
has already been created with a call to
tx_block_pool_create. */
status = tx_block_pool_delete(&my_pool);
/* If status equals TX_SUCCESS, the memory block pool is
deleted. */
Retrieve information about block pool
UINT tx_block_pool_info_get(TX_BLOCK_POOL *pool_ptr, CHAR **name,
ULONG *available, ULONG *total_blocks,
TX_THREAD **first_suspended,
ULONG *suspended_count,
TX_BLOCK_POOL **next_pool);
This service retrieves information about the specified block memory pool.
Important: Supplying a TX_NULL for any parameter indicates the parameter is not required.
Initialization, threads, timers, and ISRs
TX_BLOCK_POOL my_pool;
CHAR *name;
ULONG available;
ULONG total_blocks;
TX_THREAD *first_suspended;
ULONG suspended_count;
TX_BLOCK_POOL *next_pool;
UINT status;
/* Retrieve information about the previously created
block pool "my_pool." */
status = tx_block_pool_info_get(&my_pool, &name,
&available,&total_blocks,
&first_suspended, &suspended_count,
&next_pool);
/* If status equals TX_SUCCESS, the information requested is
valid. */
Get block pool performance information
UINT tx_block_pool_performance_info_get(TX_BLOCK_POOL *pool_ptr,
ULONG *allocates, ULONG *releases,
ULONG *suspensions, ULONG *timeouts));
This service retrieves performance information about the specified memory block pool.
Important: The ThreadX SMP library and application must be built with TX_BLOCK_POOL_ENABLE_PERFORMANCE_INFO defined for this service to return performance information.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
TX_BLOCK_POOL my_pool;
ULONG allocates;
ULONG releases;
ULONG suspensions;
ULONG timeouts;
/* Retrieve performance information on the previously created block
pool. */
status = tx_block_pool_performance_info_get(&my_pool, &allocates,
&releases,
&suspensions,
&timeouts);
/* If status is TX_SUCCESS the performance information was
successfully retrieved. */
Get block pool system performance information
UINT tx_block_pool_performance_system_info_get(ULONG *allocates,
ULONG *releases, ULONG *suspensions, ULONG *timeouts);
This service retrieves performance information about all memory block pools in the application.
Important: The ThreadX SMP library and application must be built with TX_BLOCK_POOL_ENABLE_PERFORMANCE_INFO defined for this service to return performance information.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
ULONG allocates;
ULONG releases;
ULONG suspensions;
ULONG timeouts;
/* Retrieve performance information on all the block pools in
the system. */
status = tx_block_pool_performance_system_info_get(&allocates,
&releases,&suspensions, &timeouts);
/* If status is TX_SUCCESS the performance information was
successfully retrieved. */
Prioritize block pool suspension list
UINT tx_block_pool_prioritize(TX_BLOCK_POOL *pool_ptr);
This service places the highest priority thread suspended for a block of memory on this pool at the front of the suspension list. All other threads remain in the same FIFO order they were suspended in.
Initialization, threads, timers, and ISRs
No
TX_BLOCK_POOL my_pool;
UINT status;
/* Ensure that the highest priority thread will receive
the next free block in this pool. */
status = tx_block_pool_prioritize(&my_pool);
/* If status equals TX_SUCCESS, the highest priority
suspended thread is at the front of the list. The
next tx_block_release call will wake up this thread. */
Release fixed-size block of memory
UINT tx_block_release(VOID *block_ptr);
This service releases a previously allocated block back to its associated memory pool. If there are one or more threads suspended waiting for memory blocks from this pool, the first thread suspended is given this memory block and resumed.
Important: The application must prevent using a memory block area after it has been released back to the pool.
Initialization, threads, timers, and ISRs
Yes
TX_BLOCK_POOLmy_pool;
unsigned char*memory_ptr;
UINT status;
/* Release a memory block back to my_pool. Assume that the
pool has been created and the memory block has been
allocated. */
status = tx_block_release((VOID *) memory_ptr);
/* If status equals TX_SUCCESS, the block of memory pointed
to by memory_ptr has been returned to the pool. */
Allocate bytes of memory
UINT tx_byte_allocate(TX_BYTE_POOL *pool_ptr,
VOID **memory_ptr, ULONG memory_size,
ULONG wait_option);
This service allocates the specified number of bytes from the specified memory byte pool.
Warning: It is important to ensure application code does not write outside the allocated memory block. If this happens, corruption occurs in an adjacent (usually subsequent) memory block. The results are unpredictable and are often fatal!
Important: The performance of this service is a function of the block size and the amount of fragmentation in the pool. Hence, this service should not be used during time-critical threads of execution.
Selecting TX_NO_WAIT results in an immediate return from this service regardless of whether or not it was successful. This is the only valid option if the service is called from initialization.
Selecting TX_WAIT_FOREVER causes the calling thread to suspend indefinitely until enough memory is available.
Selecting a numeric value (1-0xFFFFFFFE) specifies the maximum number of timer-ticks to stay suspended while waiting for the memory.
Initialization and threads
Yes
TX_BYTE_POOL my_pool;
unsigned char*memory_ptr;
UINT status;
/* Allocate a 112 byte memory area from my_pool. Assume
that the pool has already been created with a call to
tx_byte_pool_create. */
status = tx_byte_allocate(&my_pool, (VOID **) &memory_ptr,
112, TX_NO_WAIT);
/* If status equals TX_SUCCESS, memory_ptr contains the
address of the allocated memory area. */
Create memory pool of bytes
UINT tx_byte_pool_create(TX_BYTE_POOL *pool_ptr,
CHAR *name_ptr, VOID *pool_start,
ULONG pool_size);
This service creates a memory byte pool in the area specified. Initially the pool consists of basically one very large free block. However, the pool is broken into smaller blocks as allocations are made.
Initialization and threads
No
TX_BYTE_POOL my_pool;
UINT status;
/* Create a memory pool whose total size is 2000 bytes
starting at address 0x500000. */
status = tx_byte_pool_create(&my_pool, "my_pool_name",
(VOID *) 0x500000, 2000);
/* If status equals TX_SUCCESS, my_pool is available for
allocating memory. */
Delete memory byte pool
UINT tx_byte_pool_delete(TX_BYTE_POOL *pool_ptr);
This service deletes the specified memory byte pool. All threads suspended waiting for memory from this pool are resumed and given a TX_DELETED return status.
Important: It is the application’s responsibility to manage the memory area associated with the pool, which is available after this service completes. In addition, the application must prevent use of a deleted pool or memory previously allocated from it.
Threads
Yes
TX_BYTE_POOL my_pool;
UINT status;
/* Delete entire memory pool. Assume that the pool has already
been created with a call to tx_byte_pool_create. */
status = tx_byte_pool_delete(&my_pool);
/* If status equals TX_SUCCESS, memory pool is deleted. */
Retrieve information about byte pool
UINT tx_byte_pool_info_get(TX_BYTE_POOL *pool_ptr, CHAR **name,
ULONG *available, ULONG *fragments,
TX_THREAD **first_suspended,
ULONG *suspended_count,
TX_BYTE_POOL **next_pool);
This service retrieves information about the specified memory byte pool.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
No
TX_BYTE_POOL my_pool;
CHAR *name;
ULONG available;
ULONG fragments;
TX_THREAD *first_suspended;
ULONG suspended_count;
TX_BYTE_POOL *next_pool;
UINT status;
/* Retrieve information about the previously created
block pool "my_pool." */
status = tx_byte_pool_info_get(&my_pool, &name,
&available, &fragments,
&first_suspended, &suspended_count,
&next_pool);
/* If status equals TX_SUCCESS, the information requested is
valid. */
Get byte pool performance information
UINT tx_byte_pool_performance_info_get(TX_BYTE_POOL *pool_ptr,
ULONG *allocates, ULONG *releases,
ULONG *fragments_searched, ULONG *merges, ULONG *splits,
ULONG *suspensions, ULONG *timeouts);
This service retrieves performance information about the specified memory byte pool.
Important: The ThreadX SMP library and application must be built with TX_BYTE_POOL_ENABLE_PERFORMANCE_INFO defined for this service to return performance information.
Important: Supplying a TX_NULL for any parameter indicates the parameter is not required.
Initialization, threads, timers, and ISRs
TX_BYTE_POOL my_pool;
ULONG fragments_searched;
ULONG merges;
ULONG splits;
ULONG allocates;
ULONG releases;
ULONG suspensions;
ULONG timeouts;
/* Retrieve performance information on the previously created byte
pool. */
status = tx_byte_pool_performance_info_get(&my_pool,
&fragments_searched,
&merges, &splits,
&allocates, &releases,
&suspensions,&timeouts);
/* If status is TX_SUCCESS the performance information was
successfully retrieved. */
Get byte pool system performance information
UINT tx_byte_pool_performance_system_info_get(ULONG *allocates,
ULONG *releases, ULONG *fragments_searched, ULONG *merges,
ULONG *splits, ULONG *suspensions, ULONG *timeouts);;
This service retrieves performance information about all memory byte pools in the system.
Important: The ThreadX SMP library and application must be built with TX_BYTE_POOL_ENABLE_PERFORMANCE_INFO defined for this service to return performance information.
Important: Supplying a TX_NULL for any parameter indicates the parameter is not required.
Initialization, threads, timers, and ISRs
ULONG fragments_searched;
ULONG merges;
ULONG splits;
ULONG allocates;
ULONG releases;
ULONG suspensions;
ULONG timeouts;
/* Retrieve performance information on all byte pools in the
system. */
status =
tx_byte_pool_performance_system_info_get(&fragments_searched,
&merges, &splits, &allocates, &releases,
&suspensions, &timeouts);
/* If status is TX_SUCCESS the performance information was
successfully retrieved. */
Prioritize byte pool suspension list
UINT tx_byte_pool_prioritize(TX_BYTE_POOL *pool_ptr);
This service places the highest priority thread suspended for memory on this pool at the front of the suspension list. All other threads remain in the same FIFO order they were suspended in.
Initialization, threads, timers, and ISRs
No
TX_BYTE_POOL my_pool;
UINT status;
/* Ensure that the highest priority thread will receive
the next free memory from this pool. */
status = tx_byte_pool_prioritize(&my_pool);
/* If status equals TX_SUCCESS, the highest priority
suspended thread is at the front of the list. The
next tx_byte_release call will wake up this thread,
if there is enough memory to satisfy its request. */
Release bytes back to memory pool
UINT tx_byte_release(VOID *memory_ptr);
This service releases a previously allocated memory area back to its associated pool. If there are one or more threads suspended waiting for memory from this pool, each suspended thread is given memory and resumed until the memory is exhausted or until there are no more suspended threads. This process of allocating memory to suspended threads always begins with the first thread suspended.
Important: The application must prevent using the memory area after it is released.
Initialization and threads
Yes
unsigned char *memory_ptr;
UINT status;
/* Release a memory back to my_pool. Assume that the memory
area was previously allocated from my_pool. */
status = tx_byte_release((VOID *) memory_ptr);
/* If status equals TX_SUCCESS, the memory pointed to by
memory_ptr has been returned to the pool. */
Create event flags group
UINT tx_event_flags_create(TX_EVENT_FLAGS_GROUP *group_ptr,
CHAR *name_ptr);
This service creates a group of 32 event flags. All 32 event flags in the group are initialized to zero. Each event flag is represented by a single bit.
Initialization and threads
No
TX_EVENT_FLAGS_GROUP my_event_group;
UINT status;
/* Create an event flags group. */
status = tx_event_flags_create(&my_event_group,
"my_event_group_name");
/* If status equals TX_SUCCESS, my_event_group is ready
for get and set services. */
Delete event flags group
UINT tx_event_flags_delete(TX_EVENT_FLAGS_GROUP *group_ptr);
This service deletes the specified event flags group. All threads suspended waiting for events from this group are resumed and given a TX_DELETED return status.
Important: The application must ensure that a set notify callback for this event flags group is completed (or disabled) before deleting the event flags group. In addition, the application must prevent all future use of a deleted event flags group.
Threads
Yes
TX_EVENT_FLAGS_GROUP my_event_flags_group;
UINT status;
/* Delete event flags group. Assume that the group has
already been created with a call to
tx_event_flags_create. */
status = tx_event_flags_delete(&my_event_flags_group);
/* If status equals TX_SUCCESS, the event flags group is
deleted. */
Get event flags from event flags group
UINT tx_event_flags_get(TX_EVENT_FLAGS_GROUP *group_ptr,
ULONG requested_flags, UINT get_option,
ULONG *actual_flags_ptr, ULONG wait_option);
This service retrieves event flags from the specified event flags group. Each event flags group contains 32 event flags. Each flag is represented by a single bit. This service can retrieve a variety of event flag combinations, as selected by the input parameters.
Selecting TX_AND or TX_AND_CLEAR specifies that all event flags must be present in the group. Selecting TX_OR or TX_OR_CLEAR specifies that any event flag is satisfactory. Event flags that satisfy the request are cleared (set to zero) if TX_AND_CLEAR or TX_OR_CLEAR are specified.
Selecting TX_NO_WAIT results in an immediate return from this service regardless of whether or not it was successful. This is the only valid option if the service is called from a non-thread; e.g., Initialization, timer, or ISR.
Selecting TX_WAIT_FOREVER causes the calling thread to suspend indefinitely until the event flags are available.
Selecting a numeric value (1-0xFFFFFFFE) specifies the maximum number of timer-ticks to stay suspended while waiting for the event flags.
Initialization, threads, timers, and ISRs
Yes
TX_EVENT_FLAGS_GROUP my_event_flags_group;
ULONG actual_events;
UINT status;
/* Request that event flags 0, 4, and 8 are all set. Also,
if they are set they should be cleared. If the event
flags are not set, this service suspends for a maximum of
20 timer-ticks. */
status = tx_event_flags_get(&my_event_flags_group, 0x111,
TX_AND_CLEAR, &actual_events, 20);
/* If status equals TX_SUCCESS, actual_events contains the
actual events obtained. */
Retrieve information about event flags group
UINT tx_event_flags_info_get(TX_EVENT_FLAGS_GROUP *group_ptr,
CHAR **name, ULONG *current_flags,
TX_THREAD **first_suspended,
ULONG *suspended_count,
TX_EVENT_FLAGS_GROUP **next_group);
This service retrieves information about the specified event flags group.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
No
TX_EVENT_FLAGS_GROUPmy_event_group;
CHAR *name;
ULONG current_flags;
TX_THREAD *first_suspended;
ULONG suspended_count;
TX_EVENT_FLAGS_GROUP*next_group;
UINT status;
/* Retrieve information about the previously created
event flags group "my_event_group." */
status = tx_event_flags_info_get(&my_event_group, &name,
¤t_flags,
&first_suspended, &suspended_count,
&next_group);
/* If status equals TX_SUCCESS, the information requested is
valid. */
Get event flags group performance information
UINT tx_event_flags_performance_info_get(TX_EVENT_FLAGS_GROUP
*group_ptr, ULONG *sets, ULONG *gets,
ULONG *suspensions, ULONG *timeouts);
This service retrieves performance information about the specified event flags group.
Important: ThreadX SMP library and application must be built with TX_EVENT_FLAGS_ENABLE_PERFORMANCE_INFO defined for this service to return performance information.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
TX_EVENT_FLAGS_GROUPmy_event_flag_group;
ULONG sets;
ULONG gets;
ULONG suspensions;
ULONG timeouts;
/* Retrieve performance information on the previously created event
flag group. */
status = tx_event_flags_performance_info_get(&my_event_flag_group,
&sets, &gets, &suspensions,
&timeouts);
/* If status is TX_SUCCESS the performance information was successfully
retrieved. */
Retrieve performance system information
UINT tx_event_flags_performance_system_info_get(ULONG *sets,
ULONG *gets,ULONG *suspensions, ULONG *timeouts);
This service retrieves performance information about all event flags groups in the system.
Important: ThreadX SMP library and application must be built with TX_EVENT_FLAGS_ENABLE_PERFORMANCE_INFO defined for this service to return performance information.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
ULONG sets;
ULONG gets;
ULONG suspensions;
ULONG timeouts;
/* Retrieve performance information on all previously created event
flag groups. */
status = tx_event_flags_performance_system_info_get(&sets, &gets,
&suspensions, &timeouts);
/* If status is TX_SUCCESS the performance information was
successfully retrieved. */
Set event flags in an event flags group
UINT tx_event_flags_set(TX_EVENT_FLAGS_GROUP *group_ptr,
ULONG flags_to_set,UINT set_option);
This service sets or clears event flags in an event flags group, depending upon the specified set-option. All suspended threads whose event flags request is now satisfied are resumed.
Initialization, threads, timers, and ISRs
Yes
TX_EVENT_FLAGS_GROUPmy_event_flags_group;
UINT status;
/* Set event flags 0, 4, and 8. */
status = tx_event_flags_set(&my_event_flags_group,
0x111, TX_OR);
/* If status equals TX_SUCCESS, the event flags have been
set and any suspended thread whose request was satisfied
has been resumed. */
Notify application when event flags are set
UINT tx_event_flags_set_notify(TX_EVENT_FLAGS_GROUP *group_ptr,
VOID (*events_set_notify)(TX_EVENT_FLAGS_GROUP *));
This service registers a notification callback function that is called whenever one or more event flags are set in the specified event flags group. The processing of the notification callback is defined by the application.
Note: The application’s event flags set notification callback is not allowed to call any ThreadX SMP API with a suspension option.
Initialization, threads, timers, and ISRs
TX_EVENT_FLAGS_GROUPmy_group;
/* Register the "my_event_flags_set_notify" function for monitoring
event flags set in the event flags group "my_group." */
status = tx_event_flags_set_notify(&my_group,
my_event_flags_set_notify);
/* If status is TX_SUCCESS the event flags set notification function
was successfully registered. */
void my_event_flags_set_notify(TX_EVENT_FLAGS_GROUP *group_ptr)
/* One or more event flags was set in this group! */
Enable and disable interrupts
UINT tx_interrupt_control(UINT new_posture);
This service enables or disables interrupts as specified by the input parameter new_posture.
Important: If this service is called from an application thread, the interrupt posture remains part of that thread’s context. For example, if the thread calls this routine to disable interrupts and then suspends, when it is resumed, interrupts are disabled again.
Warning: This service should not be used to enable interrupts during initialization! Doing so could cause unpredictable results.
Threads, timers, and ISRs
No
UINT my_old_posture;
/* Lockout interrupts */
my_old_posture = tx_interrupt_control(TX_INT_DISABLE);
/* Perform critical operations that need interrupts
locked-out.... */
/* Restore previous interrupt lockout posture. */
tx_interrupt_control(my_old_posture);
None
Create mutual exclusion mutex
UINT tx_mutex_create(TX_MUTEX *mutex_ptr,
CHAR *name_ptr, UINT priority_inherit);
This service creates a mutex for inter-thread mutual exclusion for resource protection.
Initialization and threads
No
TX_MUTEX my_mutex;
UINT status;
/* Create a mutex to provide protection over a
common resource. */
status = tx_mutex_create(&my_mutex,"my_mutex_name",
TX_NO_INHERIT);
/* If status equals TX_SUCCESS, my_mutex is ready for
use. */
Delete mutual exclusion mutex
UINT tx_mutex_delete(TX_MUTEX *mutex_ptr);
This service deletes the specified mutex. All threads suspended waiting for the mutex are resumed and given a TX_DELETED return status.
Important: It is the application’s responsibility to prevent use of a deleted mutex.
Threads
Yes
TX_MUTEX my_mutex;
UINT status;
/* Delete a mutex. Assume that the mutex
has already been created. */
status = tx_mutex_delete(&my_mutex);
/* If status equals TX_SUCCESS, the mutex is
deleted. */
Obtain ownership of mutex
UINT tx_mutex_get(TX_MUTEX *mutex_ptr, ULONG wait_option);
This service attempts to obtain exclusive ownership of the specified mutex. If the calling thread already owns the mutex, an internal counter is incremented and a successful status is returned.
If the mutex is owned by another thread and this thread is higher priority and priority inheritance was specified at mutex create, the lower priority thread’s priority will be temporarily raised to that of the calling thread.
Important: The priority of the lower priority thread owning a mutex with priority inheritance should never be modified by an external thread during mutex ownership.
Selecting TX_NO_WAIT results in an immediate return from this service regardless of whether or not it was successful. This is the only valid option if the service is called from Initialization.
Selecting TX_WAIT_FOREVER causes the calling thread to suspend indefinitely until the mutex is available.
Selecting a numeric value (1-0xFFFFFFFE) specifies the maximum number of timer-ticks to stay suspended while waiting for the mutex.
Initialization and threads and timers
Yes
TX_MUTEX my_mutex;
UINT status;
/* Obtain exclusive ownership of the mutex "my_mutex".
If the mutex "my_mutex" is not available, suspend until it
becomes available. */
status = tx_mutex_get(&my_mutex, TX_WAIT_FOREVER);
Retrieve information about mutex
UINT tx_mutex_info_get(TX_MUTEX *mutex_ptr, CHAR **name,
ULONG *count, TX_THREAD **owner,
TX_THREAD **first_suspended,
ULONG *suspended_count, TX_MUTEX **next_mutex);
This service retrieves information from the specified mutex.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
No
TX_MUTEX my_mutex;
CHAR *name;
ULONG count;
TX_THREAD *owner;
TX_THREAD *first_suspended;
ULONG suspended_count;
TX_MUTEX *next_mutex;
UINT status;
/* Retrieve information about the previously created
mutex "my_mutex." */
status = tx_mutex_info_get(&my_mutex, &name,
&count, &owner,
&first_suspended, &suspended_count,
&next_mutex);
/* If status equals TX_SUCCESS, the information requested is
valid. */
Get mutex performance information
UINT tx_mutex_performance_info_get(TX_MUTEX *mutex_ptr, ULONG *puts,
ULONG *gets, ULONG *suspensions, ULONG *timeouts,
ULONG *inversions, ULONG *inheritances);
This service retrieves performance information about the specified mutex.
Important: The ThreadX SMP library and application must be built with TX_MUTEX_ENABLE_PERFORMANCE_INFO defined for this service to return performance information.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
TX_MUTEX my_mutex;
ULONG puts;
ULONG gets;
ULONG suspensions;
ULONG timeouts;
ULONG inversions;
ULONG inheritances;
/* Retrieve performance information on the previously created
mutex. */
status = tx_mutex_performance_info_get(&my_mutex_ptr, &puts, &gets,
&suspensions, &timeouts, &inversions,
&inheritances);
/* If status is TX_SUCCESS the performance information was
successfully retrieved. */
Get mutex system performance information
UINT tx_mutex_performance_system_info_get(ULONG *puts, ULONG *gets,
ULONG *suspensions, ULONG *timeouts,
ULONG *inversions, ULONG *inheritances);
This service retrieves performance information about all the mutexes in the system.
Important: The ThreadX SMP library and application must be built with TX_MUTEX_ENABLE_PERFORMANCE_INFO defined for this service to return performance information.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
ULONG puts;
ULONG gets;
ULONG suspensions;
ULONG timeouts;
ULONG inversions;
ULONG inheritances;
/* Retrieve performance information on all previously created
mutexes. */
status = tx_mutex_performance_system_info_get(&puts, &gets,
&suspensions, &timeouts,
&inversions, &inheritances);
/* If status is TX_SUCCESS the performance information was
successfully retrieved. */
Prioritize mutex suspension list
UINT tx_mutex_prioritize(TX_MUTEX *mutex_ptr);
This service places the highest priority thread suspended for ownership of the mutex at the front of the suspension list. All other threads remain in the same FIFO order they were suspended in.
Initialization, threads, timers, and ISRs
No
TX_MUTEX my_mutex;
UINT status;
/* Ensure that the highest priority thread will receive
ownership of the mutex when it becomes available. */
status = tx_mutex_prioritize(&my_mutex);
/* If status equals TX_SUCCESS, the highest priority
suspended thread is at the front of the list. The
next tx_mutex_put call that releases ownership of the
mutex will give ownership to this thread and wake it
up. */
Release ownership of mutex
UINT tx_mutex_put(TX_MUTEX *mutex_ptr);
This service decrements the ownership count of the specified mutex. If the ownership count is zero, the mutex is made available.
Important: If priority inheritance was selected during mutex creation, the priority of the releasing thread will be restored to the priority it had when it originally obtained ownership of the mutex. Any other priority changes made to the releasing thread during ownership of the mutex may be undone.
Initialization and threads and timers
Yes
TX_MUTEX my_mutex;
UINT status;
/* Release ownership of "my_mutex." */
status = tx_mutex_put(&my_mutex);
/* If status equals TX_SUCCESS, the mutex ownership
count has been decremented and if zero, released. */
Create message queue
UINT tx_queue_create(TX_QUEUE *queue_ptr, CHAR *name_ptr,
UINT message_size,
VOID *queue_start, ULONG queue_size);
This service creates a message queue that is typically used for interthread communication. The total number of messages is calculated from the specified message size and the total number of bytes in the queue.
Important: If the total number of bytes specified in the queue’s memory area is not evenly divisible by the specified message size, the remaining bytes in the memory area are not used.
Initialization and threads
No
TX_QUEUE my_queue;
UINT status;
/* Create a message queue whose total size is 2000 bytes
starting at address 0x300000. Each message in this
queue is defined to be 4 32-bit words long. */
status = tx_queue_create(&my_queue, "my_queue_name",
4, (VOID *) 0x300000, 2000);
/* If status equals TX_SUCCESS, my_queue contains room
for storing 125 messages (2000 bytes/ 16 bytes per
message). */
Delete message queue
UINT tx_queue_delete(TX_QUEUE *queue_ptr);
This service deletes the specified message queue. All threads suspended waiting for a message from this queue are resumed and given a TX_DELETED return status.
Important: The application must ensure that any send notify callback for this queue is completed (or disabled) before deleting the queue. In addition, the application must prevent any future use of a deleted queue.
It is also the application’s responsibility to manage the memory area associated with the queue, which is available after this service completes.
Threads
Yes
TX_QUEUE my_queue;
UINT status;
/* Delete entire message queue. Assume that the queue
has already been created with a call to
tx_queue_create. */
status = tx_queue_delete(&my_queue);
/* If status equals TX_SUCCESS, the message queue is
deleted. */
Empty messages in message queue
UINT tx_queue_flush(TX_QUEUE *queue_ptr);
This service deletes all messages stored in the specified message queue. If the queue is full, messages of all suspended threads are discarded. Each suspended thread is then resumed with a return status that indicates the message send was successful. If the queue is empty, this service does nothing.
Initialization, threads, timers, and ISRs
Yes
TX_QUEUE my_queue;
UINT status;
/* Flush out all pending messages in the specified message
queue. Assume that the queue has already been created
with a call to tx_queue_create. */
status = tx_queue_flush(&my_queue);
/* If status equals TX_SUCCESS, the message queue is
empty. */
Send message to the front of queue
UINT tx_queue_front_send(TX_QUEUE *queue_ptr,
VOID *source_ptr, ULONG wait_option);
This service sends a message to the front location of the specified message queue. The message is copied to the front of the queue from the memory area specified by the source pointer.
Selecting TX_NO_WAIT results in an immediate return from this service regardless of whether or not it was successful. This is the only valid option if the service is called from a non-thread; e.g., Initialization, timer, or ISR.
Selecting TX_WAIT_FOREVER causes the calling thread to suspend indefinitely until there is room in the queue.
Selecting a numeric value (1-0xFFFFFFFE) specifies the maximum number of timer-ticks to stay suspended while waiting for room in the queue.
Initialization, threads, timers, and ISRs
Yes
TX_QUEUE my_queue;
UINT status;
ULONG my_message[4];
/* Send a message to the front of "my_queue." Return
immediately, regardless of success. This wait
option is used for calls from initialization, timers,
and ISRs. */
status = tx_queue_front_send(&my_queue, my_message,
TX_NO_WAIT);
/* If status equals TX_SUCCESS, the message is at the front
of the specified queue. */
Retrieve information about queue
UINT tx_queue_info_get(TX_QUEUE *queue_ptr, CHAR **name,
ULONG *enqueued, ULONG *available_storage
TX_THREAD **first_suspended, ULONG *suspended_count,
TX_QUEUE **next_queue);
This service retrieves information about the specified message queue.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
No
TX_QUEUE my_queue;
CHAR *name;
ULONG enqueued;
ULONG available_storage;
TX_THREAD *first_suspended;
ULONG suspended_count;
TX_QUEUE *next_queue;
UINT status;
/* Retrieve information about the previously created
message queue "my_queue." */
status = tx_queue_info_get(&my_queue, &name,
&enqueued, &available_storage,
&first_suspended, &suspended_count,
&next_queue);
/* If status equals TX_SUCCESS, the information requested is
valid. */
Get queue performance information
UINT tx_queue_performance_info_get(TX_QUEUE *queue_ptr,
ULONG *messages_sent, ULONG *messages_received,
ULONG *empty_suspensions, ULONG *full_suspensions,
ULONG *full_errors, ULONG *timeouts);
This service retrieves performance information about the specified queue.
Important: The ThreadX SMP library and application must be built with TX_QUEUE_ENABLE_PERFORMANCE_INFO defined for this service to return performance information.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
TX_QUEUE my_queue;
ULONG messages_sent;
ULONG messages_received;
ULONG empty_suspensions;
ULONG full_suspensions;
ULONG full_errors;
ULONG timeouts;
/* Retrieve performance information on the previously created
queue. */
status = tx_queue_performance_info_get(&my_queue, &messages_sent,
&messages_received, &empty_suspensions,
&full_suspensions, &full_errors, &timeouts);
/* If status is TX_SUCCESS the performance information was
successfully retrieved. */
Get queue system performance information
UINT tx_queue_performance_system_info_get(ULONG *messages_sent,
ULONG *messages_received, ULONG *empty_suspensions,
ULONG *full_suspensions, ULONG *full_errors,
ULONG *timeouts);
This service retrieves performance information about all the queues in the system.
Important: The ThreadX SMP library and application must be built with TX_QUEUE_ENABLE_PERFORMANCE_INFO defined for this service to return performance information.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
ULONG messages_sent;
ULONG messages_received;
ULONG empty_suspensions;
ULONG full_suspensions;
ULONG full_errors;
ULONG timeouts;
/* Retrieve performance information on all previously created
queues. */
status = tx_queue_performance_system_info_get(&messages_sent,
&messages_received, &empty_suspensions,
&full_suspensions, &full_errors, &timeouts);
/* If status is TX_SUCCESS the performance information was
successfully retrieved. */
Prioritize queue suspension list
UINT tx_queue_prioritize(TX_QUEUE *queue_ptr);
This service places the highest priority thread suspended for a message (or to place a message) on this queue at the front of the suspension list. All other threads remain in the same FIFO order they were suspended in.
Initialization, threads, timers, and ISRs
No
TX_QUEUE my_queue;
UINT status;
/* Ensure that the highest priority thread will receive
the next message placed on this queue. */
status = tx_queue_prioritize(&my_queue);
/* If status equals TX_SUCCESS, the highest priority
suspended thread is at the front of the list. The
next tx_queue_send or tx_queue_front_send call made
to this queue will wake up this thread. */
Get message from message queue
UINT tx_queue_receive(TX_QUEUE *queue_ptr,
VOID *destination_ptr, ULONG wait_option);
This service retrieves a message from the specified message queue. The retrieved message is copied from the queue into the memory area specified by the destination pointer. That message is then removed from the queue.
Warning: The specified destination memory area must be large enough to hold the message; i.e., the message destination pointed to by destination_ptr must be at least as large as the message size for this queue. Otherwise, if the destination is not large enough, memory corruption occurs in the following memory area.
Selecting TX_NO_WAIT results in an immediate return from this service regardless of whether or not it was successful. This is the only valid option if the service is called from a non-thread; e.g., Initialization, timer, or ISR.
Selecting TX_WAIT_FOREVER causes the calling thread to suspend indefinitely until a message is available.
Selecting a numeric value (1-0xFFFFFFFE) specifies the maximum number of timer-ticks to stay suspended while waiting for a message.
Initialization, threads, timers, and ISRs
Yes
TX_QUEUE my_queue;
UINT status;
ULONG my_message[4];
/* Retrieve a message from "my_queue." If the queue is
empty, suspend until a message is present. Note that
this suspension is only possible from application
threads. */
status = tx_queue_receive(&my_queue, my_message,
TX_WAIT_FOREVER);
/* If status equals TX_SUCCESS, the message is in
"my_message." */
Send message to message queue
UINT tx_queue_send(TX_QUEUE *queue_ptr,
VOID *source_ptr, ULONG wait_option);
This service sends a message to the specified message queue. The sent message is copied to the queue from the memory area specified by the source pointer.
Selecting TX_NO_WAIT results in an immediate return from this service regardless of whether or not it was successful. This is the only valid option if the service is called from a non-thread; e.g., Initialization, timer, or ISR.
Selecting TX_WAIT_FOREVER causes the calling thread to suspend indefinitely until there is room in the queue.
Selecting a numeric value (1-0xFFFFFFFE) specifies the maximum number of timer-ticks to stay suspended while waiting for room in the queue.
Initialization, threads, timers, and ISRs
Yes
TX_QUEUE my_queue;
UINT status;
ULONG my_message[4];
/* Send a message to "my_queue." Return immediately,
regardless of success. This wait option is used for
calls from initialization, timers, and ISRs. */
status = tx_queue_send(&my_queue, my_message, TX_NO_WAIT);
/* If status equals TX_SUCCESS, the message is in the
queue. */
Notify application when message is sent to queue
UINT tx_queue_send_notify(TX_QUEUE *queue_ptr,
VOID (*queue_send_notify)(TX_QUEUE *));
This service registers a notification callback function that is called whenever a message is sent to the specified queue. The processing of the notification callback is defined by the application.
Note: The application’s queue send notification callback is not allowed to call any ThreadX SMP API with a suspension option.
Initialization, threads, timers, and ISRs
TX_QUEUE my_queue;
/* Register the "my_queue_send_notify" function for monitoring
messages sent to the queue "my_queue." */
status = tx_queue_send_notify(&my_queue, my_queue_send_notify);
/* If status is TX_SUCCESS the queue send notification function was
successfully registered. */
void my_queue_send_notify(TX_QUEUE *queue_ptr)
{
/* A message was just sent to this queue! */
}
Place an instance in counting semaphore with ceiling
UINT tx_semaphore_ceiling_put(TX_SEMAPHORE *semaphore_ptr,
ULONG ceiling);
This service puts an instance into the specified counting semaphore, which in reality increments the counting semaphore by one. If the counting semaphore’s current value is greater than or equal to the specified ceiling, the instance will not be put and a TX_CEILING_EXCEEDED error will be returned.
Initialization, threads, timers, and ISRs
TX_SEMAPHORE my_semaphore;
/* Increment the counting semaphore "my_semaphore" but make sure
that it never exceeds 7 as specified in the call. */
status = tx_semaphore_ceiling_put(&my_semaphore, 7);
/* If status is TX_SUCCESS the semaphore count has been
Create counting semaphore
UINT tx_semaphore_create(TX_SEMAPHORE *semaphore_ptr,
CHAR *name_ptr, ULONG initial_count);
This service creates a counting semaphore for inter-thread synchronization. The initial semaphore count is specified as an input parameter.
Initialization and threads
No
TX_SEMAPHORE my_semaphore;
UINT status;
/* Create a counting semaphore whose initial value is 1.
This is typically the technique used to make a binary
semaphore. Binary semaphores are used to provide
protection over a common resource. */
status = tx_semaphore_create(&my_semaphore,
"my_semaphore_name", 1);
/* If status equals TX_SUCCESS, my_semaphore is ready for
use. */
Delete counting semaphore
UINT tx_semaphore_delete(TX_SEMAPHORE *semaphore_ptr);
This service deletes the specified counting semaphore. All threads suspended waiting for a semaphore instance are resumed and given a TX_DELETED return status.
Important: The application must ensure that a put notify callback for this semaphore is completed (or disabled) before deleting the semaphore. In addition, the application must prevent all future use of a deleted semaphore.
Threads
Yes
TX_SEMAPHORE my_semaphore;
UINT status;
/* Delete counting semaphore. Assume that the counting
semaphore has already been created. */
status = tx_semaphore_delete(&my_semaphore);
/* If status equals TX_SUCCESS, the counting semaphore is
deleted. */
Get instance from counting semaphore
UINT tx_semaphore_get(TX_SEMAPHORE *semaphore_ptr,
ULONG wait_option)
This service retrieves an instance (a single count) from the specified counting semaphore. As a result, the specified semaphore’s count is decreased by one.
Selecting TX_NO_WAIT results in an immediate return from this service regardless of whether or not it was successful. This is the only valid option if the service is called from a non-thread; e.g., initialization, timer, or ISR.
Selecting TX_WAIT_FOREVER causes the calling thread to suspend indefinitely until a semaphore instance is available.
Selecting a numeric value (1-0xFFFFFFFE) specifies the maximum number of timer-ticks to stay suspended while waiting for a semaphore instance.
Initialization, threads, timers, and ISRs
Yes
TX_SEMAPHORE my_semaphore;
UINT status;
/* Get a semaphore instance from the semaphore
"my_semaphore." If the semaphore count is zero,
suspend until an instance becomes available.
Note that this suspension is only possible from
application threads. */
status = tx_semaphore_get(&my_semaphore, TX_WAIT_FOREVER);
/* If status equals TX_SUCCESS, the thread has obtained
an instance of the semaphore. */
Retrieve information about semaphore
UINT tx_semaphore_info_get(TX_SEMAPHORE *semaphore_ptr,
CHAR **name, ULONG *current_value,
TX_THREAD **first_suspended,
ULONG *suspended_count,
TX_SEMAPHORE **next_semaphore)
This service retrieves information about the specified semaphore.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
No
TX_SEMAPHORE my_semaphore;
CHAR *name;
ULONG current_value;
TX_THREAD *first_suspended;
ULONG suspended_count;
TX_SEMAPHORE *next_semaphore;
UINT status;
/* Retrieve information about the previously created
semaphore "my_semaphore." */
status = tx_semaphore_info_get(&my_semaphore, &name,
¤t_value,
&first_suspended, &suspended_count,
&next_semaphore);
/* If status equals TX_SUCCESS, the information requested is
valid. */
Get semaphore performance information
UINT tx_semaphore_performance_info_get(TX_SEMAPHORE *semaphore_ptr,
ULONG *puts, ULONG *gets,
ULONG *suspensions, ULONG *timeouts);
This service retrieves performance information about the specified semaphore.
Note: The ThreadX SMP library and application must be built with TX_SEMAPHORE_ENABLE_PERFORMANCE_INFO defined for this service to return performance information.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
TX_SEMAPHORE my_semaphore;
ULONG puts;
ULONG gets;
ULONG suspensions;
ULONG timeouts;
/* Retrieve performance information on the previously created
semaphore. */
status = tx_semaphore_performance_info_get(&my_semaphore, &puts,
&gets, &suspensions, &timeouts);
/* If status is TX_SUCCESS the performance information was
successfully retrieved. */
Get semaphore system performance information
UINT tx_semaphore_performance_system_info_get(ULONG *puts,
ULONG *gets, ULONG *suspensions, ULONG *timeouts);
This service retrieves performance information about all the semaphores in the system.
Important: The ThreadX SMP library and application must be built with TX_SEMAPHORE_ENABLE_PERFORMANCE_INFO defined for this service to return performance information.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
ULONG puts;
ULONG gets;
ULONG suspensions;
ULONG timeouts;
/* Retrieve performance information on all previously created
semaphores. */
status = tx_semaphore_performance_system_info_get(&puts, &gets,
&suspensions, &timeouts);
/* If status is TX_SUCCESS the performance information was
successfully retrieved. */
Prioritize semaphore suspension list
UINT tx_semaphore_prioritize(TX_SEMAPHORE *semaphore_ptr);
This service places the highest priority thread suspended for an instance of the semaphore at the front of the suspension list. All other threads remain in the same FIFO order they were suspended in.
Initialization, threads, timers, and ISRs
No
TX_SEMAPHORE my_semaphore;
UINT status;
/* Ensure that the highest priority thread will receive
the next instance of this semaphore. */
status = tx_semaphore_prioritize(&my_semaphore);
/* If status equals TX_SUCCESS, the highest priority
suspended thread is at the front of the list. The
next tx_semaphore_put call made to this semaphore will
wake up this thread. */
Place an instance in counting semaphore
UINT tx_semaphore_put(TX_SEMAPHORE *semaphore_ptr);
This service puts an instance into the specified counting semaphore, which in reality increments the counting semaphore by one.
Important: If this service is called when the semaphore is all ones (OxFFFFFFFF), the new put operation will cause the semaphore to be reset to zero.
Initialization, threads, timers, and ISRs
Yes
TX_SEMAPHORE my_semaphore;
UINT status;
/* Increment the counting semaphore "my_semaphore." */
status = tx_semaphore_put(&my_semaphore);
/* If status equals TX_SUCCESS, the semaphore count has
been incremented. Of course, if a thread was waiting,
it was given the semaphore instance and resumed. */
Notify application when semaphore is put
UINT tx_semaphore_put_notify(TX_SEMAPHORE *semaphore_ptr,
VOID (*semaphore_put_notify)(TX_SEMAPHORE *));
This service registers a notification callback function that is called whenever the specified semaphore is put. The processing of the notification callback is defined by the application.
Note: The application’s semaphore notification callback is not allowed to call any ThreadX SMP API with a suspension option.
Initialization, threads, timers, and ISRs
TX_SEMAPHORE my_semaphore;
/* Register the "my_semaphore_put_notify" function for monitoring
the put operations on the semaphore "my_semaphore." */
status = tx_semaphore_put_notify(&my_semaphore,
my_semaphore_put_notify);
/* If status is TX_SUCCESS the semaphore put notification function
was successfully registered. */
void my_semaphore_put_notify(TX_SEMAPHORE *semaphore_ptr)
{
/* The semaphore was just put! */
}
Create application thread
UINT tx_thread_create(TX_THREAD *thread_ptr,
CHAR *name_ptr, VOID (*entry_function)(ULONG),
ULONG entry_input, VOID *stack_start,
ULONG stack_size, UINT priority,
UINT preempt_threshold, ULONG time_slice,
UINT auto_start);
This service creates an application thread that starts execution at the specified task entry function. The stack, priority, preemption-threshold, and time-slice are among the attributes specified by the input parameters. In addition, the initial execution state of the thread is also specified.
time_slice: Number of timer-ticks this thread is allowed to run before other ready threads of the same priority are given a chance to run. Note that using preemption-threshold disables time-slicing. Legal time-slice values range from 1 to 0xFFFFFFFF (inclusive). A value of TX_NO_TIME_SLICE (a value of 0) disables time-slicing of this thread.
Important: Using time-slicing results in a slight amount of system overhead. Since time-slicing is only useful in cases where multiple threads share the same priority, threads having a unique priority should not be assigned a time-slice.
Initialization and threads
Yes
TX_THREAD my_thread;
UINT status;
/* Create a thread of priority 15 whose entry point is
"my_thread_entry". This thread's stack area is 1000
bytes in size, starting at address 0x400000. The
preemption-threshold is setup to allow preemption of threads
with priorities ranging from 0 through 14. Time-slicing is
disabled. This thread is automatically put into a ready
condition. */
status = tx_thread_create(&my_thread, "my_thread_name",
my_thread_entry, 0x1234,
(VOID *) 0x400000, 1000,
15, 15, TX_NO_TIME_SLICE,
TX_AUTO_START);
/* If status equals TX_SUCCESS, my_thread is ready
for execution! */
...
/* Thread's entry function. When "my_thread" actually
begins execution, control is transferred to this
function. */
VOID my_thread_entry (ULONG initial_input)
{
/* When we get here, the value of initial_input is
0x1234. See how this was specified during
creation. */
/* The real work of the thread, including calls to
other function should be called from here! */
/* When this function returns, the corresponding
thread is placed into a "completed" state. */
}
Delete application thread
UINT tx_thread_delete(TX_THREAD *thread_ptr);
This service deletes the specified application thread. Since the specified thread must be in a terminated or completed state, this service cannot be called from a thread attempting to delete itself.
Important: It is the application’s responsibility to manage the memory area associated with the thread’s stack, which is available after this service completes. In addition, the application must prevent use of a deleted thread.
Threads and timers
No
TX_THREAD my_thread;
UINT status;
/* Delete an application thread whose control block is
"my_thread". Assume that the thread has already been
created with a call to tx_thread_create. */
status = tx_thread_delete(&my_thread);
/* If status equals TX_SUCCESS, the application thread is
deleted. */
Notify application upon thread entry and exit
UINT tx_thread_entry_exit_notify(TX_THREAD *thread_ptr,
VOID (*entry_exit_notify)(TX_THREAD *, UINT));
This service registers a notification callback function that is called whenever the specified thread is entered or exits. The processing of the notification callback is defined by the application.
Note: The application’s thread entry/exit notification callback is not allowed to call any ThreadX SMP API with a suspension option.
Initialization, threads, timers, and ISRs
TX_THREAD my_thread;
/* Register the "my_entry_exit_notify" function for monitoring
the entry/exit of the thread "my_thread." */
status = tx_thread_entry_exit_notify(&my_thread,
my_entry_exit_notify);
/* If status is TX_SUCCESS the entry/exit notification function was
successfully registered. */
void my_entry_exit_notify(TX_THREAD *thread_ptr, UINT condition)
{
/* Determine if the thread was entered or exited. */
if (condition == TX_THREAD_ENTRY)
/* Thread entry! */
else if (condition == TX_THREAD_EXIT)
/* Thread exit! */
}
Retrieves pointer to currently executing thread
TX_THREAD* tx_thread_identify(VOID);
This service returns a pointer to the currently executing thread. If no thread is executing, this service returns a null pointer.
Important: If this service is called from an ISR, the return value represents the thread running prior to the executing interrupt handler.
None
Threads and ISRs
No
TX_THREAD *my_thread_ptr;
/* Find out who we are! */
my_thread_ptr = tx_thread_identify();
/* If my_thread_ptr is non-null, we are currently executing
from that thread or an ISR that interrupted that thread.
Otherwise, this service was called
from an ISR when no thread was running when the
interrupt occurred. */
Retrieve information about thread
UINT tx_thread_info_get(TX_THREAD *thread_ptr, CHAR **name,
UINT *state, ULONG *run_count,
UINT *priority,
UINT *preemption_threshold,
ULONG *time_slice,
TX_THREAD **next_thread,
TX_THREAD **suspended_thread);
This service retrieves information about the specified thread.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
No
TX_THREAD my_thread;
CHAR *name;
UINT state;
ULONG run_count;
UINT priority;
UINT preemption_threshold;
UINT time_slice;
TX_THREAD *next_thread;
TX_THREAD *suspended_thread;
UINT status;
/* Retrieve information about the previously created
thread "my_thread." */
status = tx_thread_info_get(&my_thread, &name,
&state, &run_count,
&priority, &preemption_threshold,
&time_slice, &next_thread,&suspended_thread);
/* If status equals TX_SUCCESS, the information requested is
valid. */
Get thread performance information
UINT tx_thread_performance_info_get(TX_THREAD *thread_ptr,
ULONG *resumptions, ULONG *suspensions,
ULONG *solicited_preemptions, ULONG *interrupt_preemptions,
ULONG *priority_inversions, ULONG *time_slices,
ULONG *relinquishes, ULONG *timeouts, ULONG *wait_aborts,
TX_THREAD **last_preempted_by);
This service retrieves performance information about the specified thread.
Important: The ThreadX SMP library and application must be built with TX_THREAD_ENABLE_PERFORMANCE_INFO defined in order for this service to return performance information.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
TX_THREAD my_thread;
ULONG resumptions;
ULONG suspensions;
ULONG solicited_preemptions;
ULONG interrupt_preemptions;
ULONG priority_inversions;
ULONG time_slices;
ULONG relinquishes;
ULONG timeouts;
ULONG wait_aborts;
TX_THREAD *last_preempted_by;
/* Retrieve performance information on the previously created
thread. */
status = tx_thread_performance_info_get(&my_thread, &resumptions,
&suspensions,
&solicited_preemptions, &interrupt_preemptions,
&priority_inversions, &time_slices,
&relinquishes, &timeouts,
&wait_aborts, &last_preempted_by);
/* If status is TX_SUCCESS the performance information was
successfully retrieved. */
Get thread system performance information
UINT tx_thread_performance_system_info_get(ULONG *resumptions,
ULONG *suspensions, ULONG *solicited_preemptions,
ULONG *interrupt_preemptions, ULONG *priority_inversions,
ULONG *time_slices, ULONG *relinquishes, ULONG *timeouts,
ULONG *wait_aborts, ULONG *non_idle_returns,
ULONG *idle_returns);
This service retrieves performance information about all the threads in the system.
Important: The ThreadX SMP library and application must be built with TX_THREAD_ENABLE_PERFORMANCE_INFO defined in order for this service to return performance information.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
ULONG resumptions;
ULONG suspensions;
ULONG solicited_preemptions;
ULONG interrupt_preemptions;
ULONG priority_inversions;
ULONG time_slices;
ULONG relinquishes;
ULONG timeouts;
ULONG wait_aborts;
ULONG non_idle_returns;
ULONG idle_returns;
/* Retrieve performance information on all previously created
thread. */
status = tx_thread_performance_system_info_get(&resumptions,
&suspensions,
&solicited_preemptions, &interrupt_preemptions,
&priority_inversions, &time_slices, &relinquishes,
&timeouts, &wait_aborts, &non_idle_returns,
&idle_returns);
/* If status is TX_SUCCESS the performance information was
successfully retrieved. */
Change preemption-threshold of application thread
UINT tx_thread_preemption_change(TX_THREAD *thread_ptr,
UINT new_threshold, UINT *old_threshold);
This service changes the preemption-threshold of the specified thread. The preemption-threshold prevents preemption of the specified thread by threads equal to or less than the preemption-threshold value.
Important: Using preemption-threshold disables time-slicing for the specified thread.
Threads and timers
Yes
TX_THREAD my_thread;
UINT my_old_threshold;
UINT status;
/* Disable all preemption of the specified thread. The
current preemption-threshold is returned in
"my_old_threshold". Assume that "my_thread" has
already been created. */
status = tx_thread_preemption_change(&my_thread,
0, &my_old_threshold);
/* If status equals TX_SUCCESS, the application thread is
non-preemptable by another thread. Note that ISRs are
not prevented by preemption disabling. */
Change priority of application thread
UINT tx_thread_priority_change(TX_THREAD *thread_ptr,
UINT new_priority, UINT *old_priority);
This service changes the priority of the specified thread. Valid priorities range from 0 through (TX_MAX_PRIORITIES-1), where 0 represents the highest priority level.
Important: The preemption-threshold of the specified thread is automatically set to the new priority. If a new threshold is desired, the tx_thread_preemption_change service must be used after this call.
Threads and timers
Yes
TX_THREAD my_thread;
UINT my_old_priority;
UINT status;
/* Change the thread represented by "my_thread" to priority
0. */
status = tx_thread_priority_change(&my_thread,
0, &my_old_priority);
/* If status equals TX_SUCCESS, the application thread is
now at the highest priority level in the system. */
Relinquish control to other application threads
VOID tx_thread_relinquish(VOID);
This service relinquishes processor control to other ready-to-run threads at the same or higher priority.
Important: In addition to relinquishing control to threads of the same priority, this service also relinquishes control to the highest-priority thread prevented from execution because of the current thread’s preemption-threshold setting.
None
None
Threads
Yes
ULONG run_counter_1 = 0;
ULONG run_counter_2 = 0;
/* Example of two threads relinquishing control to
each other in an infinite loop. Assume that
both of these threads are ready and have the same
priority. The run counters will always stay within one
of each other. */
VOID my_first_thread(ULONG thread_input)
{
/* Endless loop of relinquish. */
while(1)
{
/* Increment the run counter. */
run_counter_1++;
/* Relinquish control to other thread. */
tx_thread_relinquish();
}
}
VOID my_second_thread(ULONG thread_input)
{
/* Endless loop of relinquish. */
while(1)
{
/* Increment the run counter. */
run_counter_2++;
/* Relinquish control to other thread. */
tx_thread_relinquish();
}
}
Reset thread
UINT tx_thread_reset(TX_THREAD *thread_ptr);
This service resets the specified thread to execute at the entry point defined at thread creation. The thread must be in either a TX_COMPLETED or TX_TERMINATED state for it to be reset
Important: The thread must be resumed for it to execute again.
Threads
TX_THREAD my_thread;
/* Reset the previously created thread "my_thread." */
status = tx_thread_reset(&my_thread);
/* If status is TX_SUCCESS the thread is reset. */
Resume suspended application thread
UINT tx_thread_resume(TX_THREAD *thread_ptr);
This service resumes or prepares for execution a thread that was previously suspended by a tx_thread_suspend call. In addition, this service resumes threads that were created without an automatic start.
Initialization, threads, timers, and ISRs
Yes
TX_THREAD my_thread;
UINT status;
/* Resume the thread represented by "my_thread". */
status = tx_thread_resume(&my_thread);
/* If status equals TX_SUCCESS, the application thread is
now ready to execute. */
Suspend current thread for specified time
UINT tx_thread_sleep(ULONG timer_ticks);
This service causes the calling thread to suspend for the specified number of timer ticks. The amount of physical time associated with a timer tick is application specific. This service can be called only from an application thread.
Threads
Yes
UINT status;
/* Make the calling thread sleep for 100
timer-ticks. */
status = tx_thread_sleep(100);
/* If status equals TX_SUCCESS, the currently running
application thread slept for the specified number of
timer-ticks. */
Exclude thread execution on a set of cores
UINT tx_thread_smp_core_exclude(TX_THREAD *thread_ptr,
ULONG exclusion_map);
This function excludes the specified thread from executing on the core(s) specified in the bit map called “exclusion_map.” Each bit in “exclusion_map” represents a core (bit 0 represents core 0, etc.). If the bit is set, the corresponding core is excluded from executing the specified thread.
Important: Use of processor exclusion may cause additional processing in the thread to core mapping logic in order to find the optimal match. This processing is bounded by the number of ready threads.
Initialization, ISRs, threads, and timers
/* Exclude core 0 for "Thread 0". */
tx_thread_smp_core_exclude(&thread_0, 0x01);
Gets the thread’s current core exclusion
UINT tx_thread_smp_core_exclude_get(TX_THREAD *thread_ptr,
ULONG *exclusion_map_ptr);
This function returns the current core exclusion list.
Initialization, ISRs, threads, and timers
ULONGexcluded_cores;
/* Retrieve the core exclusion for "Thread 0". */
tx_thread_smp_core_exclude_get(&thread_0, &excluded_cores);
Retrieve currently executing core of caller
UINT tx_thread_smp_core_get(void);
This function returns the core ID of the core executing this service.
None
Initialization, ISRs, threads, and timers
UINTcore;
/* Pickup the currently executing core. */
core = tx_thread_smp_core_get();
/* At this point, "core" contains the executing core ID. */
Register thread stack error notification callback
UINT tx_thread_stack_error_notify(VOID (*error_handler)(TX_THREAD *));
This service registers a notification callback function for handling thread stack errors. When ThreadX SMP detects a thread stack error during execution, it will call this notification function to process the error. Processing of the error is completely defined by the application. Anything from suspending the violating thread to resetting the entire system may be done.
Important: The ThreadX SMP library must be built with TX_ENABLE_STACK_CHECKING defined in order for this service to return performance information.
Initialization, threads, timers, and ISRs
void my_stack_error_handler(TX_THREAD *thread_ptr);
/* Register the "my_stack_error_handler" function with ThreadX SMP
so that thread stack errors can be handled by the application. */
status = tx_thread_stack_error_notify(my_stack_error_handler);
/* If status is TX_SUCCESS the stack error handler is registered.*/
Suspend application thread
UINT tx_thread_suspend(TX_THREAD *thread_ptr);
This service suspends the specified application thread. A thread may call this service to suspend itself.
Important: If the specified thread is already suspended for another reason, this suspension is held internally until the prior suspension is lifted. When that happens, this unconditional suspension of the specified thread is performed. Further unconditional suspension requests have no effect.
After being suspended, the thread must be resumed by tx_thread_resume to execute again.
Initialization, threads, timers, and ISRs
Yes
TX_THREAD my_thread;
UINT status;
/* Suspend the thread represented by "my_thread". */
status = tx_thread_suspend(&my_thread);
/* If status equals TX_SUCCESS, the application thread is
unconditionally suspended. */
Terminates application thread
UINT tx_thread_terminate(TX_THREAD *thread_ptr);
This service terminates the specified application thread regardless of whether the thread is suspended or not. A thread may call this service to terminate itself.
Important: After being terminated, the thread must be reset for it to execute again.
Warning: It is the application’s responsibility to ensure the thread is in a state suitable for termination. For example, a thread should not be terminated during critical application processing or inside of other middleware components where it could leave such processing in an unknown state.
Threads and timers
Yes
TX_THREAD my_thread;
UINT status;
/* Terminate the thread represented by "my_thread". */
status = tx_thread_terminate(&my_thread);
/* If status equals TX_SUCCESS, the thread is terminated
and cannot execute again until it is reset. */
Changes time-slice of application thread
UINT tx_thread_time_slice_change(TX_THREAD *thread_ptr,
ULONG new_time_slice, ULONG *old_time_slice);
This service changes the time-slice of the specified application thread. Selecting a time-slice for a thread insures that it won’t execute more than the specified number of timer ticks before other threads of the same or higher priorities have a chance to execute.
Important: Using preemption-threshold disables time-slicing for the specified thread.
Threads and timers
No
TX_THREAD my_thread;
ULONG my_old_time_slice;
UINT status;
/* Change the time-slice of the thread associated with
"my_thread" to 20. This will mean that "my_thread"
can only run for 20 timer-ticks consecutively before
other threads of equal or higher priority get a chance
to run. */
status = tx_thread_time_slice_change(&my_thread, 20,
&my_old_time_slice);
/* If status equals TX_SUCCESS, the thread's time-slice
has been changed to 20 and the previous time-slice is
in "my_old_time_slice." */
Abort suspension of specified thread
UINT tx_thread_wait_abort(TX_THREAD *thread_ptr);
This service aborts sleep or any other object suspension of the specified thread. If the wait is aborted, a TX_WAIT_ABORTED value is returned from the service that the thread was waiting on.
Important: This service does not release explicit suspension that is made by the tx_thread_suspend service.
Initialization, threads, timers, and ISRs
Yes
TX_THREAD my_thread;
UINT status;
/* Abort the suspension condition of "my_thread." */
status = tx_thread_wait_abort(&my_thread);
/* If status equals TX_SUCCESS, the thread is now ready
again, with a return value showing its suspension
was aborted (TX_WAIT_ABORTED). */
Retrieves the current time
ULONG tx_time_get(VOID);
This service returns the contents of the internal system clock. Each timertick increases the internal system clock by one. The system clock is set to zero during initialization and can be changed to a specific value by the service tx_time_set.
Important: The actual time each timer-tick represents is application specific.
None
Initialization, threads, timers, and ISRs
No
ULONG current_time;
/* Pickup the current system time, in timer-ticks. */
current_time = tx_time_get();
/* Current time now contains a copy of the internal system
clock. */
Sets the current time
VOID tx_time_set(ULONG new_time);
This service sets the internal system clock to the specified value. Each timer-tick increases the internal system clock by one.
Important: The actual time each timer-tick represents is application specific.
None
Threads, timers, and ISRs
No
/* Set the internal system time to 0x1234. */
tx_time_set(0x1234);
/* Current time now contains 0x1234 until the next timer
interrupt. */
Activate application timer
UINT tx_timer_activate(TX_TIMER *timer_ptr);
This service activates the specified application timer. The expiration routines of timers that expire at the same time are executed in the order they were activated.
Note: That an expired one-shot timer must be reset via tx_timer_change before it can be activated again.
Initialization, threads, timers, and ISRs
No
TX_TIMER my_timer;
UINT status;
/* Activate an application timer. Assume that the
application timer has already been created. */
status = tx_timer_activate(&my_timer);
/* If status equals TX_SUCCESS, the application timer is
now active. */
Change application timer
UINT tx_timer_change(TX_TIMER *timer_ptr,
ULONG initial_ticks, ULONG reschedule_ticks);
This service changes the expiration characteristics of the specified application timer. The timer must be deactivated prior to calling this service.
Important: A call to the tx_timer_activate service is required after this service in order to start the timer again.
reschedule_ticks: Specifies the number of ticks for all timer expirations after the first. A zero for this parameter makes the timer a one-shot timer. Otherwise, for periodic timers, legal values range from 1 through 0xFFFFFFFF.
Note: That an expired one-shot timer must be reset via tx_timer_change before it can be activated again.
Threads, timers, and ISRs
No
TX_TIMER my_timer;
UINT status;
/* Change a previously created and now deactivated timer
to expire every 50 timer ticks, including the initial
expiration. */
status = tx_timer_change(&my_timer,50, 50);
/* If status equals TX_SUCCESS, the specified timer is
changed to expire every 50 ticks. */
/* Activate the specified timer to get it started again. */
status = tx_timer_activate(&my_timer);
Create application timer
UINT tx_timer_create(TX_TIMER *timer_ptr, CHAR *name_ptr,
VOID (*expiration_function)(ULONG),
ULONG expiration_input, ULONG initial_ticks,
ULONG reschedule_ticks, UINT auto_activate)
This service creates an application timer with the specified expiration function and periodic.
reschedule_ticks: Specifies the number of ticks for all timer expirations after the first. A zero for this parameter makes the timer a one-shot timer. Otherwise, for periodic timers, legal values range from 1 through 0xFFFFFFFF.
Note: After a one-shot timer expires, it must be reset via tx_timer_change before it can be activated again.
Initialization and threads
No
TX_TIMER my_timer;
UINT status;
/* Create an application timer that executes
"my_timer_function" after 100 ticks initially and then
after every 25 ticks. This timer is specified to start
immediately! */
status = tx_timer_create(&my_timer,"my_timer_name",
my_timer_function, 0x1234, 100, 25,
TX_AUTO_ACTIVATE);
/* If status equals TX_SUCCESS, my_timer_function will
be called 100 timer ticks later and then called every
25 timer ticks. Note that the value 0x1234 is passed to
my_timer_function every time it is called. */
Deactivate application timer
UINT tx_timer_deactivate(TX_TIMER *timer_ptr);
This service deactivates the specified application timer. If the timer is already deactivated, this service has no effect.
Initialization, threads, timers, and ISRs
No
TX_TIMER my_timer;
UINT status;
/* Deactivate an application timer. Assume that the
application timer has already been created. */
status = tx_timer_deactivate(&my_timer);
/* If status equals TX_SUCCESS, the application timer is
now deactivated. */
Delete application timer
UINT tx_timer_delete(TX_TIMER *timer_ptr);
This service deletes the specified application timer.
Important: It is the application’s responsibility to prevent use of a deleted timer.
Threads
No
TX_TIMER my_timer;
UINT status;
/* Delete application timer. Assume that the application
timer has already been created. */
status = tx_timer_delete(&my_timer);
/* If status equals TX_SUCCESS, the application timer is
deleted. */
Retrieve information about an application timer
UINT tx_timer_info_get(TX_TIMER *timer_ptr, CHAR **name,
UINT *active, ULONG *remaining_ticks,
ULONG *reschedule_ticks,
TX_TIMER **next_timer)
This service retrieves information about the specified application timer.
Note: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
No
TX_TIMER my_timer;
CHAR *name;
UINT active;
ULONG remaining_ticks;
ULONG reschedule_ticks;
TX_TIMER *next_timer;
UINT status;
/* Retrieve information about the previously created
application timer "my_timer." */
status = tx_timer_info_get(&my_timer, &name,
&active,&remaining_ticks,
&reschedule_ticks,
&next_timer);
/* If status equals TX_SUCCESS, the information requested is
valid. */
Get timer performance information
UINT tx_timer_performance_info_get(TX_TIMER *timer_ptr,
ULONG *activates, ULONG *reactivates,
ULONG *deactivates, ULONG *expirations,
ULONG *expiration_adjusts);
This service retrieves performance information about the specified application timer.
Important: The ThreadX SMP library and application must be built with TX_TIMER_ENABLE_PERFORMANCE_INFO defined for this service to return performance information.
Important: Supplying a TX_NULL for any parameter indicates the parameter is not required.
Initialization, threads, timers, and ISRs
TX_TIMER my_timer;
ULONG activates;
ULONG reactivates;
ULONG deactivates;
ULONG expirations;
ULONG expiration_adjusts;
/* Retrieve performance information on the previously created
timer. */
status = tx_timer_performance_info_get(&my_timer, &activates,
&reactivates,&deactivates, &expirations,
&expiration_adjusts);
/* If status is TX_SUCCESS the performance information was
successfully retrieved. */
Get timer system performance information
UINT tx_timer_performance_system_info_get(ULONG *activates,
ULONG *reactivates, ULONG *deactivates,
ULONG *expirations, ULONG *expiration_adjusts);
This service retrieves performance information about all the application timers in the system.
Important: The ThreadX SMP library and application must be built with TX_TIMER_ENABLE_PERFORMANCE_INFO defined for this service to return performance information.
Important: Supplying a TX_NULL for any parameter indicates that the parameter is not required.
Initialization, threads, timers, and ISRs
ULONG activates;
ULONG reactivates;
ULONG deactivates;
ULONG expirations;
ULONG expiration_adjusts;
/* Retrieve performance information on all previously created
timers. */
status = tx_timer_performance_system_info_get(&activates,
&reactivates, &deactivates, &expirations,
&expiration_adjusts);
/* If status is TX_SUCCESS the performance information was
successfully retrieved. */
Exclude timer execution on a set of cores
UINT tx_timer_smp_core_exclude(TX_TIMER *timer_ptr, ULONG exclusion_map);
This function excludes the specified timer from executing on the core(s) specified in the bit map called “exclusion_map.” Each bit in “exclusion_map” represents a core (bit 0 represents core 0, etc.). If the bit is set, the corresponding core is excluded from executing the specified timer.
Important: Use of processor exclusion may cause additional processing in the thread to core mapping logic in order to find the optimal match. This processing is bounded by the number of ready threads.
Initialization, ISRs, threads, and timers
/* Exclude core 0 for "Timer 0". */
tx_timer_smp_core_exclude(&timer_0, 0x01);
Gets the timer’s current core exclusion
UINT tx_timer_smp_core_exclude_get(TX_TIMER *timer_ptr,
ULONG *exclusion_map_ptr);
This function returns the current core exclusion list.
Initialization, ISRs, threads, and timers
ULONGexcluded_cores;
/* Retrieve the core exclusion for "Timer 0". */
tx_timer_smp_core_exclude_get(&timer_0,&excluded_cores);