ThreadX User Guide Thread X
ThreadX_User_Guide
User Manual:
Open the PDF directly: View PDF
Page Count: 362 [warning: Documents this large are best viewed by clicking the View PDF Link!]
- Contents
- Figures
- About This Guide
- 1 Introduction to ThreadX
- 2 Installation and Use of ThreadX
- 3 Functional Components of ThreadX
- Execution Overview
- Memory Usage
- Initialization
- Thread Execution
- Thread Execution States
- Thread Entry/Exit Notification
- Thread Priorities
- Thread Scheduling
- Round-robin Scheduling
- Time-Slicing
- Preemption
- Preemption- Threshold™
- Priority Inheritance
- Thread Creation
- Thread Control Block TX_THREAD
- Currently Executing Thread
- Thread Stack Area
- Memory Pitfalls
- Optional Run-time Stack Checking
- Reentrancy
- Thread Priority Pitfalls
- Priority Overhead
- Run-time Thread Performance Information
- Debugging Pitfalls
- Message Queues
- Counting Semaphores
- Mutexes
- Event Flags
- Memory Block Pools
- Memory Byte Pools
- Application Timers
- Relative Time
- Interrupts
- 4 Description of ThreadX Services
- tx_block_allocate
- Allocate fixed-size block of memory
- Prototype
- Description
- Input Parameters
- pool_ptr Pointer to a previously created memory block pool.
- block_ptr Pointer to a destination block pointer. On successful allocation, the address of the allocated memory block is placed where this parameter points.
- wait_option Defines how the service behaves if there are no memory blocks available. The wait options are defined as follows:
- 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.
- Return Values
- TX_SUCCESS (0x00) Successful memory block allocation.
- TX_DELETED (0x01) Memory block pool was deleted while thread was suspended.
- TX_NO_MEMORY (0x10) Service was unable to allocate a block of memory within the specified time to wait.
- TX_WAIT_ABORTED (0x1A) Suspension was aborted by another thread, timer or ISR.
- TX_POOL_ERROR (0x02) Invalid memory block pool pointer.
- TX_PTR_ERROR (0x03) Invalid pointer to destination pointer.
- TX_WAIT_ERROR (0x04) A wait option other than TX_NO_WAIT was specified on a call from a non- thread.
- Allowed From
- Preemption Possible
- Example
- 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. */
- See Also
- tx_block_pool_create
- Create pool of fixed-size memory blocks
- Prototype
- Description
- Input Parameters
- Return Values
- TX_SUCCESS (0x00) Successful memory block pool creation.
- TX_POOL_ERROR (0x02) Invalid memory block pool pointer. Either the pointer is NULL or the pool is already created.
- TX_PTR_ERROR (0x03) Invalid starting address of the pool.
- TX_SIZE_ERROR (0x05) Size of pool is invalid.
- TX_CALLER_ERROR (0x13) Invalid caller of this service.
- Allowed From
- Preemption Possible
- Example
- 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. */
- See Also
- tx_block_pool_delete
- tx_block_pool_info_get
- Retrieve information about block pool
- Prototype
- Description
- Input Parameters
- pool_ptr Pointer to previously created memory block pool.
- name Pointer to destination for the pointer to the block pool’s name.
- available Pointer to destination for the number of available blocks in the block pool.
- total_blocks Pointer to destination for the total number of blocks in the block pool.
- first_suspended Pointer to destination for the pointer to the thread that is first on the suspension list of this block pool.
- suspended_count Pointer to destination for the number of threads currently suspended on this block pool.
- next_pool Pointer to destination for the pointer of the next created block pool.
- Return Values
- Allowed From
- Example
- 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. */
- See Also
- tx_block_pool_performance_info_get
- Get block pool performance information
- Prototype
- Description
- Input Parameters
- pool_ptr Pointer to previously created memory block pool.
- allocates Pointer to destination for the number of allocate requests performed on this pool.
- releases Pointer to destination for the number of release requests performed on this pool.
- suspensions Pointer to destination for the number of thread allocation suspensions on this pool.
- timeouts Pointer to destination for the number of allocate suspension timeouts on this pool.
- Return Values
- Allowed From
- Example
- 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. */
- See Also
- tx_block_pool_performance_system_info_get
- Get block pool system performance information
- Prototype
- Description
- Input Parameters
- allocates Pointer to destination for the total number of allocate requests performed on all block pools.
- releases Pointer to destination for the total number of release requests performed on all block pools.
- suspensions Pointer to destination for the total number of thread allocation suspensions on all block pools.
- timeouts Pointer to destination for the total number of allocate suspension timeouts on all block pools..
- Return Values
- Allowed From
- Example
- 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. */
- See Also
- tx_block_pool_prioritize
- Prioritize block pool suspension list
- Prototype
- Description
- Input Parameters
- Return Values
- Allowed From
- Preemption Possible
- Example
- 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. */
- See Also
- tx_block_release
- Release fixed-size block of memory
- Prototype
- Description
- Input Parameters
- Return Values
- Allowed From
- Preemption Possible
- Example
- TX_BLOCK_POOL my_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. */
- See Also
- tx_byte_allocate
- Allocate bytes of memory
- Prototype
- Description
- Input Parameters
- pool_ptr Pointer to a previously created memory pool.
- memory_ptr Pointer to a destination memory pointer. On successful allocation, the address of the allocated memory area is placed where this parameter points to.
- memory_size Number of bytes requested.
- wait_option Defines how the service behaves if there is not enough memory available. The wait options are defined as follows:
- 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.
- Return Values
- TX_SUCCESS (0x00) Successful memory allocation.
- TX_DELETED (0x01) Memory pool was deleted while thread was suspended.
- TX_NO_MEMORY (0x10) Service was unable to allocate the memory within the specified time to wait.
- TX_WAIT_ABORTED (0x1A) Suspension was aborted by another thread, timer, or ISR.
- TX_POOL_ERROR (0x02) Invalid memory pool pointer.
- TX_PTR_ERROR (0x03) Invalid pointer to destination pointer.
- TX_SIZE_ERROR (0X05) Requested size is zero or larger than the pool.
- TX_WAIT_ERROR (0x04) A wait option other than TX_NO_WAIT was specified on a call from a non- thread.
- TX_CALLER_ERROR (0x13) Invalid caller of this service.
- Allowed From
- Preemption Possible
- Example
- 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. */
- See Also
- tx_byte_pool_create
- Create memory pool of bytes
- Prototype
- Description
- Input Parameters
- Return Values
- TX_SUCCESS (0x00) Successful memory pool creation.
- TX_POOL_ERROR (0x02) Invalid memory pool pointer. Either the pointer is NULL or the pool is already created.
- TX_PTR_ERROR (0x03) Invalid starting address of the pool.
- TX_SIZE_ERROR (0x05) Size of pool is invalid.
- TX_CALLER_ERROR (0x13) Invalid caller of this service.
- Allowed From
- Preemption Possible
- Example
- See Also
- tx_byte_pool_delete
- tx_byte_pool_info_get
- Retrieve information about byte pool
- Prototype
- Description
- Input Parameters
- pool_ptr Pointer to previously created memory pool.
- name Pointer to destination for the pointer to the byte pool’s name.
- available Pointer to destination for the number of available bytes in the pool.
- fragments Pointer to destination for the total number of memory fragments in the byte pool.
- first_suspended Pointer to destination for the pointer to the thread that is first on the suspension list of this byte pool.
- suspended_count Pointer to destination for the number of threads currently suspended on this byte pool.
- next_pool Pointer to destination for the pointer of the next created byte pool.
- Return Values
- Allowed From
- Preemption Possible
- Example
- 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. */
- See Also
- tx_byte_pool_performance_info_get
- Get byte pool performance information
- Prototype
- Description
- Input Parameters
- pool_ptr Pointer to previously created memory byte pool.
- allocates Pointer to destination for the number of allocate requests performed on this pool.
- releases Pointer to destination for the number of release requests performed on this pool.
- fragments_searched Pointer to destination for the number of internal memory fragments searched during allocation requests on this pool.
- merges Pointer to destination for the number of internal memory blocks merged during allocation requests on this pool.
- splits Pointer to destination for the number of internal memory blocks split (fragments) created during allocation requests on this pool.
- suspensions Pointer to destination for the number of thread allocation suspensions on this pool.
- timeouts Pointer to destination for the number of allocate suspension timeouts on this pool.
- Return Values
- Allowed From
- Example
- 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. */
- See Also
- tx_byte_pool_performance_system_info_get
- Get byte pool system performance information
- Prototype
- Description
- Input Parameters
- allocates Pointer to destination for the number of allocate requests performed on this pool.
- releases Pointer to destination for the number of release requests performed on this pool.
- fragments_searched Pointer to destination for the total number of internal memory fragments searched during allocation requests on all byte pools.
- merges Pointer to destination for the total number of internal memory blocks merged during allocation requests on all byte pools.
- splits Pointer to destination for the total number of internal memory blocks split (fragments) created during allocation requests on all byte pools.
- suspensions Pointer to destination for the total number of thread allocation suspensions on all byte pools.
- timeouts Pointer to destination for the total number of allocate suspension timeouts on all byte pools.
- Return Values
- Allowed From
- Example
- 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. */
- See Also
- tx_byte_pool_prioritize
- Prioritize byte pool suspension list
- Prototype
- Description
- Input Parameters
- Return Values
- Allowed From
- Preemption Possible
- Example
- 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. */
- See Also
- tx_byte_release
- tx_event_flags_create
- tx_event_flags_delete
- tx_event_flags_get
- Get event flags from event flags group
- Prototype
- Description
- Input Parameters
- group_ptr Pointer to a previously created event flags group.
- requested_flags 32-bit unsigned variable that represents the requested event flags.
- get_option Specifies whether all or any of the requested event flags are required. The following are valid selections:
- 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 spe...
- actual_flags_ptr Pointer to destination of where the retrieved event flags are placed. Note that the actual flags obtained may contain flags that were not requested.
- wait_option Defines how the service behaves if the selected event flags are not set. The wait options are defined as follows:
- 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.
- Return Values
- TX_SUCCESS (0x00) Successful event flags get.
- TX_DELETED (0x01) Event flags group was deleted while thread was suspended.
- TX_NO_EVENTS (0x07) Service was unable to get the specified events within the specified time to wait.
- TX_WAIT_ABORTED (0x1A) Suspension was aborted by another thread, timer, or ISR.
- TX_GROUP_ERROR (0x06) Invalid event flags group pointer.
- TX_PTR_ERROR (0x03) Invalid pointer for actual event flags.
- TX_WAIT_ERROR (0x04) A wait option other than TX_NO_WAIT was specified on a call from a non- thread.
- TX_OPTION_ERROR (0x08) Invalid get-option was specified.
- Allowed From
- Preemption Possible
- Example
- See Also
- tx_event_flags_info_get
- Retrieve information about event flags group
- Prototype
- Description
- Input Parameters
- group_ptr Pointer to an event flags group control block.
- name Pointer to destination for the pointer to the event flags group’s name.
- current_flags Pointer to destination for the current set flags in the event flags group.
- first_suspended Pointer to destination for the pointer to the thread that is first on the suspension list of this event flags group.
- suspended_count Pointer to destination for the number of threads currently suspended on this event flags group.
- next_group Pointer to destination for the pointer of the next created event flags group.
- Return Values
- Allowed From
- Preemption Possible
- Example
- TX_EVENT_FLAGS_GROUP my_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. */
- See Also
- tx_event_flags_performance info_get
- Get event flags group performance information
- Prototype
- Description
- Input Parameters
- group_ptr Pointer to previously created event flags group.
- sets Pointer to destination for the number of event flags set requests performed on this group.
- gets Pointer to destination for the number of event flags get requests performed on this group.
- suspensions Pointer to destination for the number of thread event flags get suspensions on this group.
- timeouts Pointer to destination for the number of event flags get suspension timeouts on this group.
- Return Values
- Allowed From
- Example
- TX_EVENT_FLAGS_GROUP my_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. */
- See Also
- tx_event_flags_performance_system_info_get
- Retrieve performance system information
- Prototype
- Description
- Input Parameters
- sets Pointer to destination for the total number of event flags set requests performed on all groups.
- gets Pointer to destination for the total number of event flags get requests performed on all groups.
- suspensions Pointer to destination for the total number of thread event flags get suspensions on all groups.
- timeouts Pointer to destination for the total number of event flags get suspension timeouts on all groups.
- Return Values
- Allowed From
- Example
- 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. */
- See Also
- tx_event_flags_set
- Set event flags in an event flags group
- Prototype
- Description
- Input Parameters
- group_ptr Pointer to the previously created event flags group control block.
- flags_to_set Specifies the event flags to set or clear based upon the set option selected.
- set_option Specifies whether the event flags specified are ANDed or ORed into the current event flags of the group. The following are valid selections:
- Selecting TX_AND specifies that the specified event flags are ANDed into the current event flags in the group. This option is of...
- Return Values
- Allowed From
- Preemption Possible
- Example
- See Also
- tx_event_flags_set_notify
- Notify application when event flags are set
- Prototype
- Description
- Input Parameters
- Return Values
- Allowed From
- Example
- TX_EVENT_FLAGS_GROUP my_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! */
- See Also
- tx_interrupt_control
- tx_mutex_create
- Create mutual exclusion mutex
- Prototype
- Description
- Input Parameters
- mutex_ptr Pointer to a mutex control block.
- name_ptr Pointer to the name of the mutex.
- priority_inherit Specifies whether or not this mutex supports priority inheritance. If this value is TX_INHERIT, then priority inheritance is supported. However, if TX_NO_INHERIT is specified, priority inheritance is not supported by this mutex.
- Return Values
- Allowed From
- Preemption Possible
- Example
- See Also
- tx_mutex_delete
- tx_mutex_get
- Obtain ownership of mutex
- Prototype
- Description
- 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.
- Input Parameters
- mutex_ptr Pointer to a previously created mutex.
- wait_option Defines how the service behaves if the mutex is already owned by another thread. The wait options are defined as follows:
- 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.
- Return Values
- TX_SUCCESS (0x00) Successful mutex get operation.
- TX_DELETED (0x01) Mutex was deleted while thread was suspended.
- TX_NOT_AVAILABLE (0x1D) Service was unable to get ownership of the mutex within the specified time to wait.
- TX_WAIT_ABORTED (0x1A) Suspension was aborted by another thread, timer, or ISR.
- TX_MUTEX_ERROR (0x1C) Invalid mutex pointer.
- TX_WAIT_ERROR (0x04) A wait option other than TX_NO_WAIT was specified on a call from a non- thread.
- TX_CALLER_ERROR (0x13) Invalid caller of this service.
- Allowed From
- Preemption Possible
- Example
- See Also
- tx_mutex_info_get
- Retrieve information about mutex
- Prototype
- Description
- Input Parameters
- mutex_ptr Pointer to mutex control block.
- name Pointer to destination for the pointer to the mutex’s name.
- count Pointer to destination for the ownership count of the mutex.
- owner Pointer to destination for the owning thread’s pointer.
- first_suspended Pointer to destination for the pointer to the thread that is first on the suspension list of this mutex.
- suspended_count Pointer to destination for the number of threads currently suspended on this mutex.
- next_mutex Pointer to destination for the pointer of the next created mutex.
- Return Values
- Allowed From
- Preemption Possible
- Example
- 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. */
- See Also
- tx_mutex_performance_info_get
- Get mutex performance information
- Prototype
- Description
- Input Parameters
- mutex_ptr Pointer to previously created mutex.
- puts Pointer to destination for the number of put requests performed on this mutex.
- gets Pointer to destination for the number of get requests performed on this mutex.
- suspensions Pointer to destination for the number of thread mutex get suspensions on this mutex.
- timeouts Pointer to destination for the number of mutex get suspension timeouts on this mutex.
- inversions Pointer to destination for the number of thread priority inversions on this mutex.
- inheritances Pointer to destination for the number of thread priority inheritance operations on this mutex.
- Return Values
- Allowed From
- Example
- 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. */
- See Also
- tx_mutex_performance_system_info_get
- Get mutex system performance information
- Prototype
- Description
- Input Parameters
- puts Pointer to destination for the total number of put requests performed on all mutexes.
- gets Pointer to destination for the total number of get requests performed on all mutexes.
- suspensions Pointer to destination for the total number of thread mutex get suspensions on all mutexes.
- timeouts Pointer to destination for the total number of mutex get suspension timeouts on all mutexes.
- inversions Pointer to destination for the total number of thread priority inversions on all mutexes.
- inheritances Pointer to destination for the total number of thread priority inheritance operations on all mutexes.
- Return Values
- Allowed From
- Example
- 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. */
- See Also
- tx_mutex_prioritize
- Prioritize mutex suspension list
- Prototype
- Description
- Input Parameters
- Return Values
- Allowed From
- Preemption Possible
- Example
- 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. */
- See Also
- tx_mutex_put
- tx_queue_create
- Create message queue
- Prototype
- Description
- Input Parameters
- queue_ptr Pointer to a message queue control block.
- name_ptr Pointer to the name of the message queue.
- message_size Specifies the size of each message in the queue. Message sizes range from 1 32-bit word to 16 32-bit words. Valid message size options are numerical values from 1 through 16, inclusive.
- queue_start Starting address of the message queue.
- queue_size Total number of bytes available for the message queue.
- Return Values
- TX_SUCCESS (0x00) Successful message queue creation.
- TX_QUEUE_ERROR (0x09) Invalid message queue pointer. Either the pointer is NULL or the queue is already created.
- TX_PTR_ERROR (0x03) Invalid starting address of the message queue.
- TX_SIZE_ERROR (0x05) Size of message queue is invalid.
- TX_CALLER_ERROR (0x13) Invalid caller of this service.
- Allowed From
- Preemption Possible
- Example
- 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). */
- See Also
- tx_queue_delete
- tx_queue_flush
- tx_queue_front_send
- Send message to the front of queue
- Prototype
- Description
- Input Parameters
- queue_ptr Pointer to a message queue control block.
- source_ptr Pointer to the message.
- wait_option Defines how the service behaves if the message queue is full. The wait options are defined as follows:
- 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.
- Return Values
- TX_SUCCESS (0x00) Successful sending of message.
- TX_DELETED (0x01) Message queue was deleted while thread was suspended.
- TX_QUEUE_FULL (0x0B) Service was unable to send message because the queue was full for the duration of the specified time to wait.
- TX_WAIT_ABORTED (0x1A) Suspension was aborted by another thread, timer, or ISR.
- TX_QUEUE_ERROR (0x09) Invalid message queue pointer.
- TX_PTR_ERROR (0x03) Invalid source pointer for message.
- TX_WAIT_ERROR (0x04) A wait option other than TX_NO_WAIT was specified on a call from a non- thread.
- Allowed From
- Preemption Possible
- Example
- 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. */
- See Also
- tx_queue_info_get
- Retrieve information about queue
- Prototype
- Description
- Input Parameters
- queue_ptr Pointer to a previously created message queue.
- name Pointer to destination for the pointer to the queue’s name.
- enqueued Pointer to destination for the number of messages currently in the queue.
- available_storage Pointer to destination for the number of messages the queue currently has space for.
- first_suspended Pointer to destination for the pointer to the thread that is first on the suspension list of this queue.
- suspended_count Pointer to destination for the number of threads currently suspended on this queue.
- next_queue Pointer to destination for the pointer of the next created queue.
- Return Values
- Allowed From
- Preemption Possible
- Example
- 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. */
- See Also
- tx_queue_performance_info_get
- Get queue performance information
- Prototype
- Description
- Input Parameters
- queue_ptr Pointer to previously created queue.
- messages_sent Pointer to destination for the number of send requests performed on this queue.
- messages_received Pointer to destination for the number of receive requests performed on this queue.
- empty_suspensions Pointer to destination for the number of queue empty suspensions on this queue.
- full_suspensions Pointer to destination for the number of queue full suspensions on this queue.
- full_errors Pointer to destination for the number of queue full errors on this queue.
- timeouts Pointer to destination for the number of thread suspension timeouts on this queue.
- Return Values
- Allowed From
- Example
- 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. */
- See Also
- tx_queue_performance_system_info_get
- Get queue system performance information
- Prototype
- Description
- Input Parameters
- messages_sent Pointer to destination for the total number of send requests performed on all queues.
- messages_received Pointer to destination for the total number of receive requests performed on all queues.
- empty_suspensions Pointer to destination for the total number of queue empty suspensions on all queues.
- full_suspensions Pointer to destination for the total number of queue full suspensions on all queues.
- full_errors Pointer to destination for the total number of queue full errors on all queues.
- timeouts Pointer to destination for the total number of thread suspension timeouts on all queues.
- Return Values
- Allowed From
- Example
- 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. */
- See Also
- tx_queue_prioritize
- Prioritize queue suspension list
- Prototype
- Description
- Input Parameters
- Return Values
- Allowed From
- Preemption Possible
- Example
- 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. */
- See Also
- tx_queue_receive
- Get message from message queue
- Prototype
- Description
- Input Parameters
- queue_ptr Pointer to a previously created message queue.
- destination_ptr Location of where to copy the message.
- wait_option Defines how the service behaves if the message queue is empty. The wait options are defined as follows:
- 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.
- Return Values
- TX_SUCCESS (0x00) Successful retrieval of message.
- TX_DELETED (0x01) Message queue was deleted while thread was suspended.
- TX_QUEUE_EMPTY (0x0A) Service was unable to retrieve a message because the queue was empty for the duration of the specified time to wait.
- TX_WAIT_ABORTED (0x1A) Suspension was aborted by another thread, timer, or ISR.
- TX_QUEUE_ERROR (0x09) Invalid message queue pointer.
- TX_PTR_ERROR (0x03) Invalid destination pointer for message.
- TX_WAIT_ERROR (0x04) A wait option other than TX_NO_WAIT was specified on a call from a non- thread.
- Allowed From
- Preemption Possible
- Example
- 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." */
- See Also
- tx_queue_send
- Send message to message queue
- Prototype
- Description
- Input Parameters
- queue_ptr Pointer to a previously created message queue.
- source_ptr Pointer to the message.
- wait_option Defines how the service behaves if the message queue is full. The wait options are defined as follows:
- 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.
- Return Values
- TX_SUCCESS (0x00) Successful sending of message.
- TX_DELETED (0x01) Message queue was deleted while thread was suspended.
- TX_QUEUE_FULL (0x0B) Service was unable to send message because the queue was full for the duration of the specified time to wait.
- TX_WAIT_ABORTED (0x1A) Suspension was aborted by another thread, timer, or ISR.
- TX_QUEUE_ERROR (0x09) Invalid message queue pointer.
- TX_PTR_ERROR (0x03) Invalid source pointer for message.
- TX_WAIT_ERROR (0x04) A wait option other than TX_NO_WAIT was specified on a call from a non- thread.
- Allowed From
- Preemption Possible
- Example
- 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. */
- See Also
- tx_queue_send_notify
- Notify application when message is sent to queue
- Prototype
- Description
- Input Parameters
- Return Values
- Allowed From
- Example
- 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! */
- }
- See Also
- tx_semaphore_ceiling_put
- tx_semaphore_create
- tx_semaphore_delete
- tx_semaphore_get
- Get instance from counting semaphore
- Prototype
- Description
- Input Parameters
- semaphore_ptr Pointer to a previously created counting semaphore.
- wait_option Defines how the service behaves if there are no instances of the semaphore available; i.e., the semaphore count is zero. The wait options are defined as follows:
- 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.
- Return Values
- TX_SUCCESS (0x00) Successful retrieval of a semaphore instance.
- TX_DELETED (0x01) Counting semaphore was deleted while thread was suspended.
- TX_NO_INSTANCE (0x0D) Service was unable to retrieve an instance of the counting semaphore (semaphore count is zero within the specified time to wait).
- TX_WAIT_ABORTED (0x1A) Suspension was aborted by another thread, timer, or ISR.
- TX_SEMAPHORE_ERROR (0x0C) Invalid counting semaphore pointer.
- TX_WAIT_ERROR (0x04) A wait option other than TX_NO_WAIT was specified on a call from a non-thread.
- Allowed From
- Preemption Possible
- Example
- See Also
- tx_semaphore_info_get
- Retrieve information about semaphore
- Prototype
- Description
- Input Parameters
- semaphore_ptr Pointer to semaphore control block.
- name Pointer to destination for the pointer to the semaphore’s name.
- current_value Pointer to destination for the current semaphore’s count.
- first_suspended Pointer to destination for the pointer to the thread that is first on the suspension list of this semaphore.
- suspended_count Pointer to destination for the number of threads currently suspended on this semaphore.
- next_semaphore Pointer to destination for the pointer of the next created semaphore.
- Return Values
- Allowed From
- Preemption Possible
- Example
- 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. */
- See Also
- tx_semaphore_performance_info_get
- Get semaphore performance information
- Prototype
- Description
- Input Parameters
- semaphore_ptr Pointer to previously created semaphore.
- puts Pointer to destination for the number of put requests performed on this semaphore.
- gets Pointer to destination for the number of get requests performed on this semaphore.
- suspensions Pointer to destination for the number of thread suspensions on this semaphore.
- timeouts Pointer to destination for the number of thread suspension timeouts on this semaphore.
- Return Values
- Allowed From
- Example
- 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. */
- See Also
- tx_semaphore_performance_system_info_get
- Get semaphore system performance information
- Prototype
- Description
- Input Parameters
- puts Pointer to destination for the total number of put requests performed on all semaphores.
- gets Pointer to destination for the total number of get requests performed on all semaphores.
- suspensions Pointer to destination for the total number of thread suspensions on all semaphores.
- timeouts Pointer to destination for the total number of thread suspension timeouts on all semaphores.
- Return Values
- Allowed From
- Example
- 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. */
- See Also
- tx_semaphore_prioritize
- Prioritize semaphore suspension list
- Prototype
- Description
- Input Parameters
- Return Values
- Allowed From
- Preemption Possible
- Example
- 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. */
- See Also
- tx_semaphore_put
- tx_semaphore_put_notify
- Notify application when semaphore is put
- Prototype
- Description
- Input Parameters
- Return Values
- Allowed From
- Example
- 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! */
- }
- See Also
- tx_thread_create
- Create application thread
- Prototype
- Description
- Input Parameters
- thread_ptr Pointer to a thread control block.
- name_ptr Pointer to the name of the thread.
- entry_function Specifies the initial C function for thread execution. When a thread returns from this entry function, it is placed in a completed state and suspended indefinitely.
- entry_input A 32-bit value that is passed to the thread’s entry function when it first executes. The use for this input is determined exclusively by the application.
- stack_start Starting address of the stack’s memory area.
- stack_size Number bytes in the stack memory area. The thread’s stack area must be large enough to handle its worst-case function call nesting and local variable usage.
- priority Numerical priority of thread. Legal values range from 0 through (TX_MAX_PRIORITES-1), where a value of 0 represents the highest priority.
- preempt_threshold Highest priority level (0 through (TX_MAX_PRIORITIES-1)) of disabled preemption. Only priorities higher than t...
- time_slice Number of timer-ticks this thread is allowed to run before other ready threads of the same priority are given a chanc...
- 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.
- auto_start Specifies whether the thread starts immediately or is placed in a suspended state. Legal options are TX_AUTO_START (0...
- Return Values
- TX_SUCCESS (0x00) Successful thread creation.
- TX_THREAD_ERROR (0x0E) Invalid thread control pointer. Either the pointer is NULL or the thread is already created.
- TX_PTR_ERROR (0x03) Invalid starting address of the entry point or the stack area is invalid, usually NULL.
- TX_SIZE_ERROR (0x05) Size of stack area is invalid. Threads must have at least TX_MINIMUM_STACK bytes to execute.
- TX_PRIORITY_ERROR (0x0F) Invalid thread priority, which is a value outside the range of (0 through (TX_MAX_PRIORITIES-1)).
- TX_THRESH_ERROR (0x18) Invalid preemption- threshold specified. This value must be a valid priority less than or equal to the initial priority of the thread.
- TX_START_ERROR (0x10) Invalid auto-start selection.
- TX_CALLER_ERROR (0x13) Invalid caller of this service.
- Allowed From
- Preemption Possible
- Example
- 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, starti...
- /* 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 th...
- See Also
- tx_thread_delete
- tx_thread_entry_exit_notify
- Notify application upon thread entry and exit
- Prototype
- Description
- Input Parameters
- Return Values
- Allowed From
- Example
- 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! */
- }
- See Also
- tx_thread_identify
- tx_thread_info_get
- Retrieve information about thread
- Prototype
- Description
- Input Parameters
- thread_ptr Pointer to thread control block.
- name Pointer to destination for the pointer to the thread’s name.
- state Pointer to destination for the thread’s current execution state. Possible values are as follows:
- TX_READY (0x00) TX_COMPLETED (0x01) TX_TERMINATED (0x02) TX_SUSPENDED (0x03) TX_SLEEP (0x04) TX_QUEUE_SUSP (0x05) TX_SEMAPHORE_SUSP (0x06) TX_EVENT_FLAG (0x07) TX_BLOCK_MEMORY (0x08) TX_BYTE_MEMORY (0x09) TX_MUTEX_SUSP (0x0D)
- run_count Pointer to destination for the thread’s run count.
- priority Pointer to destination for the thread’s priority.
- preemption_threshold Pointer to destination for the thread’s preemption-threshold.
- time_slice Pointer to destination for the thread’s time-slice.
- next_thread Pointer to destination for next created thread pointer.
- suspended_thread Pointer to destination for pointer to next thread in suspension list.
- Return Values
- Allowed From
- Preemption Possible
- Example
- 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. */
- See Also
- tx_thread_performance_info_get
- Get thread performance information
- Prototype
- Description
- Input Parameters
- thread_ptr Pointer to previously created thread.
- resumptions Pointer to destination for the number of resumptions of this thread.
- suspensions Pointer to destination for the number of suspensions of this thread.
- solicited_preemptions Pointer to destination for the number of preemptions as a result of a ThreadX API service call made by this thread.
- interrupt_preemptions Pointer to destination for the number of preemptions of this thread as a result of interrupt processing.
- priority_inversions Pointer to destination for the number of priority inversions of this thread.
- time_slices Pointer to destination for the number of time- slices of this thread.
- relinquishes Pointer to destination for the number of thread relinquishes performed by this thread.
- timeouts Pointer to destination for the number of suspension timeouts on this thread.
- wait_aborts Pointer to destination for the number of wait aborts performed on this thread.
- last_preempted_by Pointer to destination for the thread pointer that last preempted this thread.
- Supplying a TX_NULL for any parameter indicates that the parameter is not required.
- Return Values
- Allowed From
- Example
- 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, &re...
- /* If status is TX_SUCCESS the performance information was successfully retrieved. */
- See Also
- tx_thread_performance_system_info_get
- Get thread system performance information
- Prototype
- Description
- Input Parameters
- resumptions Pointer to destination for the total number of thread resumptions.
- suspensions Pointer to destination for the total number of thread suspensions.
- solicited_preemptions Pointer to destination for the total number of thread preemptions as a result of a thread calling a ThreadX API service.
- interrupt_preemptions Pointer to destination for the total number of thread preemptions as a result of interrupt processing.
- priority_inversions Pointer to destination for the total number of thread priority inversions.
- time_slices Pointer to destination for the total number of thread time-slices.
- relinquishes Pointer to destination for the total number of thread relinquishes.
- timeouts Pointer to destination for the total number of thread suspension timeouts.
- wait_aborts Pointer to destination for the total number of thread wait aborts.
- non_idle_returns Pointer to destination for the number of times a thread returns to the system when another thread is ready to execute.
- idle_returns Pointer to destination for the number of times a thread returns to the system when no other thread is ready to execute (idle system).
- Supplying a TX_NULL for any parameter indicates that the parameter is not required.
- Return Values
- Allowed From
- Example
- 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(&resumpt...
- /* If status is TX_SUCCESS the performance information was successfully retrieved. */
- See Also
- tx_thread_preemption_change
- Change preemption-threshold of application thread
- Prototype
- Description
- Input Parameters
- Return Values
- TX_SUCCESS (0x00) Successful preemption-threshold change.
- TX_THREAD_ERROR (0x0E) Invalid application thread pointer.
- TX_THRESH_ERROR (0x18) Specified new preemption-threshold is not a valid thread priority (a value other than (0 through (TX_MAX_PRIORITIES-1)) or is greater than (lower priority) than the current thread priority.
- TX_PTR_ERROR (0x03) Invalid pointer to previous preemption- threshold storage location.
- TX_CALLER_ERROR (0x13) Invalid caller of this service.
- Allowed From
- Preemption Possible
- Example
- 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. */
- See Also
- tx_thread_priority_change
- Change priority of application thread
- Prototype
- Description
- Input Parameters
- Return Values
- TX_SUCCESS (0x00) Successful priority change.
- TX_THREAD_ERROR (0x0E) Invalid application thread pointer.
- TX_PRIORITY_ERROR (0x0F) Specified new priority is not valid (a value other than (0 through (TX_MAX_PRIORITIES-1)).
- TX_PTR_ERROR (0x03) Invalid pointer to previous priority storage location.
- TX_CALLER_ERROR (0x13) Invalid caller of this service.
- Allowed From
- Preemption Possible
- Example
- See Also
- tx_thread_relinquish
- tx_thread_reset
- tx_thread_resume
- tx_thread_sleep
- tx_thread_stack_error_notify
- Register thread stack error notification callback
- Prototype
- Description
- Input Parameters
- Return Values
- Allowed From
- Example
- void my_stack_error_handler(TX_THREAD *thread_ptr);
- /* Register the "my_stack_error_handler" function with ThreadX 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.*/
- See Also
- tx_thread_suspend
- tx_thread_terminate
- tx_thread_time_slice_change
- Changes time-slice of application thread
- Prototype
- Description
- Input Parameters
- Return Values
- Allowed From
- Preemption Possible
- Example
- 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 ti...
- /* 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." */
- See Also
- tx_thread_wait_abort
- tx_time_get
- tx_time_set
- tx_timer_activate
- tx_timer_change
- Change application timer
- Prototype
- Description
- Input Parameters
- timer_ptr Pointer to a timer control block.
- initial_ticks Specifies the initial number of ticks for timer expiration. Legal values range from 1 through 0xFFFFFFFF.
- 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.
- Return Values
- Allowed From
- Preemption Possible
- Example
- 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);
- See Also
- tx_timer_create
- Create application timer
- Prototype
- Description
- Input Parameters
- timer_ptr Pointer to a timer control block
- name_ptr Pointer to the name of the timer.
- expiration_function Application function to call when the timer expires.
- expiration_input Input to pass to expiration function when timer expires.
- initial_ticks Specifies the initial number of ticks for timer expiration. Legal values range from 1 through 0xFFFFFFFF.
- 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.
- auto_activate Determines if the timer is automatically activated during creation. If this value is TX_AUTO_ACTIVATE (0x01) the t...
- Return Values
- TX_SUCCESS (0x00) Successful application timer creation.
- TX_TIMER_ERROR (0x15) Invalid application timer pointer. Either the pointer is NULL or the timer is already created.
- TX_TICK_ERROR (0x16) Invalid value (a zero) supplied for initial ticks.
- TX_ACTIVATE_ERROR (0x17) Invalid activation selected.
- TX_CALLER_ERROR (0x13) Invalid caller of this service.
- Allowed From
- Preemption Possible
- Example
- 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 t...
- /* 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. */
- See Also
- tx_timer_deactivate
- tx_timer_delete
- tx_timer_info_get
- Retrieve information about an application timer
- Prototype
- Description
- Input Parameters
- timer_ptr Pointer to a previously created application timer.
- name Pointer to destination for the pointer to the timer’s name.
- active Pointer to destination for the timer active indication. If the timer is inactive or this service is called from the timer itself, a TX_FALSE value is returned. Otherwise, if the timer is active, a TX_TRUE value is returned.
- remaining_ticks Pointer to destination for the number of timer ticks left before the timer expires.
- reschedule_ticks Pointer to destination for the number of timer ticks that will be used to automatically reschedule this timer. If the value is zero, then the timer is a one-shot and won’t be rescheduled.
- next_timer Pointer to destination for the pointer of the next created application timer.
- Return Values
- Allowed From
- Preemption Possible
- Example
- 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. */
- See Also
- tx_timer_performance_info_get
- Get timer performance information
- Prototype
- Description
- Input Parameters
- timer_ptr Pointer to previously created timer.
- activates Pointer to destination for the number of activation requests performed on this timer.
- reactivates Pointer to destination for the number of automatic reactivations performed on this periodic timer.
- deactivates Pointer to destination for the number of deactivation requests performed on this timer.
- expirations Pointer to destination for the number of expirations of this timer.
- expiration_adjusts Pointer to destination for the number of internal expiration adjustments performed on this timer. These adjus...
- Supplying a TX_NULL for any parameter indicates the parameter is not required.
- Return Values
- Allowed From
- Example
- 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. */
- See Also
- tx_timer_performance_system_info_get
- Get timer system performance information
- Prototype
- Description
- Input Parameters
- activates Pointer to destination for the total number of activation requests performed on all timers.
- reactivates Pointer to destination for the total number of automatic reactivation performed on all periodic timers.
- deactivates Pointer to destination for the total number of deactivation requests performed on all timers.
- expirations Pointer to destination for the total number of expirations on all timers.
- expiration_adjusts Pointer to destination for the total number of internal expiration adjustments performed on all timers. These...
- Supplying a TX_NULL for any parameter indicates that the parameter is not required.
- Return Values
- Allowed From
- Example
- 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. */
- See Also
- tx_block_allocate
- 5 Device Drivers for ThreadX
- 6 Demonstration System for ThreadX
- A ThreadX API Services
- B ThreadX Constants
- C ThreadX Data Types
- D ASCII Character Codes
- Index