第 4 章 - Azure RTOS ThreadX 服务的说明

本章按字母顺序介绍所有 Azure RTOS ThreadX 服务。 它们的名称经过设计，以便将所有相似的服务组合在一起。 在以下说明的“返回值”部分中，以粗体显示的值不受用于禁用 API 错误检查的 TX_DISABLE_ERROR_CHECKING 定义影响，而不以粗体显示的值则是完全禁用的。 此外，“可以抢占”标题下列出的“是”表示调用该服务可能会恢复更高优先级的线程，从而抢占调用线程 。

tx_block_allocate

分配固定大小的内存块

原型

UINT tx_block_allocate(
    TX_BLOCK_POOL *pool_ptr, 
    VOID **block_ptr,
    ULONG wait_option);

说明

此服务从指定的内存池中分配固定大小的内存块。 内存块的实际大小是在创建内存池的过程中确定的。

重要

务必确保应用程序代码不在已分配的内存块之外写入。 如果发生这种情况，则会损坏其相邻的内存块（通常是后续块）。 其结果不可预测，通常很严重！

参数

• pool_ptr：
  指向之前创建的内存块池的指针。
• block_ptr：
  指向目标块指针的指针。 成功分配时，已分配内存块的地址就位于此参数所指向的位置。
• wait_option：
  定义此服务在没有可用的内存块时的行为方式。 等待选项的定义如下：
  • TX_NO_WAIT (0x00000000) - 如果选择 TX_NO_WAIT，则无论此服务是否成功，都会导致立即从此服务返回 。 如果从非线程（例如初始化、计时器或 ISR）调用服务，则这是唯一有效的选项。
  • TX_WAIT_FOREVER (0xFFFFFFF) - 选择 TX_WAIT_FOREVER 会导致发出调用的线程无限期挂起，直到内存块可用为止 。
  • 超时值（0x00000001 至 0xFFFFFFFE）- 如果选择一个数值（1 到 0xFFFFFFFE），则会指定在等待内存块时发出调用的线程保持挂起的最大计时器时钟周期数。

返回值

• TX_SUCCESS (0x00) 成功分配内存块。
• TX_DELETED (0x01) 线程挂起时删除了内存块池。
• TX_NO_MEMORY (0x10) 服务无法在指定的等待时间内分配内存块。
• TX_WAIT_ABORTED (0x1A) 挂起状态由其他线程、计时器或 ISR 中止。
• TX_POOL_ERROR：(0x02) 内存块池指针无效。
• TX_WAIT_ERROR：(0x04) 从非线程调用时指定了除 TX_NO_WAIT 以外的等待选项。
• TX_PTR_ERROR：(0x03) 指向目标指针的指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

是

示例

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. */

另请参阅

• tx_block_pool_create
• tx_block_pool_delete
• tx_block_pool_info_get
• tx_block_pool_performance_info_get
• tx_block_pool_performance_system_info_get
• tx_block_pool_prioritize
• tx_block_release

tx_block_pool_create

创建固定大小内存块的池

原型

UINT tx_block_pool_create(
    TX_BLOCK_POOL pool_ptr,
    CHAR name_ptr, 
    ULONG block_size,
    VOID pool_start, 
    ULONG pool_size);

说明

此服务创建固定大小内存块的池。 使用以下公式将指定的内存区域划分为尽可能多的固定大小内存块：

总块数 =（总字节数）/（块大小 + sizeof(void *)）

注意

*每个内存块包含一个开销指针，该指针对用户不可见，在前面的公式中用“sizeof(void)”表示。

参数

• pool_ptr* 指向内存块池控制块的指针。
• name_ptr* 指向内存块池名称的指针。
• block_size* 每个内存块中的字节数。
• pool_start* 内存块池的起始地址。 起始地址必须与 ULONG 数据类型的大小一致。
• pool_size* 内存块池可用的总字节数。

返回值

• TX_SUCCESS (0x00) 成功创建内存块池。
• TX_POOL_ERROR：(0x02) 内存块池指针无效。 指针为 NULL 或池已创建。
• TX_PTR_ERROR：(0x03) 池的起始地址无效。
• NX_CALLER_ERROR (0x13) 此服务的调用方无效。
• TX_SIZE_ERROR：(0x05) 池大小无效。

允许来自

初始化和线程

可以抢占

否

示例

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. */

另请参阅

• tx_block_allocate、tx_block_pool_delete
• tx_block_pool_info_get、tx_block_pool_performance_info_get
• tx_block_pool_performance_system_info_get
• tx_block_pool_prioritize、tx_block_release

tx_block_pool_delete

删除内存块池

原型

UINT tx_block_pool_delete(TX_BLOCK_POOL *pool_ptr);

说明

此服务删除指定的块内存池。 所有挂起并等待来自此池的内存块的线程都将恢复，并获得 TX_DELETED 返回状态。

注意

应用程序负责管理与池关联的内存区域，该内存区域在此服务完成后可用。 此外，应用程序必须阻止使用已删除的池或其以前的内存块。

参数

• pool_ptr：指向之前创建的内存块池的指针。

返回值

• TX_SUCCESS：(0X00) 成功删除内存块池。
• TX_POOL_ERROR：(0x02) 内存块池指针无效。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

线程数

可以抢占

是

示例

TX_BLOCK_POOL my_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.*/

另请参阅

• tx_block_allocate
• tx_block_pool_create
• tx_block_pool_info_get、tx_block_pool_performance_info_get
• tx_block_pool_performance_system_info_get
• tx_block_pool_prioritize、tx_block_release

tx_block_pool_info_get

检索有关块池的信息

原型

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);

说明

此服务检索所指定块内存池的相关信息。

参数

• pool_ptr* 指向之前创建的内存块池的指针。
• name* 指向块池名称指针这一目标的指针。
• available* 指向块池中可用块数这一目标的指针。
• total_blocks* 指向块池中总块数这一目标的指针。
• first_suspended* 指向此块池的挂起列表上第一个线程的指针这一目标的指针。
• suspended_count* 指向此块池中当前挂起的线程数的指针。
• next_pool* 指向下一个已创建的块池的指针这一目标的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0x00) 成功检索块池信息。
• TX_POOL_ERROR：(0x02) 内存块池指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_block_allocate
• tx_block_pool_create
• tx_block_pool_delete
• tx_block_pool_info_get、tx_block_pool_performance_info_get
• tx_block_pool_performance_system_info_get
• tx_block_pool_prioritize、tx_block_release

tx_block_pool_performance_info_get

获取块池性能信息

原型

UINT tx_block_pool_performance_info_get(
    TX_BLOCK_POOL *pool_ptr,
    ULONG *allocates, 
    ULONG *releases,
    ULONG *suspensions, 
    ULONG *timeouts));

说明

此服务检索所指定内存块池的相关性能信息。

重要

必须使用为此服务定义的TX_BLOCK_POOL_ENABLE_PERFORMANCE_INFO 生成 ThreadX 库和应用程序才能返回性能信息。

参数

• pool_ptr* 指向之前创建的内存块池的指针。
• allocates* 指向对此池执行的分配请求数这一目标的指针。
• releases* 指向对此池执行的释放请求数这一目标的指针。
• suspensions* 指向此池的线程分配挂起次数这一目标的指针。
• timeouts* 指向此池的分配挂起超时次数这一目标的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS (0x00) 成功获取块池性能信息。
• TX_PTR_ERROR (0x03) 块池指针无效。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时未启用性能信息。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_block_allocate
• tx_block_pool_create
• tx_block_pool_delete
• tx_block_pool_info_get
• tx_block_pool_performance_info_get
• tx_block_pool_performance_system_info_get
• tx_block_release

tx_block_pool_performance_system_info_get

获取块池系统性能信息

原型

UINT tx_block_pool_performance_system_info_get(
    ULONG *allocates,
    ULONG *releases, 
    ULONG *suspensions, 
    ULONG *timeouts);

说明

此服务检索应用程序中所有内存块池的相关性能信息。

重要

必须使用为此服务定义的TX_BLOCK_POOL_ENABLE_PERFORMANCE_INFO 生成 ThreadX 库和应用程序才能返回性能信息。

参数

• allocates：指向对所有块池执行的分配请求总数的指针。
• releases：指向对所有块池执行的释放请求总数的指针。
• suspensions：指向所有块池的线程分配挂起总次数的指针。
• timeouts：指向所有块池的分配挂起超时总次数的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0x00) 成功获取块池系统性能信息。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时未启用性能信息。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_block_allocate
• tx_block_pool_create
• tx_block_pool_delete
• tx_block_pool_info_get
• tx_block_pool_performance_info_get
• tx_block_pool_prioritize
• tx_block_release

tx_block_pool_prioritize

设置块池挂起列表的优先级

原型

UINT tx_block_pool_prioritize(TX_BLOCK_POOL *pool_ptr);

说明

此服务将此池中某个内存块已挂起的最高优先级线程放在挂起列表前面。 所有其他线程保持它们挂起时的相同 FIFO 顺序。

参数

• pool_ptr：指向内存块池控制块的指针。

返回值

• TX_SUCCESS：(0x00) 成功为块池设置优先级。
• TX_POOL_ERROR：(0x02) 内存块池指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_block_allocate
• tx_block_pool_create
• tx_block_pool_delete
• tx_block_pool_info_get
• tx_block_pool_performance_info_get
• tx_block_pool_performance_system_info_get
• tx_block_release

tx_block_release

释放固定大小的内存块

原型

UINT tx_block_release(VOID *block_ptr);

说明

此服务将以前分配的块释放回其关联的内存池。 如果有一个或多个线程挂起并等待此池中的内存块，则为第一个挂起的线程提供此内存块并恢复该线程。

注意

应用程序可能希望在释放内存块之前将其清空以防止数据泄漏。

重要

内存块区域已释放回池中后，应用程序应阻止使用该内存块区域。

参数

• block_ptr：指向之前分配的内存块的指针。

返回值

• TX_SUCCESS：(0x00) 成功释放内存块。
• TX_PTR_ERROR：(0x03) 指向内存块的指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

是

示例

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. */

另请参阅

• tx_block_allocate
• tx_block_pool_create
• tx_block_pool_delete
• tx_block_pool_info_get
• tx_block_pool_performance_info_get
• tx_block_pool_performance_system_info_get
• tx_block_pool_prioritize

tx_byte_allocate

分配内存的字节数

原型

UINT tx_byte_allocate(
    TX_BYTE_POOL *pool_ptr,
    VOID **memory_ptr, 
    ULONG memory_size,
    ULONG wait_option);

说明

此服务从指定的内存字节池中分配指定的字节数。

重要

务必确保应用程序代码不在已分配的内存块之外写入。 如果发生这种情况，则会损坏其相邻的内存块（通常是后续块）。 其结果不可预测，通常很严重！

注意

此服务的性能是块大小和池中碎片量的函数。 因此，在执行时间关键线程期间不应使用此服务。

参数

• pool_ptr：
  指向之前创建的内存块池的指针。
• memory_ptr：
  指向目标内存指针的指针。 成功分配时，已分配内存区域的地址就位于在此参数所指向的位置。
• memory_size：
  请求的字节数。
• wait_option：
  定义此服务在没有足够内存可用时的行为方式。 等待选项的定义如下：
  • TX_NO_WAIT (0x00000000) - 如果选择 TX_NO_WAIT，则无论此服务是否成功，都会导致立即从此服务返回 。 如果从初始化调用服务，则这是唯一有效的选项。
  • TX_WAIT_FOREVER (0xFFFFFFFF) - 选择 TX_WAIT_FOREVER 会导致发出调用的线程无限期挂起，直到有足够内存可用为止 。
  • 超时值（0x00000001 至 0xFFFFFFFE）- 如果选择一个数值（1 到 0xFFFFFFFE），则会指定在等待内存时发出调用的线程保持挂起的最大计时器时钟周期数。

返回值

• TX_SUCCESS：(0x00) 成功分配内存。
• TX_DELETED：(0x01) 线程挂起时删除了内存池。
• TX_NO_MEMORY：(0X10) 服务无法在指定的等待时间内分配内存。
• TX_WAIT_ABORTED (0x1A) 挂起状态由其他线程、计时器或 ISR 中止。
• TX_POOL_ERROR：(0x02) 内存池指针无效。
• TX_PTR_ERROR：(0x03) 指向目标指针的指针无效。
• TX_SIZE_ERROR：(0X05) 所请求的大小为零或超过池大小。
• TX_WAIT_ERROR：(0x04) 从非线程调用时指定了除 TX_NO_WAIT 以外的等待选项。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

初始化和线程

可以抢占

是

示例

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. */

另请参阅

• tx_byte_pool_create
• tx_byte_pool_delete
• tx_byte_pool_info_get
• tx_byte_pool_performance_info_get
• tx_byte_pool_performance_system_info_get
• tx_byte_pool_prioritize
• tx_byte_release

tx_byte_pool_create

创建内存字节池

原型

UINT tx_byte_pool_create(
    TX_BYTE_POOL *pool_ptr,
    CHAR *name_ptr, 
    VOID *pool_start,
    ULONG pool_size);

说明

此服务在指定的区域中创建内存字节池。 基本上来说，池最初包含一个非常大的可用块。 但是，随着不断进行分配，池将分成更小的块。

参数

• pool_ptr：指向内存池控制块的指针。
• name_ptr：指向内存池名称的指针。
• pool_start：内存池的起始地址。 起始地址必须与 ULONG 数据类型的大小一致。
• pool_size：内存池可用的总字节数。

返回值

• TX_SUCCESS：(0X00) 成功创建内存池。
• TX_POOL_ERROR：(0x02) 内存池指针无效。 指针为 NULL 或池已创建。
• TX_PTR_ERROR：(0x03) 池的起始地址无效。
• TX_SIZE_ERROR：(0x05) 池大小无效。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

初始化和线程

可以抢占

否

示例

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. */

另请参阅

• tx_byte_allocate
• tx_byte_pool_delete
• tx_byte_pool_info_get
• tx_byte_pool_performance_info_get
• tx_byte_pool_performance_system_info_get
• tx_byte_pool_prioritize
• tx_byte_release

tx_byte_pool_delete

删除内存字节池

原型

UINT tx_byte_pool_delete(TX_BYTE_POOL *pool_ptr);

说明

此服务删除指定的内存字节池。 所有挂起并等待来自此池的内存的线程都将恢复，并获得 TX_DELETED 返回状态。

重要

应用程序负责管理与池关联的内存区域，该内存区域在此服务完成后可用。 此外，应用程序必须阻止使用已删除的池或先前从中分配的内存。

参数

• pool_ptr：指向之前创建的内存池的指针。

返回值

• TX_SUCCESS：(0X00) 成功删除内存池。
• TX_POOL_ERROR：(0x02) 内存池指针无效。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

线程数

可以抢占

是

示例

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. */

另请参阅

• tx_byte_allocate
• tx_byte_pool_create
• tx_byte_pool_info_get
• tx_byte_pool_performance_info_get
• tx_byte_pool_performance_system_info_get
• tx_byte_pool_prioritize
• tx_byte_release

tx_byte_pool_info_get

检索有关字节池的信息

原型

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);

说明

此服务检索所指定内存字节池的相关信息。

参数

• pool_ptr：指向之前创建的内存池的指针。
• name：指向字节池名称指针这一目标的指针。
• available：指向池中的可用字节数的指针。
• fragments：指向字节池中内存片段总数的指针。
• first_suspended：指向此字节池的挂起列表上第一个线程的指针。
• suspended_count：指向此字节池中当前挂起的线程数的指针。
• next_pool：指向下一个已创建的字节池的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0x00) 成功检索池信息。
• TX_POOL_ERROR：(0x02) 内存池指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_byte_allocate
• tx_byte_pool_create
• tx_byte_pool_delete
• tx_byte_pool_performance_info_get
• tx_byte_pool_performance_system_info_get
• tx_byte_pool_prioritize
• tx_byte_release

tx_byte_pool_performance_info_get

获取字节池性能信息

原型

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);

说明

此服务检索所指定内存字节池的相关性能信息。

重要

必须使用为此服务定义的TX_BYTE_POOL_ENABLE_PERFORMANCE_INFO 生成 ThreadX 库和应用程序才能返回性能信息。

参数

• pool_ptr：指向之前创建的内存字节池的指针。
• allocates：指向对此池执行的分配请求数的指针。
• releases：指向对此池执行的释放请求数的指针。
• fragments_searched：指向对此池执行分配请求期间搜索到的内部内存片段数的指针。
• merges：指向对此池执行分配请求期间合并的内部内存块数的指针。
• splits：指向对此池执行分配请求期间创建的内部内存块拆分（片段）数的指针。
• suspensions：指向此池的线程分配挂起数的指针。
• timeouts：指向此池的分配挂起超时次数的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0x00) 成功获取字节池性能信息。
• TX_PTR_ERROR：(0x03) 字节池指针无效。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时未启用性能信息。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_byte_allocate
• tx_byte_pool_create
• tx_byte_pool_delete
• tx_byte_pool_info_get
• tx_byte_pool_performance_system_info_get
• tx_byte_pool_prioritize
• tx_byte_release

tx_byte_pool_performance_system_info_get

获取字节池系统性能信息

原型

UINT tx_byte_pool_performance_system_info_get(
    ULONG *allocates,
    ULONG *releases, 
    ULONG *fragments_searched, 
    ULONG *merges,
    ULONG *splits, 
    ULONG *suspensions, 
    ULONG *timeouts);

说明

此服务检索系统中所有内存字节池的相关性能信息。

重要

必须使用为此服务定义的TX_BYTE_POOL_ENABLE_PERFORMANCE_INFO 生成 ThreadX 库和应用程序才能返回性能信息。

参数

• allocates：指向对此池执行的分配请求数的指针。
• releases：指向对此池执行的释放请求数的指针。
• fragments_searched：指向对所有字节池执行分配请求期间搜索到的内部内存片段总数的指针。
• merges：指向对所有字节池执行分配请求期间合并的内部内存块总数的指针。
• splits：指向对所有字节池执行分配请求期间创建的内部内存块拆分（片段）总数的指针。
• suspensions：指向所有字节池的线程分配挂起总次数的指针。
• timeouts：指向所有字节池的分配挂起超时总次数的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0x00) 成功获取字节池性能信息。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时未启用性能信息。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_byte_allocate
• tx_byte_pool_create
• tx_byte_pool_delete
• tx_byte_pool_info_get
• tx_byte_pool_performance_info_get
• tx_byte_pool_prioritize
• tx_byte_release

tx_byte_pool_prioritize

设置字节池挂起列表的优先级

原型

UINT tx_byte_pool_prioritize(TX_BYTE_POOL *pool_ptr);

说明

此服务将此池中内存已挂起的最高优先级线程放在挂起列表前面。 所有其他线程保持它们挂起时的相同 FIFO 顺序。

参数

• pool_ptr：指向内存池控制块的指针。

返回值

• TX_SUCCESS：(0x00) 成功为内存池设置优先级。
• TX_POOL_ERROR：(0x02) 内存池指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_byte_allocate
• tx_byte_pool_create
• tx_byte_pool_delete
• tx_byte_pool_info_get
• tx_byte_pool_performance_info_get
• tx_byte_pool_performance_system_info_get
• tx_byte_release

tx_byte_release

将字节释放回内存池

原型

UINT tx_byte_release(VOID *memory_ptr);

说明

此服务将以前分配的内存区域释放回其关联的池。 如果有一个或多个挂起的线程正在等待此池中的内存，则会为每个挂起的线程分配内存，并继续执行直到内存耗尽或不再有任何挂起的线程为止。 向挂起的线程分配内存这一过程始终从挂起的第一个线程开始。

注意

应用程序可能希望在释放内存区域之前将其清空以防止数据泄漏。

重要

应用程序必须阻止在释放某个内存区域后使用该区域。

参数

• memory_ptr：指向之前分配的内存区域的指针。

返回值

• TX_SUCCESS：(0x00) 成功释放内存。
• TX_PTR_ERROR：(0x03) 内存区域指针无效。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

初始化和线程

可以抢占

是

示例

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. */

另请参阅

• tx_byte_allocate
• tx_byte_pool_create
• tx_byte_pool_delete
• tx_byte_pool_info_get
• tx_byte_pool_performance_info_get
• tx_byte_pool_performance_system_info_get
• tx_byte_pool_prioritize

tx_event_flags_create

创建事件标志组

原型

UINT tx_event_flags_create(
    TX_EVENT_FLAGS_GROUP *group_ptr,
    CHAR *name_ptr);

说明

此服务创建包含 32 个事件标志的事件标志组。 组中的 32 个事件标志全部初始化为零。 每个事件标志由一个位表示。

参数

• group_ptr：指向事件标志组控制块的指针。
• name_ptr：指向事件标志组名称的指针。

返回值

• TX_SUCCESS：(0X00) 成功创建事件组。
• TX_GROUP_ERROR：(0x06) 事件组指针无效。 指针为 NULL 或事件组已创建。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

初始化和线程

可以抢占

否

示例

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. */

另请参阅

• tx_event_flags_delete
• tx_event_flags_get
• tx_event_flags_info_get
• tx_event_flags_performance_info_get
• tx_event_flags_performance_system_info_get
• tx_event_flags_set
• tx_event_flags_set_notify

tx_event_flags_delete

删除事件标志组

原型

UINT tx_event_flags_delete(TX_EVENT_FLAGS_GROUP *group_ptr);

说明

此服务删除指定的事件标志组。 所有挂起并等待此组中的事件的线程都将恢复，并获得 TX_DELETED 返回状态。

重要

在删除事件标志组之前，应用程序必须确保完成（或禁用）此事件标志组的设置通知回调。 此外，应用程序必须阻止将来再使用已删除的事件标志组。

参数

• group_ptr：指向以前创建的事件标志组的指针。

返回值

• TX_SUCCESS：(0X00) 成功删除事件标志组。
• TX_GROUP_ERROR：(0x06) 事件标志组指针无效。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

线程数

可以抢占

是

示例

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. */

另请参阅

• tx_event_flags_create
• tx_event_flags_get
• tx_event_flags_info_get
• tx_event_flags_performance_info_get
• tx_event_flags_performance_system_info_get
• tx_event_flags_set
• tx_event_flags_set_notify

tx_event_flags_get

从事件标志组获取事件标志

原型

UINT tx_event_flags_get(
    TX_EVENT_FLAGS_GROUP *group_ptr,
    ULONG requested_flags, 
    UINT get_option,
    ULONG *actual_flags_ptr, 
    ULONG wait_option);

说明

此服务从指定事件标志组检索事件标志。 每个事件标志组都包含 32 个事件标志。 每个标志由一个位表示。 此服务可以检索由输入参数选择的各种事件标志组合。

参数

• group_ptr：
  指向以前创建的事件标志组的指针。

• requested_flags：
  32 位无符号变量，表示请求的事件标志。

• get_option：
  指定是否需要所有或任何请求的事件标志。 以下是有效的选择：

  • TX_AND (0x02)

  • TX_AND_CLEAR (0x03)

  • TX_OR (0x00)

  • TX_OR_CLEAR (0x01)

    如果选择 TX_AND 或 TX_AND_CLEAR，则会指定所有事件标志在组中都必须存在。 如果选择 TX_OR 或 TX_OR_CLEAR，则会指定任何事件标志都符合要求。 如果指定 TX_AND_CLEAR 或 TX_OR_CLEAR，则会清除满足请求的事件标志（设置为零）。

• actual_flags_ptr：
  指向放置检索到的事件标志的位置这一目标的指针。 注意，实际获得的标志可能包含没有请求的标志。

• wait_option：
  定义未设置所选事件标志时服务的行为方式。 等待选项的定义如下：

  • TX_NO_WAIT (0x00000000) - 如果选择 TX_NO_WAIT，则无论此服务是否成功，都会导致立即从此服务返回。 如果从非线程（例如初始化、计时器或 ISR）调用服务，则这是唯一有效的选项。
  • TX_WAIT_FOREVER 超时值 (0xFFFFFFFF) - 选择 TX_WAIT_FOREVER 会导致发出调用的线程无限期挂起，直到事件标志可用为止。
  • 超时值（0x00000001 至 0xFFFFFFFE）- 如果选择一个数值（1 到 0xFFFFFFFE），则会指定在等待事件标志时发出调用的线程保持挂起的最大计时器时钟周期数。

返回值

• TX_SUCCESS：(0X00) 成功获取事件标志。
• TX_DELETED：(0x01) 线程挂起时删除了事件标志组。
• TX_NO_EVENTS：(0X07) 服务无法在指定的等待时间内获取指定的事件。
• TX_WAIT_ABORTED：(0x1A) 挂起状态由其他线程、计时器或 ISR 中止。
• TX_GROUP_ERROR：(0x06) 事件标志组指针无效。
• TX_PTR_ERROR：(0x03) 指向实际事件标志的指针无效。
• TX_WAIT_ERROR：(0x04) 从非线程调用时指定了除 TX_NO_WAIT 以外的等待选项。
• TX_OPTION_ERROR：(0x08) 指定的 get-option 无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

是

示例

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. */

另请参阅

• tx_event_flags_create
• tx_event_flags_delete
• tx_event_flags_info_get
• tx_event_flags_performance_info_get
• tx_event_flags_performance_system_info_get
• tx_event_flags_set
• tx_event_flags_set_notify

tx_event_flags_info_get

检索有关事件标志组的信息

原型

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);

说明

此服务检索所指定事件标志组的相关信息。

参数

• group_ptr：指向事件标志组控制块的指针。
• name：指向事件标志组名称指针这一目标的指针。
• current_flags：指向事件标志组中当前设置的标志的指针。
• first_suspended：指向此事件标志组的挂起列表上第一个线程的指针。
• suspended_count：指向此事件标志组中当前挂起的线程数的指针。
• next_group：指向下一个已创建的事件标志组的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0X00) 成功检索事件组信息。
• TX_GROUP_ERROR：(0x06) 事件组指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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,
    &current_flags,
    &first_suspended, &suspended_count,
    &next_group);
/* If status equals TX_SUCCESS, the information requested is
valid. */

另请参阅

• tx_event_flags_create
• tx_event_flags_delete
• tx_event_flags_get
• tx_event_flags_performance_info_get
• tx_event_flags_performance_system_info_get
• tx_event_flags_set
• tx_event_flags_set_notify

tx_event_flags_performance_info_get

获取事件标志组性能信息

原型

UINT tx_event_flags_performance_info_get(
    TX_EVENT_FLAGS_GROUP *group_ptr,
    ULONG *sets, ULONG *gets,
    ULONG *suspensions, 
    ULONG *timeouts);

说明

此服务检索所指定事件标志组的相关性能信息。

重要

必须使用为此服务定义的 * TX_EVENT_FLAGS_ENABLE_PERFORMANCE_INFO: 生成 ThreadX 库和应用程序才能返回性能信息。

参数

• group_ptr：指向以前创建的事件标志组的指针。
• sets：指向对此组执行的事件标志设置请求数的指针。
• gets：指向对此组执行的事件标志获取请求数的指针。
• suspensions：指向此组的线程事件标志获取挂起数的指针。
• timeouts：指向此组的事件标志获取挂起超时次数的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0X00) 成功获取事件标志组性能信息。
• TX_PTR_ERROR：(0x03) 事件标志组指针无效。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时未启用性能信息。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_event_flags_create
• tx_event_flags_delete
• tx_event_flags_get
• tx_event_flags_info_get
• tx_event_flags_performance_system_info_get
• tx_event_flags_set
• tx_event_flags_set_notify

tx_event_flags_performance_system_info_get

检索系统性能信息

原型

UINT tx_event_flags_performance_system_info_get(
    ULONG *sets,
    ULONG *gets,
    ULONG *suspensions, 
    ULONG *timeouts);

说明

此服务检索系统中所有事件标志组的相关性能信息。

重要

必须使用为此服务定义的 TX_EVENT_FLAGS_ENABLE_PERFORMANCE_INFO 生成 ThreadX 库和应用程序才能返回性能信息。

参数

• sets：指向对所有组执行的事件标志设置请求总数的指针。
• gets：指向对所有组执行的事件标志获取请求总数的指针。
• suspensions：指向所有组的线程事件标志获取挂起总数的指针。
• timeouts：指向所有组的事件标志获取挂起超时总次数的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0X00) 成功获取事件标志系统性能信息。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时未启用性能信息。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_event_flags_create
• tx_event_flags_delete
• tx_event_flags_get
• tx_event_flags_info_get
• tx_event_flags_performance_info_get
• tx_event_flags_set
• tx_event_flags_set_notify

tx_event_flags_set

在事件标志组中设置事件标志

原型

UINT tx_event_flags_set(
    TX_EVENT_FLAGS_GROUP *group_ptr,
    ULONG flags_to_set,
    UINT set_option);

说明

此服务根据指定的 set_option 设置或清除事件标志组中的事件标志。 所有现已满足其事件标志请求的挂起线程都将恢复。

参数

• group_ptr：
  指向以前创建的事件标志组控制块的指针。

• flags_to_set：
  根据所选的 set-option，指定要设置或清除的事件标志。

• set_option：
  指定将所指定的事件标志与该组的当前事件标志进行“AND”或“OR”运算。 以下是有效的选择：

  • TX_AND (0x02)
  • TX_OR (0x00)

  如果选择 TX_AND，则会指定将所指定的事件标志与该组的当前事件标志进行“AND”运算。 此选项通常用于清除组中的事件标志。 否则，如果指定了 TX_OR，则对所指定的事件标志与该组的当前事件标志进行“OR”运算。

返回值

• TX_SUCCESS：(0X00) 成功设置事件标志。
• TX_GROUP_ERROR：(0x06) 指向事件标志组的指针无效。
• TX_OPTION_ERROR：(0x08) 指定的 set-option 无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

是

示例

TX_EVENT_FLAGS_GROUP my_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. */

另请参阅

• tx_event_flags_create
• tx_event_flags_delete
• tx_event_flags_get
• tx_event_flags_info_get
• tx_event_flags_performance_info_get
• tx_event_flags_performance_system_info_get
• tx_event_flags_set_notify

tx_event_flags_set_notify

设置事件标志时通知应用程序

原型

UINT tx_event_flags_set_notify(
    TX_EVENT_FLAGS_GROUP *group_ptr,
    VOID (*events_set_notify)(TX_EVENT_FLAGS_GROUP *));

说明

此服务注册一个通知回调函数，只要在指定的事件标志组中设置了一个或多个事件标志，就会调用该函数。 通知回调的处理由应用程序定义。

参数

• group_ptr：指向以前创建的事件标志组的指针。
• events_set_notify：指向应用程序的事件标志设置通知函数的指针。 如果此值为 TX_NULL，则禁用通知。

返回值

• TX_SUCCESS：(0X00) 成功注册事件标志设置通知。
• TX_GROUP_ERROR：(0x06) 事件标志组指针无效。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时禁用了通知功能。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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! */

另请参阅

• tx_event_flags_create
• tx_event_flags_delete
• tx_event_flags_get
• tx_event_flags_info_get
• tx_event_flags_performance_info_get
• tx_event_flags_performance_system_info_get
• tx_event_flags_set

tx_interrupt_control

启用和禁用中断

原型

UINT tx_interrupt_control(UINT new_posture);

说明

此服务启用或禁用由输入参数 new_posture 指定的中断。

注意

如果从应用程序线程调用此服务，中断状态将保留在该线程的上下文中。 例如，如果线程调用此例程来禁用中断，然后挂起，则当该线程恢复后，将重新禁用中断。

警告

在初始化期间，不应使用此服务来启用中断！ 这样做可能会导致不可预知的结果。

参数

• new_posture：此参数指定是禁用还是启用中断。 合法值包括 TX_INT_DISABLE 和 TX_INT_ENABLE 。 这些参数的实际值特定于端口。 此外，某些处理体系结构可能还支持其他中断禁用状态。

返回值

• previous posture：此服务将以前的中断状态返回给调用方。 这使该服务的用户可以在禁用中断后恢复先前的状态。

允许来自

线程、计时器和 ISR

可以抢占

否

示例

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);

另请参阅

无

tx_mutex_create

创建互斥锁

原型

UINT tx_mutex_create(
    TX_MUTEX *mutex_ptr,
    CHAR *name_ptr, 
    UINT priority_inherit);

说明

此服务为线程间互斥创建一个互斥锁，用于资源保护。

参数

• mutex_ptr：指向互斥锁控制块的指针。
• name_ptr：指向互斥锁名称的指针。
• priority_inherit：指定此互斥锁是否支持优先级继承。 如果此值为 TX_INHERIT，则支持优先级继承。 但是，如果指定了 TX_NO_INHERIT，则此互斥锁不支持优先级继承。

返回值

• TX_SUCCESS：(0X00) 成功创建互斥锁。
• TX_MUTEX_ERROR：(0X1C) 互斥锁指针无效。 指针为 NULL 或已创建互斥锁。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。
• TX_INHERIT_ERROR：(0x1F) 优先级继承参数无效。

允许来自

初始化和线程

可以抢占

否

示例

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. */

另请参阅

• tx_mutex_delete
• tx_mutex_get
• tx_mutex_info_get
• tx_mutex_performance_info_get
• tx_mutex_performance_system_info_get
• tx_mutex_prioritize
• tx_mutex_put

tx_mutex_delete

删除互斥锁

原型

UINT tx_mutex_delete(TX_MUTEX *mutex_ptr);

说明

此服务删除指定的互斥锁。 所有挂起并等待互斥锁的线程都将恢复，并获得 TX_DELETED 返回状态。

注意

应用程序负责阻止使用已删除的互斥锁。

参数

• mutex_ptr：指向之前创建的互斥锁的指针。

返回值

• TX_SUCCESS：(0X00) 成功删除互斥锁。
• TX_MUTEX_ERROR：(0X1C) 互斥锁指针无效。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

线程数

可以抢占

是

示例

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. */

另请参阅

• tx_mutex_create
• tx_mutex_get
• tx_mutex_info_get
• tx_mutex_performance_info_get
• tx_mutex_performance_system_info_get
• tx_mutex_prioritize
• tx_mutex_put

tx_mutex_get

获取互斥锁的所有权

原型

UINT tx_mutex_get(
    TX_MUTEX *mutex_ptr, 
    ULONG wait_option);

说明

此服务尝试获取指定互斥锁的独占所有权。 如果调用线程已拥有互斥锁，则内部计数器会递增，并返回成功状态。

如果互斥锁由另一个线程拥有，并且该线程具有更高的优先级，并且在创建互斥锁时指定了优先级继承，则较低优先级线程的优先级将临时提升到调用线程的优先级。

注意

对于拥有互斥锁并指定了优先级继承的较低优先级线程，在拥有互斥锁期间，其优先级绝不能由外部线程修改。

参数

• mutex_ptr：
  指向之前创建的互斥锁的指针。
• wait_option：
  定义该互斥锁已由另一个线程拥有时此服务的行为方式。 等待选项的定义如下：
  • * TX_NO_WAIT：(0x00000000) - 如果选择 TX_NO_WAIT，则无论此服务是否成功，都会导致立即从此服务返回。 如果从初始化调用服务，则这是唯一有效的选项。
  • TX_WAIT_FOREVER 超时值 (0xFFFFFFFF) - 选择 TX_WAIT_FOREVER 会导致发出调用的线程无限期挂起，直到互斥锁可用为止 。
  • 超时值（0x00000001 至 0xFFFFFFFE）- 如果选择一个数值（1 到 0xFFFFFFFE），则会指定在等待互斥锁时发出调用的线程保持挂起的最大计时器时钟周期数。

返回值

• TX_SUCCESS：(0X00) 成功执行互斥锁获取操作。
• TX_DELETED：(0x01) 线程挂起时删除了互斥锁。
• TX_NOT_AVAILABLE：(0X1D) 服务无法在指定的等待时间内获得互斥锁的所有权。
• TX_WAIT_ABORTED：(0x1A) 挂起状态由其他线程、计时器或 ISR 中止。
• TX_MUTEX_ERROR：(0X1C) 互斥锁指针无效。
• TX_WAIT_ERROR：(0x04) 从非线程调用时指定了除 TX_NO_WAIT 以外的等待选项。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

初始化、线程和计时器

可以抢占

是

示例

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);

另请参阅

• tx_mutex_create
• tx_mutex_delete
• tx_mutex_info_get
• tx_mutex_performance_info_get
• tx_mutex_performance_system_info_get
• tx_mutex_prioritize
• tx_mutex_put

tx_mutex_info_get

检索有关互斥锁的信息

原型

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);

说明

此服务从指定的互斥锁检索信息。

参数

• mutex_ptr：指向互斥锁控制块的指针。
• name：指向互斥锁名称指针这一目标的指针。
• count：指向互斥锁所有权计数的指针。
• owner：指向拥有线程的指针这一目标的指针。
• first_suspended：指向此互斥锁的挂起列表上第一个线程的指针。
• suspended_count：指向此互斥锁中当前挂起的线程数的指针。
• next_mutex：指向下一个已创建的互斥锁的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0X00) 成功检索互斥锁信息。
• TX_MUTEX_ERROR：(0X1C) 互斥锁指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_mutex_create
• tx_mutex_delete
• tx_mutex_get
• tx_mutex_performance_info_get
• tx_mutex_performance_system_info_get
• tx_mutex_prioritize
• tx_mutex_put

tx_mutex_performance_info_get

获取互斥锁性能信息

原型

UINT tx_mutex_performance_info_get(
    TX_MUTEX *mutex_ptr, 
    ULONG *puts,
    ULONG *gets, 
    ULONG *suspensions, 
    ULONG *timeouts,
    ULONG *inversions, 
    ULONG *inheritances);

说明

此服务检索所指定互斥锁的相关性能信息。

重要

必须使用为此服务定义的TX_MUTEX_ENABLE_PERFORMANCE_INFO 生成 ThreadX 库和应用程序才能返回性能信息。

参数

• mutex_ptr：指向之前创建的互斥锁的指针。
• puts：指向对此互斥锁执行的放置请求数的指针。
• gets：指向对此互斥锁执行的获取请求数的指针。
• suspensions：指向此互斥锁的线程互斥锁获取挂起数的指针。
• timeouts：指向此互斥锁的互斥锁获取挂起超时次数的指针。
• inversions：指向此互斥锁的线程优先级倒置数的指针。
• inheritances：指向此互斥锁的线程优先级继承操作数的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0X00) 成功获取互斥锁性能信息。
• TX_PTR_ERROR：(0x03) 互斥锁指针无效。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时未启用性能信息。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_mutex_create
• tx_mutex_delete
• tx_mutex_get
• tx_mutex_info_get
• tx_mutex_performance_system_info_get
• tx_mutex_prioritize
• tx_mutex_put

tx_mutex_performance_system_info_get

获取互斥锁系统性能信息

原型

UINT tx_mutex_performance_system_info_get(
    ULONG *puts, 
    ULONG *gets,
    ULONG *suspensions, 
    ULONG *timeouts,
    ULONG *inversions, 
    ULONG *inheritances);

说明

此服务检索系统中所有互斥锁的相关性能信息。

重要

必须使用为此服务定义的 TX_MUTEX_ENABLE_PERFORMANCE_INFO 生成 ThreadX 库和应用程序才能返回性能信息。

参数

• puts：指向对所有互斥锁执行的放置请求总数的指针。
• gets：指向对所有互斥锁执行的获取请求总数的指针。
• suspensions：指向所有互斥锁的线程互斥锁获取挂起总数的指针。
• timeouts：指向所有互斥锁的互斥锁获取挂起超时总次数的指针。
• inversions：指向所有互斥锁的线程优先级倒置总数的指针。
• inheritances：指向所有互斥锁的线程优先级继承操作总数的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0X00) 成功获取互斥锁系统性能信息。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时未启用性能信息。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_mutex_create
• tx_mutex_delete
• tx_mutex_get
• tx_mutex_info_get
• tx_mutex_performance_info_get
• tx_mutex_prioritize
• tx_mutex_put

tx_mutex_prioritize

设置互斥锁挂起列表的优先级

原型

UINT tx_mutex_prioritize(TX_MUTEX *mutex_ptr);

说明

此服务将为拥有互斥锁而挂起的最高优先级线程放在挂起列表前面。 所有其他线程保持它们挂起时的相同 FIFO 顺序。

参数

• mutex_ptr：指向之前创建的互斥锁的指针。

返回值

• TX_SUCCESS：(0X00) 成功设置互斥锁优先级。
• TX_MUTEX_ERROR：(0X1C) 互斥锁指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_mutex_create
• tx_mutex_delete
• tx_mutex_get
• tx_mutex_info_get
• tx_mutex_performance_info_get
• tx_mutex_performance_system_info_get
• tx_mutex_put

tx_mutex_put

释放互斥锁的所有权

原型

UINT tx_mutex_put(TX_MUTEX *mutex_ptr);

说明

此服务递减指定互斥锁的所有权计数。 如果所有权计数为零，则互斥锁可用。

注意

如果在创建互斥锁期间选择了优先级继承，则释放线程的优先级将恢复为最初获得互斥锁所有权时的优先级。 在拥有互斥锁期间对释放线程所做的任何其他优先级更改都可以撤消。

参数

• mutex_ptr：指向之前创建的互斥锁的指针。

返回值

• TX_SUCCESS：(0X00) 成功释放互斥锁。
• TX_NOT_OWNED：(0X1E) 互斥锁不归调用方所有。
• TX_MUTEX_ERROR：(0X1C) 互斥锁指针无效。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

初始化、线程和计时器

可以抢占

是

示例

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. */

另请参阅

• tx_mutex_create
• tx_mutex_delete
• tx_mutex_get
• tx_mutex_info_get
• tx_mutex_performance_info_get
• tx_mutex_performance_system_info_get
• tx_mutex_prioritize

tx_queue_create

创建消息队列

原型

UINT tx_queue_create(
    TX_QUEUE *queue_ptr, 
    CHAR *name_ptr,
    UINT message_size,
    VOID *queue_start, 
    ULONG queue_size);

说明

此服务创建通常用于线程间通信的消息队列。 消息总数是根据指定的消息大小和队列中的字节总数来计算的。

注意

如果队列内存区域中指定的总字节数不能被指定的消息大小整除，则不会使用内存区域中剩余的字节。

参数

• queue_ptr：指向消息队列控制块的指针。
• name_ptr：指向消息队列名称的指针。
• message_size：指定队列中每条消息的大小。 消息大小从 1 个 32 位字到 16 个 32 位字不等。 有效的消息大小选项是介于 1 到 16（含）之间的数值。
• queue_start：消息队列的起始地址。 起始地址必须与 ULONG 数据类型的大小一致。
• queue_size：可用于消息队列的总字节数。

返回值

• TX_SUCCESS：(0X00) 成功创建消息队列。
• TX_QUEUE_ERROR：(0X09) 消息队列指针无效。 指针为 NULL 或已创建队列。
• TX_PTR_ERROR：(0x03) 消息队列的起始地址无效。
• TX_SIZE_ERROR：(0x05) 消息队列大小无效。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

初始化和线程

可以抢占

否

示例

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). */

另请参阅

• tx_queue_delete
• tx_queue_flush
• tx_queue_front_send
• tx_queue_info_get
• tx_queue_performance_info_get
• tx_queue_performance_system_info_get
• tx_queue_prioritize
• tx_queue_receive
• tx_queue_send
• tx_queue_send_notify

tx_queue_delete

删除消息队列

原型

UINT tx_queue_delete(TX_QUEUE *queue_ptr);

说明

此服务删除指定的消息队列。 所有挂起并等待来自此队列的消息的线程都将恢复，并获得 TX_DELETED 返回状态。

重要

在删除队列之前，应用程序必须确保完成（或禁用）此队列的任何发送通知回调。 此外，应用程序必须阻止将来再使用已删除的队列。

应用程序还负责管理与队列关联的内存区域，该内存区域在此服务完成后可用。

参数

• queue_ptr：指向以前创建的消息队列的指针。

返回值

• TX_SUCCESS：(0X00) 成功删除消息队列。
• TX_QUEUE_ERROR：(0X09) 消息队列指针无效。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

线程数

可以抢占

是

示例

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. */

另请参阅

• tx_queue_create
• tx_queue_flush
• tx_queue_front_send
• tx_queue_info_get
• tx_queue_performance_info_get
• tx_queue_performance_system_info_get
• tx_queue_prioritize
• tx_queue_receive
• tx_queue_send
• tx_queue_send_notify

tx_queue_flush

清空消息队列中的消息

原型

UINT tx_queue_flush(TX_QUEUE *queue_ptr);

说明

此服务删除存储在指定消息队列中的所有消息。

如果队列已满，则丢弃所有挂起线程的消息。 然后，每个挂起的线程都将恢复，并且返回状态会指示消息发送成功。 如果队列为空，则此服务不执行任何操作。

参数

• queue_ptr：指向以前创建的消息队列的指针。

返回值

• TX_SUCCESS：(0X00) 成功刷新消息队列。
• TX_QUEUE_ERROR：(0X09) 消息队列指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

是

示例

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. */

另请参阅

• tx_queue_create
• tx_queue_delete
• tx_queue_front_send
• tx_queue_info_get
• tx_queue_performance_info_get
• tx_queue_performance_system_info_get
• tx_queue_prioritize
• tx_queue_receive
• tx_queue_send
• tx_queue_send_notify

tx_queue_front_send

将消息发送到队列的前面

原型

UINT tx_queue_front_send(
    TX_QUEUE *queue_ptr,
    VOID *source_ptr, 
    ULONG wait_option);

说明

此服务将消息发送到指定消息队列的前端位置。 将消息从源指针指定的内存区域复制到队列的前面。

参数

• queue_ptr：
  指向消息队列控制块的指针。
• source_ptr：
  指向消息的指针。
• wait_option：
  定义在消息队列已满时服务的行为方式。 等待选项的定义如下：
  • * TX_NO_WAIT：(0x00000000) - 如果选择 TX_NO_WAIT，则无论此服务是否成功，都会导致立即从此服务返回。 如果从非线程（例如初始化、计时器或 ISR）调用服务，则这是唯一有效的选项。
  • TX_WAIT_FOREVER (0xFFFFFFFF) - 选择 TX_WAIT_FOREVER 会导致发出调用的线程无限期挂起，直到队列中有空间为止。
  • 超时值（0x00000001 至 0xFFFFFFFE）- 如果选择一个数值（1 到 0xFFFFFFFE），则会指定在等待队列空间时发出调用的线程保持挂起的最大计时器时钟周期数。

返回值

• TX_SUCCESS：(0X00) 成功发送消息。
• TX_DELETED：(0x01) 线程挂起时删除了消息队列。
• TX_QUEUE_FULL：(0x0B) 服务无法发送消息，因为在指定的等待时间内队列已满。
• TX_WAIT_ABORTED：(0x1A) 挂起状态由其他线程、计时器或 ISR 中止。
• TX_QUEUE_ERROR：(0X09) 消息队列指针无效。
• TX_PTR_ERROR：(0x03) 消息的源指针无效。
• TX_WAIT_ERROR：(0x04) 从非线程调用时指定了除 TX_NO_WAIT 以外的等待选项。

允许来自

初始化、线程、计时器和 ISR

可以抢占

是

示例

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. */

另请参阅

• tx_queue_create
• tx_queue_delete
• tx_queue_flush
• tx_queue_info_get
• tx_queue_performance_info_get
• tx_queue_performance_system_info_get
• tx_queue_prioritize
• tx_queue_receive
• tx_queue_send
• tx_queue_send_notify

tx_queue_info_get

检索有关队列的信息

原型

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);

说明

此服务检索所指定消息队列的相关信息。

参数

• queue_ptr：指向以前创建的消息队列的指针。
• name：指向队列名称指针这一目标的指针。
• enqueued：指向队列中的当前消息数的指针。
• available_storage：指向队列当前可容纳的消息数的指针。
• first_suspended：指向此队列的挂起列表上第一个线程的指针。
• suspended_count：指向此队列中当前挂起的线程数的指针。
• next_queue：指向下一个已创建的队列的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0X00) 成功获取队列信息。
• TX_QUEUE_ERROR：(0X09) 消息队列指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_queue_create
• tx_queue_delete
• tx_queue_flush
• tx_queue_front_send
• tx_queue_performance_info_get
• tx_queue_performance_system_info_get
• tx_queue_prioritize
• tx_queue_receive
• tx_queue_send
• tx_queue_send_notify

tx_queue_performance_info_get

获取队列性能信息

原型

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);

说明

此服务检索所指定消息队列的相关性能信息。

重要

必须使用为此服务定义的 * TX_QUEUE_ENABLE_PERFORMANCE_INFO: 生成 ThreadX 库和应用程序才能返回性能信息。

参数

• queue_ptr：指向之前创建的队列的指针。
• messages_sent：指向对此队列执行的发送请求数的指针。
• messages_received：指向对此队列执行的接收请求数的指针。
• empty_suspensions：指向此队列的队列为空挂起数的指针。
• full_suspensions：指向此队列的队列已满挂起数的指针。
• full_errors：指向此队列的队列已满错误数的指针。
• timeouts：指向此队列的线程挂起超时次数的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0X00) 成功获取队列性能信息。
• TX_PTR_ERROR：(0x03) 队列指针无效。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时未启用性能信息。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_queue_create
• tx_queue_delete
• tx_queue_flush
• tx_queue_front_send
• tx_queue_info_get
• tx_queue_performance_system_info_get
• tx_queue_prioritize
• tx_queue_receive
• tx_queue_send
• tx_queue_send_notify

tx_queue_performance_system_info_get

获取队列系统性能信息

原型

UINT tx_queue_performance_system_info_get(
    ULONG *messages_sent,
    ULONG *messages_received, 
    ULONG *empty_suspensions,
    ULONG *full_suspensions, 
    ULONG *full_errors,
    ULONG *timeouts);

说明

此服务检索系统中所有队列的相关性能信息。

重要

必须使用为此服务定义的 TX_QUEUE_ENABLE_PERFORMANCE_INFO 生成 ThreadX 库和应用程序才能返回性能信息。

参数

• messages_sent：指向对所有队列执行的发送请求总数的指针。
• messages_received：指向对所有队列执行的接收请求总数的指针。
• empty_suspensions：指向所有队列的队列为空挂起总数的指针。
• full_suspensions：指向所有队列的队列已满挂起总数的指针。
• full_errors：指向所有队列的队列已满错误总数的指针。
• timeouts：指向所有队列的线程挂起超时总次数的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0X00) 成功获取队列系统性能信息。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时未启用性能信息。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_queue_create
• tx_queue_delete
• tx_queue_flush
• tx_queue_front_send
• tx_queue_info_get
• tx_queue_performance_info_get
• tx_queue_prioritize
• tx_queue_receive
• tx_queue_send
• tx_queue_send_notify

tx_queue_prioritize

设置队列挂起列表的优先级

原型

UINT tx_queue_prioritize(TX_QUEUE *queue_ptr);

说明

此服务将此队列中消息已挂起的最高优先级线程（或者将消息）放在挂起列表前面。

所有其他线程保持它们挂起时的相同 FIFO 顺序。

参数

• queue_ptr：指向以前创建的消息队列的指针。

返回值

• TX_SUCCESS：(0X00) 成功设置队列优先级。
• TX_QUEUE_ERROR：(0X09) 消息队列指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_queue_create
• tx_queue_delete
• tx_queue_flush
• tx_queue_front_send
• tx_queue_info_get
• tx_queue_performance_info_get
• tx_queue_performance_system_info_get
• tx_queue_receive
• tx_queue_send
• tx_queue_send_notify

tx_queue_receive

从消息队列获取消息

原型

UINT tx_queue_receive(
    TX_QUEUE *queue_ptr,
    VOID *destination_ptr, 
    ULONG wait_option);

说明

此服务从指定的消息队列检索消息。 将检索到的消息从队列复制到目标指针指定的内存区域中。 然后从队列中删除该消息。

重要

指定的目标内存区域必须足够大以容纳消息；也就是说，由 指向的消息目标内存区域必须至少与此队列的消息大小一样大。否则，如果目标不够大，则下一个内存区域会发生内存损坏。

参数

• queue_ptr：
  指向以前创建的消息队列的指针。
• destination_ptr：
  复制消息的位置。
• wait_option：
  定义在消息队列为空时服务的行为方式。 等待选项的定义如下：
  • * TX_NO_WAIT：(0x00000000) - 如果选择 TX_NO_WAIT，则无论此服务是否成功，都会导致立即从此服务返回。 如果从非线程（例如初始化、计时器或 ISR）调用服务，则这是唯一有效的选项。
  • TX_WAIT_FOREVER (0xFFFFFFF) - 选择 TX_WAIT_FOREVER 会导致发出调用的线程无限期挂起，直到消息可用为止。
  • 超时值（0x00000001 至 0xFFFFFFFE）- 如果选择一个数值（1 到 0xFFFFFFFE），则会指定在等待消息时发出调用的线程保持挂起的最大计时器时钟周期数。

返回值

• TX_SUCCESS：(0X00) 成功检索消息。
• TX_DELETED：(0x01) 线程挂起时删除了消息队列。
• TX_QUEUE_EMPTY：(0x0A) 服务无法检索消息，因为队列在指定的等待时间内为空。
• TX_WAIT_ABORTED：(0x1A) 挂起状态由其他线程、计时器或 ISR 中止。
• TX_QUEUE_ERROR：(0X09) 消息队列指针无效。
• TX_PTR_ERROR：(0x03) 消息的目标指针无效。
• TX_WAIT_ERROR：(0x04) 从非线程调用时指定了除 TX_NO_WAIT 以外的等待选项。

允许来自

初始化、线程、计时器和 ISR

可以抢占

是

示例

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." */

另请参阅

• tx_queue_create
• tx_queue_delete
• tx_queue_flush
• tx_queue_front_send
• tx_queue_info_get
• tx_queue_performance_info_get
• tx_queue_performance_system_info_get
• tx_queue_prioritize
• tx_queue_send
• tx_queue_send_notify

tx_queue_send

将消息发送到消息队列

原型

UINT tx_queue_send(
    TX_QUEUE *queue_ptr,
    VOID *source_ptr, 
    ULONG wait_option);

说明

此服务将消息发送到指定的消息队列。 将发送的消息从源指针指定的内存区域复制到队列。

参数

• queue_ptr：
  指向以前创建的消息队列的指针。
• source_ptr：
  指向消息的指针。
• wait_option：
  定义在消息队列已满时服务的行为方式。 等待选项的定义如下：
  • * TX_NO_WAIT：(0x00000000) - 如果选择 TX_NO_WAIT，则无论此服务是否成功，都会导致立即从此服务返回。 如果从非线程（例如初始化、计时器或 ISR）调用服务，则这是唯一有效的选项。
  • TX_WAIT_FOREVER (0xFFFFFFFF) - 选择 TX_WAIT_FOREVER 会导致发出调用的线程无限期挂起，直到队列中有空间为止。
  • 超时值（0x00000001 至 0xFFFFFFFE）- 如果选择一个数值（1 到 0xFFFFFFFE），则会指定在等待队列空间时发出调用的线程保持挂起的最大计时器时钟周期数。

返回值

• TX_SUCCESS：(0X00) 成功发送消息。
• TX_DELETED：(0x01) 线程挂起时删除了消息队列。
• TX_QUEUE_FULL：(0x0B) 服务无法发送消息，因为在指定的等待时间内队列已满。
• TX_WAIT_ABORTED：(0x1A) 挂起状态由其他线程、计时器或 ISR 中止。
• TX_QUEUE_ERROR：(0X09) 消息队列指针无效。
• TX_PTR_ERROR：(0x03) 消息的源指针无效。
• TX_WAIT_ERROR：(0x04) 从非线程调用时指定了除 TX_NO_WAIT 以外的等待选项。

允许来自

初始化、线程、计时器和 ISR

可以抢占

是

示例

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. */

另请参阅

• tx_queue_create
• tx_queue_delete
• tx_queue_flush
• tx_queue_front_send
• tx_queue_info_get
• tx_queue_performance_info_get
• tx_queue_performance_system_info_get
• tx_queue_prioritize
• tx_queue_receive
• tx_queue_send_notify

tx_queue_send_notify

在将消息发送到队列时通知应用程序

原型

UINT tx_queue_send_notify(
    TX_QUEUE *queue_ptr,
    VOID (*queue_send_notify)(TX_QUEUE *));

说明

此服务注册一个通知回调函数，每当消息发送到指定的队列时，就会调用该函数。 通知回调的处理由应用程序定义。

注意

不允许应用程序的队列发送通知回调调用任何带有挂起选项的 ThreadX API。

参数

• queue_ptr：指向之前创建的队列的指针。
• queue_send_notify：指向应用程序的队列发送通知函数的指针。 如果此值为 TX_NULL，则禁用通知。

返回值

• TX_SUCCESS：(0X00) 成功注册队列发送通知。
• TX_QUEUE_ERROR：(0X09) 队列指针无效。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时禁用了通知功能。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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! */
}

另请参阅

• tx_queue_create
• tx_queue_delete
• tx_queue_flush
• tx_queue_front_send
• tx_queue_info_get
• tx_queue_performance_info_get
• tx_queue_performance_system_info_get
• tx_queue_prioritize
• tx_queue_receive
• tx_queue_send

tx_semaphore_ceiling_put

将实例放入具有上限的计数信号灯

原型

UINT tx_semaphore_ceiling_put(
    TX_SEMAPHORE *semaphore_ptr,
    ULONG ceiling);

说明

此服务将一个实例放入指定的计数信号灯，实际上会将计数信号灯增加 1。 如果计数信号灯的当前值大于或等于指定的上限，则不会放入该实例，并将返回 TX_CEILING_EXCEEDED 错误。

参数

• semaphore_ptr：指向之前创建的信号灯的指针。
• ceiling：允许的信号灯上限（有效值的范围介于 1 到 0xFFFFFFFF 之间）。

返回值

• TX_SUCCESS：(0X00) 成功设置信号灯上限。
• TX_CEILING_EXCEEDED：(0x21) 放置请求超过上限。
• TX_INVALID_CEILING：(0x22) 为上限提供的值 (0) 无效。
• TX_SEMAPHORE_ERROR：(0x0C) 信号灯指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

是

示例

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
incremented. */

另请参阅

• tx_semaphore_create
• tx_semaphore_delete
• tx_semaphore_get
• tx_semaphore_info_get
• tx_semaphore_performance_info_get
• tx_semaphore_performance_system_info_get
• tx_semaphore_prioritize
• tx_semaphore_put
• tx_semaphore_put_notify

tx_semaphore_create

创建计数信号灯

原型

UINT tx_semaphore_create(
    TX_SEMAPHORE *semaphore_ptr,
    CHAR *name_ptr, 
    ULONG initial_count);

说明

此服务创建用于线程间同步的计数信号灯。 初始信号灯计数指定为输入参数。

参数

• semaphore_ptr：指向信号灯控制块的指针。
• name_ptr：指向信号灯名称的指针。
• initial_count：指定此信号灯的初始计数。 合法值的范围为 0x00000000 至 0xFFFFFFFF。

返回值

• TX_SUCCESS：(0X00) 成功创建信号灯。
• TX_SEMAPHORE_ERROR：(0x0C) 信号灯指针无效。 指针为 NULL 或已创建信号灯。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

初始化和线程

可以抢占

否

示例

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. */

另请参阅

• tx_semaphore_ceiling_put
• tx_semaphore_delete
• tx_semaphore_get
• tx_semaphore_info_get
• tx_semaphore_performance_info_get
• tx_semaphore_performance_system_info_get
• tx_semaphore_prioritize
• tx_semaphore_put
• tx_semaphore_put_notify

tx_semaphore_delete

删除计数信号灯

原型

UINT tx_semaphore_delete(TX_SEMAPHORE *semaphore_ptr);

说明

此服务删除指定的计数信号灯。 所有挂起并等待信号灯实例的线程都将恢复，并获得 TX_DELETED 返回状态。

重要

在删除信号灯之前，应用程序必须确保完成（或禁用）此信号灯的放置通知回调。 此外，应用程序必须阻止将来再使用已删除的信号灯。

参数

• semaphore_ptr：指向之前创建的信号灯的指针。

返回值

• TX_SUCCESS：(0X00) 成功删除计数信号灯。
• TX_SEMAPHORE_ERROR：(0x0C) 计数信号灯指针无效。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

线程数

可以抢占

是

示例

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. */

另请参阅

• tx_semaphore_ceiling_put
• tx_semaphore_create
• tx_semaphore_get
• tx_semaphore_info_get
• tx_semaphore_performance_info_get
• tx_semaphore_performance_system_info_get
• tx_semaphore_prioritize
• tx_semaphore_put
• tx_semaphore_put_notify

tx_semaphore_get

从计数信号灯获取实例

原型

UINT tx_semaphore_get(
    TX_SEMAPHORE *semaphore_ptr,
    ULONG wait_option);

说明

此服务从指定的计数信号灯检索实例（单个计数）。 因此，指定信号灯的计数将减少 1。

参数

• semaphore_ptr：
  指向之前创建的计数信号灯的指针。
• wait_option：
  定义在没有可用信号灯实例（即信号灯计数为零）的情况下服务的行为方式。 等待选项的定义如下：
  • TX_NO_WAIT (0x00000000) - 如果选择 TX_NO_WAIT，则无论此服务是否成功，都会导致立即从此服务返回。 如果从非线程（例如初始化、计时器或 ISR）调用服务，则这是唯一有效的选项。
  • TX_WAIT_FOREVER (0xFFFFFFF) - 选择 TX_WAIT_FOREVER 会导致发出调用的线程无限期挂起，直到信号灯实例可用为止。
  • 超时值（0x00000001 至 0xFFFFFFFE）- 如果选择一个数值（1 到 0xFFFFFFFE），则会指定在等待信号灯实例时发出调用的线程保持挂起的最大计时器时钟周期数。

返回值

• TX_SUCCESS：(0X00) 成功检索信号灯实例。
• TX_DELETED：(0x01) 线程挂起时删除了计数信号灯。
• TX_NO_INSTANCE：(0X0D) 服务无法检索计数信号灯的实例（信号灯计数在指定的等待时间内为零）。
• TX_WAIT_ABORTED：(0x1A) 挂起状态由其他线程、计时器或 ISR 中止。
• TX_SEMAPHORE_ERROR：(0x0C) 计数信号灯指针无效。
• TX_WAIT_ERROR：(0x04) 从非线程调用时指定了除 TX_NO_WAIT 以外的等待选项。

允许来自

初始化、线程、计时器和 ISR

可以抢占

是

示例

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. */

另请参阅

• tx_semaphore_ceiling_put
• tx_semaphore_create
• tx_semahore_delete
• tx_semaphore_info_get
• tx_semaphore_performance_info_get
• tx_semaphore_prioritize
• tx_semaphore_put
• tx_semaphore_put_notify

tx_semaphore_info_get

检索有关信号灯的信息

原型

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);

说明

此服务检索所指定信号灯的相关信息。

参数

• semaphore_ptr：指向信号灯控制块的指针。
• name：指向信号灯名称指针这一目标的指针。
• current_value：指向当前信号灯的计数这一目标的指针。
• first_suspended：指向此信号灯的挂起列表上第一个线程的指针。
• suspended_count：指向此信号灯中当前挂起的线程数的指针。
• next_semaphore：指向下一个已创建的信号灯的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0X00) 检索信息。

• TX_SEMAPHORE_ERROR：(0x0C) 信号灯指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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,
    &current_value,
    &first_suspended, &suspended_count,
    &next_semaphore);

/* If status equals TX_SUCCESS, the information requested is
valid. */

另请参阅

• tx_semaphore_ceiling_put
• tx_semaphore_create
• tx_semaphore_delete
• tx_semaphore_get
• tx_semaphore_performance_info_get
• tx_semaphore_performance_system_info_get
• tx_semaphore_prioritize
• tx_semaphore_put
• tx_semaphore_put_notify

tx_semaphore_performance_info_get

获取信号灯性能信息

原型

UINT tx_semaphore_performance_info_get(
    TX_SEMAPHORE *semaphore_ptr,
    ULONG *puts, 
    ULONG *gets,
    ULONG *suspensions, 
    ULONG *timeouts);

说明

此服务检索所指定信号灯的相关性能信息。

重要

必须使用为此服务定义的TX_SEMAPHORE_ENABLE_PERFORMANCE_INFO 生成 ThreadX 库和应用程序才能返回性能信息。

参数

• *semaphore_ptr：指向之前创建的信号灯的指针。
• *puts：指向对此信号灯执行的放置请求数这一目标的指针。
• *gets：指向对此信号灯执行的获取请求数这一目标的指针。
• *suspensions：指向此信号灯上的线程挂起数这一目标的指针。
• *timeouts：指向此信号灯的线程挂起超时次数这一目标的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0X00) 成功获取信号灯性能信息。
• TX_PTR_ERROR：(0X03) 信号灯指针无效。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时未启用性能信息。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_semaphore_ceiling_put
• tx_semaphore_create
• tx_semaphore_delete
• tx_semaphore_get
• tx_semaphore_info_get
• tx_semaphore_performance_system_info_get
• tx_semaphore_prioritize
• tx_semaphore_put
• tx_semaphore_put_notify

tx_semaphore_performance_system_info_get

获取信号灯系统性能信息

原型

UINT tx_semaphore_performance_system_info_get(
    ULONG *puts,
    ULONG *gets, 
    ULONG *suspensions, 
    ULONG *timeouts);

说明

此服务检索系统中所有信号灯的相关性能信息。

重要

必须使用为此服务定义的 TX_SEMAPHORE_ENABLE_PERFORMANCE_INFO 生成 ThreadX 库和应用程序才能返回性能信息

参数

• puts：指向对所有信号灯执行的放置请求总数的指针。
• gets：指向对所有信号灯执行的获取请求总数的指针。
• suspensions：指向所有信号灯的线程挂起总数的指针。
• timeouts：指向所有信号灯的线程挂起超时总次数的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0X00) 获取系统性能信息。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时未启用性能信息。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_semaphore_ceiling_put
• tx_semaphore_create
• tx_semaphore_delete
• tx_semaphore_get
• tx_semaphore_info_get
• tx_semaphore_performance_info_get
• tx_semaphore_prioritize
• tx_semaphore_put
• tx_semaphore_put_notify

tx_semaphore_prioritize

设置信号灯挂起列表的优先级

原型

UINT tx_semaphore_prioritize(TX_SEMAPHORE *semaphore_ptr);

说明

此服务将信号灯实例已挂起的最高优先级线程放在挂起列表前面。 所有其他线程保持它们挂起时的相同 FIFO 顺序。

参数

• semaphore_ptr：指向之前创建的信号灯的指针。

返回值

• TX_SUCCESS：(0X00) 成功设置信号灯优先级。
• TX_SEMAPHORE_ERROR：(0x0C) 计数信号灯指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_semaphore_create
• tx_semaphore_delete
• tx_semaphore_get
• tx_semaphore_info_get
• tx_semaphore_put

tx_semaphore_put

将实例放入计数信号灯

原型

UINT tx_semaphore_put(TX_SEMAPHORE *semaphore_ptr);

说明

此服务将一个实例放入指定的计数信号灯，实际上会将计数信号灯增加 1。

注意

如果在信号灯全部为一 (OxFFFFFFFF) 时调用此服务，则新的放置操作将导致信号灯重置为零。

参数

• semaphore_ptr：指向之前创建的计数信号灯控制块的指针。

返回值

• TX_SUCCESS：(0X00) 成功放置信号灯。
• TX_SEMAPHORE_ERROR：(0x0C) 计数信号灯指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

是

示例

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. */

另请参阅

• tx_semaphore_ceiling_put
• tx_semaphore_create
• tx_semaphore_delete
• tx_semaphore_info_get
• tx_semaphore_performance_info_get
• tx_semaphore_performance_system_info_get
• tx_semaphore_prioritize
• tx_semaphore_get
• tx_semaphore_put_notify

tx_semaphore_put_notify

放置信号灯时通知应用程序

原型

UINT tx_semaphore_put_notify(
    TX_SEMAPHORE *semaphore_ptr,
    VOID (*semaphore_put_notify)(TX_SEMAPHORE *));

说明

此服务注册一个通知回调函数，每当放置指定的信号灯时，就会调用该函数。 通知回调的处理由应用程序定义。

注意

不允许应用程序的信号灯通知回调调用任何带有挂起选项的 ThreadX API。

参数

• semaphore_ptr：指向之前创建的信号灯的指针。
• semaphore_put_notify：指向应用程序的信号灯放置通知函数的指针。 如果此值为 TX_NULL，则禁用通知。

返回值

• TX_SUCCESS：(0X00) 成功注册信号灯放置通知。
• TX_SEMAPHORE_ERROR：(0x0C) 信号灯指针无效。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时禁用了通知功能。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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! */
}

另请参阅

• tx_semaphore_ceiling_put
• tx_semaphore_create
• tx_semaphore_delete
• tx_semaphore_get
• tx_semaphore_info_get
• tx_semaphore_performance_info_get
• tx_semaphore_performance_system_info_get
• tx_semaphore_prioritize
• tx_semaphore_put

tx_thread_create

创建应用程序线程

原型

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);

说明

此服务创建一个应用程序线程，该线程在指定的任务入口函数处开始执行。 堆栈、优先级、抢占阈值和时间片都是由输入参数指定的属性。 此外，还指定了线程的初始执行状态。

参数

• thread_ptr：指向线程控制块的指针。

• name_ptr：指向线程名称的指针。

• entry_function：指定线程执行的初始 C 函数。 当线程从此入口函数返回时，它将处于完成状态并无限期挂起。

• entry_input：首次执行时传递给线程的入口函数的 32 位值。 该输入的用途完全由应用程序决定。

• stack_start：堆栈的内存区域的起始地址。

• stack_size：堆栈内存区域中的字节数。 线程的堆栈区域必须足够大，以应对最坏情况下的函数调用嵌套和局部变量使用情况。

• priority：线程的优先级数值。 合法值的范围为 0 至 TX_MAX_PRIORITES-1，其中 0 表示最高优先级。

• preempt_threshold：禁用抢占的最高优先级（0 至 TX_MAX_PRIORITIES-1）。 仅允许高于此级别的优先级抢占该线程。 该值必须小于或等于指定的优先级。 如果设置为等于线程优先级的值，将禁用抢占阈值。

• time_slice：在优先级相同的其他就绪线程有机会运行之前，允许该线程运行的计时器时钟周期数。 请注意，使用抢占阈值将禁用时间片。 合法时间片值的范围为 1 至 0xFFFFFFFF（含）。 值为 TX_NO_TIME_SLICE（值为 0）将禁用此线程的时间片。

  注意

  使用时间切片会产生少量系统开销。 由于时间片仅适用于多个线程具有相同优先级的情况，因此不应为具有唯一优先级的线程分配时间片。

• auto_start：指定线程是立即启动还是置于挂起状态。 合法选项为 TX_AUTO_START (0x01) 和 TX_DONT_START (0x00) 。 如果指定了 TX_DONT_START，应用程序随后必须调用 tx_thread_resume 以便线程运行。

返回值

• TX_SUCCESS：(0X00) 成功创建线程。
• TX_THREAD_ERROR：(0x0E) 线程控制指针无效。 指针为 NULL 或已创建线程。
• TX_PTR_ERROR：(0x03) 入口点的起始地址无效或堆栈区域无效（通常为 NULL）。
• TX_SIZE_ERROR：(0x05) 堆栈区域大小无效。 线程必须至少有 TX_MINIMUM_STACK 个字节才能执行。
• TX_PRIORITY_ERROR：(0x0F) 线程优先级无效，该值超出范围（0 至 (TX_MAX_PRIORITIES-1)）。
• TX_THRESH_ERROR：(0x18) 指定的抢占阈值无效。 此值必须是小于或等于线程初始优先级的有效优先级。
• TX_START_ERROR：(0x10) 自动启动选择无效。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

初始化和线程

可以抢占

是

示例

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. */
}

另请参阅

• tx_thread_delete
• tx_thread_entry_exit_notify
• tx_thread_identify
• tx_thread_info_get
• tx_thread_performance_info_get
• tx_thread_performance_system_info_get
• tx_thread_preemption_change
• tx_thread_priority_change
• tx_thread_relinquish
• tx_thread_reset
• tx_thread_resume
• tx_thread_sleep
• tx_thread_stack_error_notify
• tx_thread_suspend
• tx_thread_terminate
• tx_thread_time_slice_change
• tx_thread_wait_abort

tx_thread_delete

删除应用程序线程

原型

UINT tx_thread_delete(TX_THREAD *thread_ptr);

说明

此服务删除指定的应用程序线程。 由于指定的线程必须处于已终止或已完成状态，因此不能从尝试删除自身的线程中调用此服务。

注意

应用程序负责管理与线程堆栈关联的内存区域，该内存区域在此服务完成后可用。 此外，应用程序必须阻止使用已删除的线程。

参数

• thread_ptr：指向以前创建的应用程序线程的指针。

返回值

• TX_SUCCESS：(0X00) 成功删除线程。
• TX_THREAD_ERROR：(0X0E) 应用程序线程指针无效。
• TX_DELETE_ERROR：(0X11) 指定线程未处于已终止或已完成状态。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

线程和计时器

可以抢占

否

示例

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. */

另请参阅

• tx_thread_create
• tx_thread_entry_exit_notify
• tx_thread_identify
• tx_thread_info_get
• tx_thread_performance_info_get
• tx_thread_performance_system_info_get
• tx_thread_preemption_change
• tx_thread_priority_change
• tx_thread_relinquish
• tx_thread_reset
• tx_thread_resume
• tx_thread_sleep
• tx_thread_stack_error_notify
• tx_thread_suspend
• tx_thread_terminate
• tx_thread_time_slice_change
• tx_thread_wait_abort

tx_thread_entry_exit_notify

在线程进入和退出时通知应用程序

原型

UINT tx_thread_entry_exit_notify(
    TX_THREAD *thread_ptr,
    VOID (*entry_exit_notify)(TX_THREAD *, UINT));

说明

此服务注册一个通知回调函数，每当进入或退出指定的线程时，就会调用该函数。 通知回调的处理由应用程序定义。

注意

不允许应用程序的线程进入/退出通知回调调用任何带有挂起选项的 ThreadX API。

参数

• thread_ptr：指向之前创建的线程的指针。
• entry_exit_notify：指向应用程序的线程进入/退出通知函数的指针。 进入/退出通知函数的第二个参数指定是否存在进入或退出情况。 值 TX_THREAD_ENTRY (0x00) 表示线程已进入，而值 TX_THREAD_EXIT (0x01) 表示线程已退出 。 如果此值为 TX_NULL，则禁用通知。

返回值

• TX_SUCCESS：(0X00) 成功注册线程进入/退出通知函数。
• TX_THREAD_ERROR (0X0E) 线程指针无效。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时禁用了通知功能。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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! */
}

另请参阅

• tx_thread_create
• tx_thread_delete
• tx_thread_entry_exit_notify
• tx_thread_identify
• tx_thread_info_get
• tx_thread_performance_info_get
• tx_thread_performance_system_info_get
• tx_thread_preemption_change
• tx_thread_priority_change
• tx_thread_relinquish
• tx_thread_reset
• tx_thread_resume
• tx_thread_sleep
• tx_thread_stack_error_notify
• tx_thread_suspend
• tx_thread_terminate
• tx_thread_time_slice_change
• tx_thread_wait_abort

tx_thread_identify

检索指向当前正在执行的线程的指针

原型

TX_THREAD* tx_thread_identify(VOID);

说明

此服务将返回指向当前正在执行的线程的指针。 如果没有正在执行的线程，则此服务返回空指针。

注意

如果从 ISR 调用此服务，则返回值表示在执行中断处理程序之前运行的线程。

参数

无

返回值

• thread pointer：指向当前正在执行的线程的指针。 如果没有正在执行的线程，则返回值为 TX_NULL。

允许来自

线程和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_thread_create
• tx_thread_delete
• tx_thread_entry_exit_notify
• tx_thread_info_get
• tx_thread_performance_info_get
• tx_thread_performance_system_info_get
• tx_thread_preemption_change
• tx_thread_priority_change
• tx_thread_relinquish
• tx_thread_reset
• tx_thread_resume
• tx_thread_sleep
• tx_thread_stack_error_notify
• tx_thread_suspend
• tx_thread_terminate
• tx_thread_time_slice_change
• tx_thread_wait_abort

tx_thread_info_get

检索有关线程的信息

原型

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);

说明

此服务检索有关指定线程的信息。

参数

• thread_ptr：指向线程控制块的指针。

• name：指向线程名称指针这一目标的指针。

• state：指向线程的当前执行状态这一目标的指针。 可能的值如下所示。

  • 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：指向线程的运行计数这一目标的指针。

• priority：指向线程优先级这一目标的指针。

• preemption_threshold：指向线程的抢占阈值这一目标的指针。

• time_slice：指向线程的时间片这一目标的指针。

• next_thread：指向下一个已创建的线程的指针。

• suspended_thread：指向挂起列表中的下一个线程的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0X00) 成功检索线程信息。
• TX_THREAD_ERROR：(0x0E) 线程控制指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_thread_create
• tx_thread_delete
• tx_thread_entry_exit_notify
• tx_thread_identify
• tx_thread_performance_info_get
• tx_thread_performance_system_info_get
• tx_thread_preemption_change
• tx_thread_priority_change
• tx_thread_relinquish
• tx_thread_reset
• tx_thread_resume
• tx_thread_sleep
• tx_thread_stack_error_notify
• tx_thread_suspend
• tx_thread_terminate
• tx_thread_time_slice_change
• tx_thread_wait_abort

tx_thread_performance_info_get

获取线程性能信息

原型

UINT tx_thread_performance_info_get(
    TX_THREAD *thread_ptr,
    LONG *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);

说明

此服务检索有关指定线程的性能信息。

重要

必须使用为此服务定义的 TX_THREAD_ENABLE_PERFORMANCE_INFO 生成 ThreadX 库和应用程序才能返回性能信息。

参数

• thread_ptr：指向之前创建的线程的指针。
• resumptions：指向此线程的恢复数的指针。
• suspensions：指向此线程的挂起数的指针。
• solicited_preemptions：指向由于此线程进行的 ThreadX API 服务调用而导致的抢占数的指针。
• interrupt_preemptions：指向此线程由于中断处理而导致的抢占数的指针。
• priority_inversions：指向此线程的优先级倒置数的指针。
• time_slices：指向此线程的时间片数这一目标的指针。
• relinquishes：指向此线程执行的线程放弃次数的指针。
• timeouts：指向此线程的挂起超时次数的指针。
• wait_aborts：指向对此线程执行的等待中止数的指针。
• last_preempted_by：指向最后抢占此线程的线程的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0X00) 成功获取线程性能信息。
• TX_PTR_ERROR：(0x03) 线程指针无效。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时未启用性能信息。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_thread_create
• tx_thread_delete
• tx_thread_entry_exit_notify
• tx_thread_identify
• tx_thread_info_get
• tx_thread_performance_system_info_get
• tx_thread_preemption_change
• tx_thread_priority_change
• tx_thread_relinquish
• tx_thread_reset
• tx_thread_resume
• tx_thread_sleep
• tx_thread_stack_error_notify
• tx_thread_suspend
• tx_thread_terminate
• tx_thread_time_slice_change
• tx_thread_wait_abort

tx_thread_performance_system_info_get

获取线程系统性能信息

原型

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);

说明

此服务检索系统中所有线程的性能信息。

必须使用为此服务定义的 TX_THREAD_ENABLE_PERFORMANCE_INFO 生成 ThreadX 库和应用程序

TX_THREAD_ENABLE_PERFORMANCE_INFO 已定义以便此服务返回性能信息。

参数

• resumptions：指向线程恢复总数的指针。
• suspensions：指向线程挂起总数的指针。
• solicited_preemptions：指向由于线程调用 ThreadX API 服务而导致的线程抢占总数的指针。
• interrupt_preemptions：指向由于中断处理而导致的线程抢占总数的指针。
• priority_inversions：指向线程优先级倒置总数的指针。
• resumptions：指向线程时间片总数的指针。
• relinquishes：指向线程放弃总次数的指针。
• timeouts：指向线程挂起超时总次数的指针。
• wait_aborts：指向线程等待中止总数的指针。
• non_idle_returns：指向线程在另一个线程准备好执行时返回到系统的次数的指针。
• idle_returns：指向线程在没有任何其他线程准备好执行（系统空闲）时返回到系统的次数的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0X00) 成功获取线程系统性能信息。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时未启用性能信息。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_thread_create
• tx_thread_delete
• tx_thread_entry_exit_notify
• tx_thread_identify
• tx_thread_info_get
• tx_thread_performance_info_get
• tx_thread_preemption_change
• tx_thread_priority_change
• tx_thread_relinquish
• tx_thread_reset
• tx_thread_resume
• tx_thread_sleep
• tx_thread_stack_error_notify
• tx_thread_suspend
• tx_thread_terminate
• tx_thread_time_slice_change
• tx_thread_wait_abort

tx_thread_preemption_change

更改应用程序线程的抢占阈值

原型

UINT tx_thread_preemption_change(
    TX_THREAD *thread_ptr,
    UINT new_threshold, 
    UINT *old_threshold);

说明

此服务更改指定线程的抢占阈值。 抢占阈值阻止指定线程被等于或小于抢占阈值的线程抢占。

注意

使用抢占阈值会禁用指定线程的时间切片。

参数

• thread_ptr：指向以前创建的应用程序线程的指针。
• new_threshold：新的抢占阈值优先级（0 至 TX_MAX_PRIORITIES-1）。
• old_threshold：指向恢复为上一个抢占阈值的位置的指针。

返回值

• TX_SUCCESS：(0X00) 成功更改抢占阈值。
• TX_THREAD_ERROR：(0X0E) 应用程序线程指针无效。
• TX_THRESH_ERROR：(0x18) 指定的新抢占阈值是无效的线程优先级（值不介于 0 到 TX_MAX_PRIORITIES-1 之间）或大于（优先级更低）当前线程优先级。
• TX_PTR_ERROR：(0x03) 指向之前的抢占阈值存储位置的指针无效。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

线程和计时器

可以抢占

是

示例

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. */

另请参阅

• tx_thread_create
• tx_thread_delete
• tx_thread_entry_exit_notify
• tx_thread_identify
• tx_thread_info_get
• tx_thread_performance_info_get
• tx_thread_performance_system_info_get
• tx_thread_priority_change
• tx_thread_relinquish
• tx_thread_reset
• tx_thread_resume
• tx_thread_sleep
• tx_thread_stack_error_notify
• tx_thread_suspend
• tx_thread_terminate
• tx_thread_time_slice_change
• tx_thread_wait_abort

tx_thread_priority_change

更改应用程序线程的优先级

原型

UINT tx_thread_priority_change(
    TX_THREAD *thread_ptr,
    UINT new_priority, 
    UINT *old_priority);

说明

此服务更改指定线程的优先级。 有效优先级的范围为 0 至 (TX_MAX_PRIORITES-1)，其中 0 表示最高优先级。

重要

指定线程的抢占阈值会自动设置为新的优先级。 如果需要新的阈值，则必须在此调用之后使用 tx_thread_preemption_change 服务。

参数

• thread_ptr：指向以前创建的应用程序线程的指针。
• new_priority：新的线程优先级（0 至 TX_MAX_PRIORITIES-1）。
• old_priority：指向恢复为上一个线程优先级的位置的指针。

返回值

• TX_SUCCESS：(0X00) 成功更改优先级。
• TX_THREAD_ERROR：(0X0E) 应用程序线程指针无效。
• TX_PRIORITY_ERROR：(0x0F) 指定的新优先级无效（值不介于 0 到 TX_MAX_PRIORITIES-1 之间）。
• TX_PTR_ERROR：(0x03) 指向之前的优先级存储位置的指针无效。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

线程和计时器

可以抢占

是

示例

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. */

另请参阅

• tx_thread_create
• tx_thread_delete
• tx_thread_entry_exit_notify
• tx_thread_identify
• tx_thread_info_get
• tx_thread_performance_info_get
• tx_thread_performance_system_info_get
• tx_thread_preemption_change
• tx_thread_relinquish
• tx_thread_reset
• tx_thread_resume
• tx_thread_sleep
• tx_thread_stack_error_notify
• tx_thread_suspend
• tx_thread_terminate
• tx_thread_time_slice_change
• tx_thread_wait_abort

tx_thread_relinquish

将控制权让给其他应用程序线程

原型

VOID tx_thread_relinquish(VOID);

说明

此服务将处理器控件让给其他具有相同或更高优先级的就绪线程。

注意

除了将控制权让给具有相同优先级的线程以外，此服务还将控制权让给由于当前线程的抢占阈值设置而阻止执行的最高优先级线程。

参数

无

返回值

无

允许调用自

线程数

可以抢占

是

示例

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();
    }
}

另请参阅

• tx_thread_create
• tx_thread_delete
• tx_thread_entry_exit_notify
• tx_thread_identify
• tx_thread_info_get
• tx_thread_performance_info_get
• tx_thread_performance_system_info_get
• tx_thread_preemption_change
• tx_thread_priority_change
• tx_thread_reset
• tx_thread_resume
• tx_thread_sleep
• tx_thread_stack_error_notify
• tx_thread_suspend
• tx_thread_terminate
• tx_thread_time_slice_change
• tx_thread_wait_abort

tx_thread_reset

重置线程

原型

UINT tx_thread_reset(TX_THREAD *thread_ptr);

说明

此服务重置指定的线程，使其在创建线程时定义的入口点执行。 线程必须处于 TX_COMPLETED 或 TX_TERMINATED 状态才能重置

重要

线程必须恢复后才能再次执行。

参数

• mutex_ptr：指向之前创建的线程的指针。

返回值

• TX_SUCCESS：(0X00) 成功重置线程。
• TX_NOT_DONE：(0X20) 指定的线程未处于 TX_COMPLETED 或 TX_TERMINATED 状态 。
• TX_THREAD_ERROR (0X0E) 线程指针无效。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

线程数

可以抢占

是

示例

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. */

另请参阅

• tx_thread_create
• tx_thread_delete
• tx_thread_entry_exit_notify
• tx_thread_identify
• tx_thread_info_get
• tx_thread_performance_info_get
• tx_thread_preformance_system_info_get
• tx_thread_preemption_change
• tx_thread_priority_change
• tx_thread_relinquish
• tx_thread_resume
• tx_thread_sleep
• tx_thread_stack_error_notify
• tx_thread_suspend
• tx_thread_terminate
• tx_thread_time_slice_change
• tx_thread_wait_abort

tx_thread_resume

恢复挂起的应用程序线程

原型

UINT tx_thread_resume(TX_THREAD *thread_ptr);

说明

此服务恢复或准备执行之前由 tx_thread_suspend 调用挂起的线程。 此外，此服务将恢复在创建时未启用自动启动的线程。

参数

• thread_ptr：指向挂起的应用程序线程的指针。

返回值

• TX_SUCCESS：(0X00) 成功恢复线程。
• TX_SUSPEND_LIFTED：(0X19) 之前设置的延迟挂起被解除。
• TX_THREAD_ERROR：(0X0E) 应用程序线程指针无效。
• TX_RESUME_ERROR：(0X12) 指定的线程未挂起，或者以前被 tx_thread_suspend 以外的服务挂起。

允许来自

初始化、线程、计时器和 ISR

可以抢占

是

TX_THREAD my_thread;

示例

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. */

另请参阅

• tx_thread_create
• tx_thread_delete
• tx_thread_entry_exit_notify
• tx_thread_identify
• tx_thread_info_get
• tx_thread_performance_info_get
• tx_thread_performance_system_info_get
• tx_thread_preemption_change
• tx_thread_priority_change
• tx_thread_relinquish
• tx_thread_reset
• tx_thread_sleep
• tx_thread_stack_error_notify
• tx_thread_suspend
• tx_thread_terminate
• tx_thread_time_slice_change
• tx_thread_wait_abort

tx_thread_sleep

在指定的时间内挂起当前线程

原型

UINT tx_thread_sleep(ULONG timer_ticks);

说明

此服务使调用线程在指定的计时器时钟周期数内挂起。 与计时器时钟周期相关的物理时间量特定于应用程序。 此服务只能从应用程序线程调用。

参数

• timer_ticks：挂起调用应用程序线程的计时器时钟周期数，范围为 0 至 0xFFFFFFFF。 如果指定 0，服务将立即返回。

返回值

• TX_SUCCESS：(0X00) 线程成功进入睡眠状态。
• TX_WAIT_ABORTED：(0x1A) 挂起状态由其他线程、计时器或 ISR 中止。
• TX_CALLER_ERROR：(0X13) 从非线程调用了服务。

允许来自

线程数

可以抢占

是

示例

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. */

另请参阅

• tx_thread_create、tx_thread_delete
• tx_thread_entry_exit_notify
• tx_thread_identify
• tx_thread_info_get
• tx_thread_performance_info_get
• tx_thread_performance_system_info_get
• tx_thread_preemption_change
• tx_thread_priority_change
• tx_thread_relinquish
• tx_thread_reset
• tx_thread_resume
• tx_thread_stack_error_notify
• tx_thread_suspend
• tx_thread_terminate
• tx_thread_time_slice_change
• tx_thread_wait_abort

tx_thread_stack_error_notify

注册线程堆栈错误通知回调

原型

UINT tx_thread_stack_error_notify(VOID (*error_handler)(TX_THREAD *));

说明

此服务注册用于处理线程堆栈错误的通知回调函数。 当 ThreadX 在执行过程中检测到线程堆栈错误时，它将调用此通知函数来处理该错误。 对错误的处理完全由应用程序定义。 可以完成从挂起冲突线程到重置整个系统的一切操作。

重要

必须使用为此服务定义的TX_ENABLE_STACK_CHECKING 生成 ThreadX 库才能返回性能信息。

参数

• error_handler：指向应用程序的堆栈错误处理函数的指针。 如果此值为 TX_NULL，则禁用通知。

返回值

• TX_SUCCESS：(0X00) 成功重置线程。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时未启用性能信息。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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.*/

另请参阅

• tx_thread_create
• tx_thread_delete
• tx_thread_entry_exit_notify
• tx_thread_identify
• tx_thread_info_get
• tx_thread_performance_info_get
• tx_thread_preformance_system_info_get
• tx_thread_preemption_change
• tx_thread_priority_change
• tx_thread_relinquish
• tx_thread_reset
• tx_thread_resume
• tx_thread_sleep
• tx_thread_suspend
• tx_thread_terminate
• tx_thread_time_slice_change
• tx_thread_wait_abort

tx_thread_suspend

挂起应用程序线程

原型

UINT tx_thread_suspend(TX_THREAD *thread_ptr);

说明

此服务挂起指定的应用程序线程。 线程可以调用此服务来挂起自身。

注意

如果指定的线程已由于其他原因而挂起，则会在内部保持此挂起，直到之前的挂起被解除为止。 发生这种情况时，将对指定的线程执行无条件挂起。 其他无条件挂起请求不起作用。

挂起后，该线程必须由 tx_thread_resume 恢复后才能再次执行。

参数

• thread_ptr：指向应用程序线程的指针。

返回值

• TX_SUCCESS：(0X00) 线程成功挂起。
• TX_THREAD_ERROR：(0X0E) 应用程序线程指针无效。
• TX_SUSPEND_ERROR：(0X14) 指定的线程处于已终止或已完成状态。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

是

示例

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. */

另请参阅

• tx_thread_create
• tx_thread_delete
• tx_thread_entry_exit_notify
• tx_thread_identify
• tx_thread_info_get
• tx_thread_performance_info_get
• tx_thread_performance_system_info_get
• tx_thread_preemption_change
• tx_thread_priority_change
• tx_thread_relinquish
• tx_thread_reset
• tx_thread_resume
• tx_thread_sleep
• tx_thread_stack_error_notify
• tx_thread_terminate
• tx_thread_time_slice_change
• tx_thread_wait_abort

tx_thread_terminate

终止应用程序线程

原型

UINT tx_thread_terminate(TX_THREAD *thread_ptr);

说明

不管是否挂起线程，此服务都将终止指定的应用程序线程。 线程可以调用此服务来终止自身。

注意

应用程序负责确保线程处于适合终止的状态。 例如，在关键应用程序处理期间，或者在此类处理可能会处于未知状态的其他中间件组件中，不应终止线程。

重要

终止后，必须重置该线程才能再次执行。

参数

• thread_ptr：指向应用程序线程的指针。

返回值

• TX_SUCCESS：(0X00) 线程成功终止。
• TX_THREAD_ERROR：(0X0E) 应用程序线程指针无效。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

线程和计时器

可以抢占

是

示例

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. */

另请参阅

• tx_thread_create tx_thread_delete
• tx_thread_entry_exit_notify
• tx_thread_identify
• tx_thread_info_get
• tx_thread_performance_info_get
• tx_thread_performance_system_info_get
• tx_thread_preemption_change
• tx_thread_priority_change
• tx_thread_relinquish
• tx_thread_reset
• tx_thread_resume
• tx_thread_sleep
• tx_thread_stack_error_notify
• tx_thread_suspend
• tx_thread_time_slice_change
• tx_thread_wait_abort

tx_thread_time_slice_change

更改应用程序线程的时间片

原型

UINT tx_thread_time_slice_change(
    TX_THREAD *thread_ptr,
    ULONG new_time_slice, 
    ULONG *old_time_slice);

说明

此服务更改指定应用程序线程的时间片。 为线程选择时间片可确保在具有相同或更高优先级的其他线程有机会执行之前，该线程的执行时间不会超过指定的计时器时钟周期数。

注意

使用抢占阈值会禁用指定线程的时间切片。

参数

• thread_ptr：指向应用程序线程的指针。
• new_time_slice：新的时间片值。 合法值包括 TX_NO_TIME_SLICE 和从 1 到 0xFFFFFFFF 的数值。
• old_time_slice：指向用于存储指定线程先前时间片值的位置的指针。

返回值

• TX_SUCCESS：(0X00) 成功设置时间片。
• TX_THREAD_ERROR：(0X0E) 应用程序线程指针无效。
• TX_PTR_ERROR：(0x03) 指向之前的时间片存储位置的指针无效。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

线程和计时器

可以抢占

否

示例

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." */

另请参阅

• tx_thread_create
• tx_thread_delete
• tx_thread_entry_exit_notify
• tx_thread_identify
• tx_thread_info_get
• tx_thread_performance_info_get
• tx_thread_performance_system_info_get
• tx_thread_preemption_change
• tx_thread_priority_change
• tx_thread_relinquish
• tx_thread_reset
• tx_thread_resume
• tx_thread_sleep
• tx_thread_stack_error_notify
• tx_thread_suspend
• tx_thread_terminate
• tx_thread_wait_abort

tx_thread_wait_abort

中止指定线程的挂起

原型

UINT tx_thread_wait_abort(TX_THREAD *thread_ptr);

说明

此服务将中止指定线程的睡眠状态或任何其他对象挂起。 如果中止等待，则从线程正在等待的服务返回 TX_WAIT_ABORTED 值。

注意

此服务不会释放由 tx_thread_suspend 服务执行的显式挂起。

参数

• thread_ptr：指向以前创建的应用程序线程的指针。

返回值

• TX_SUCCESS：(0X00) 线程等待成功中止。
• TX_THREAD_ERROR：(0X0E) 应用程序线程指针无效。
• TX_WAIT_ABORT_ERROR：(0X1b) 指定的线程未处于等待状态。

允许来自

初始化、线程、计时器和 ISR

可以抢占

是

示例

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). */

另请参阅

• tx_thread_create
• tx_thread_delete
• tx_thread_entry_exit_notify
• tx_thread_identify
• tx_thread_info_get
• tx_thread_performance_info_get
• tx_thread_performance_system_info_get
• tx_thread_preemption_change
• tx_thread_priority_change
• tx_thread_relinquish
• tx_thread_reset
• tx_thread_resume
• tx_thread_sleep
• tx_thread_stack_error_notify
• tx_thread_suspend
• tx_thread_terminate
• tx_thread_time_slice_change

tx_time_get

检索当前时间

应用程序计时器

原型

ULONG tx_time_get(VOID);

说明

此服务返回内部系统时钟的内容。 每个计时器时钟周期将内部系统时钟增加 1。 系统时钟在初始化期间设置为零，并且可以通过服务 tx_time_set 更改为特定值。

注意

每个计时器时钟周期代表的实际时间特定于应用程序。

参数

无

返回值

• 系统时钟计时周期*：内部自由运行系统时钟的值。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_time_set

tx_time_set

设置当前时间

原型

VOID tx_time_set(ULONG new_time);

说明

此服务将内部系统时钟设置为指定值。 每个计时器时钟周期将内部系统时钟增加 1。

注意

每个计时器时钟周期代表的实际时间特定于应用程序。

参数

• new_time：要添加到系统时钟的新时间，合法值的范围为 0 至 0xFFFFFFFF。

返回值

无

允许来自

线程、计时器和 ISR

可以抢占

否

示例

/* Set the internal system time to 0x1234. */
tx_time_set(0x1234);

/* Current time now contains 0x1234 until the next timer
interrupt. */

另请参阅

• tx_time_get

tx_timer_activate

激活应用程序计时器

原型

UINT tx_timer_activate(TX_TIMER *timer_ptr);

说明

此服务激活指定的应用程序计时器。 同时过期的计时器的过期例程将按其激活的顺序执行。

注意

过期的一次性计时器必须通过 tx_timer_change 重置，然后才能再次激活。

参数

• timer_ptr：指向以前创建的应用程序计时器的指针。

返回值

• TX_SUCCESS：(0X00) 成功激活应用程序计时器。
• TX_TIMER_ERROR：(0X15) 应用程序计时器指针无效。
• TX_ACTIVATE_ERROR：(0X17) 计时器已处于活动状态或是已过期的一次性计时器。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_timer_change
• tx_timer_create
• tx_timer_deactivate
• tx_timer_delete
• tx_timer_info_get
• tx_timer_performance_info_get
• tx_timer_performance_system_info_get

tx_timer_change

更改应用程序计时器

原型

UINT tx_timer_change(
    TX_TIMER *timer_ptr,
    ULONG initial_ticks, 
    ULONG reschedule_ticks);

说明

此服务更改指定应用程序计时器的过期特性。 必须先停用该计时器，然后才能调用此服务。

注意

在此服务之后，需要调用 tx_timer_activate 服务，以便再次启动计时器。

参数

• timer_ptr：指向计时器控制块的指针。
• initial_ticks：指定计时器过期的初始时钟周期数。 合法值的范围为 1 至 0xFFFFFFFF。
• reschedule_ticks：指定第一个计时器过期后所有计时器过期的时钟周期数。 如果此参数为 0，则计时器是一次性的。 否则，对于周期性计时器，合法值的范围为 1 至 0xFFFFFFFF。

注意

过期的一次性计时器必须通过 tx_timer_change 重置，然后才能再次激活。

返回值

• TX_SUCCESS：(0X00) 成功更改应用程序计时器。
• TX_TIMER_ERROR：(0X15) 应用程序计时器指针无效。
• TX_TICK_ERROR：(0x16) 为初始时钟周期提供的值无效（零）。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

线程、计时器和 ISR

可以抢占

否

示例

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);

另请参阅

• tx_timer_activate
• tx_timer_create
• tx_timer_deactivate
• tx_timer_delete
• tx_timer_info_get
• tx_timer_performance_info_get
• tx_timer_performance_system_info_get

tx_timer_create

创建应用程序计时器

原型

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);

说明

此服务创建具有指定过期函数和定期的应用程序计时器。

参数

• timer_ptr：指向计时器控制块的指针

• name_ptr：指向计时器名称的指针。

• expiration_function：在计时器过期时要调用的应用程序函数。

• expiration_input：在计时器过期时要传递到过期函数的输入。

• initial_ticks：指定计时器过期的初始时钟周期数。 合法值的范围为 1 至 0xFFFFFFFF。

• reschedule_ticks：指定第一个计时器过期后所有计时器过期的时钟周期数。 如果此参数为 0，则计时器是一次性的。 否则，对于周期性计时器，合法值的范围为 1 至 0xFFFFFFFF。

  注意

  一次性计时器过期后，必须通过 tx_timer_change 将其重置，然后才能再次激活。

• auto_activate：确定创建期间是否自动激活计时器。 如果此值为 TX_AUTO_ACTIVATE (0x01)，则激活计时器。 否则，如果选择了值 TX_NO_ACTIVATE (0x00)，则所创建的计时器处于非活动状态。 在这种情况下，随后需要调用 tx_timer_activate 服务来实际启动计时器。

返回值

• TX_SUCCESS：(0X00) 成功创建应用程序计时器。
• TX_TIMER_ERROR：(0X15) 应用程序计时器指针无效。 指针为 NULL 或已创建计时器。
• TX_TICK_ERROR：(0x16) 为初始时钟周期提供的值无效（零）。
• TX_ACTIVATE_ERROR：(0x17) 选择的激活无效。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

初始化和线程

可以抢占

否

示例

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. */

另请参阅

• tx_timer_activate
• tx_timer_change
• tx_timer_deactivate
• tx_timer_delete
• tx_timer_info_get
• tx_timer_performance_info_get
• tx_timer_performance_system_info_get

tx_timer_deactivate

停用应用程序计时器

原型

UINT tx_timer_deactivate(TX_TIMER *timer_ptr);

说明

此服务停用指定的应用程序计时器。 如果计时器已停用，则此服务不起作用。

参数

• timer_ptr：指向以前创建的应用程序计时器的指针。

返回值

• TX_SUCCESS：(0X00) 成功停用应用程序计时器。
• TX_TIMER_ERROR：(0X15) 应用程序计时器指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_timer_activate
• tx_timer_change
• tx_timer_create
• tx_timer_delete
• tx_timer_info_get
• tx_timer_performance_info_get
• tx_timer_performance_system_info_get

tx_timer_delete

删除应用程序计时器

原型

UINT tx_timer_delete(TX_TIMER *timer_ptr);

说明

此服务删除指定的应用程序计时器。

注意

应用程序负责阻止使用已删除的计时器。

参数

• timer_ptr：指向以前创建的应用程序计时器的指针。

返回值

• TX_SUCCESS：(0X00) 成功删除应用程序计时器。
• TX_TIMER_ERROR：(0X15) 应用程序计时器指针无效。
• NX_CALLER_ERROR：(0x13) 此服务的调用方无效。

允许来自

线程数

可以抢占

否

示例

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. */

另请参阅

• tx_timer_activate
• tx_timer_change
• tx_timer_create
• tx_timer_deactivate
• tx_timer_info_get
• tx_timer_performance_info_get
• tx_timer_performance_system_info_get

tx_timer_info_get

检索有关应用程序计时器的信息

原型

UINT tx_timer_info_get(
    TX_TIMER *timer_ptr, 
    CHAR **name,
    UINT *active,
    ULONG *remaining_ticks,
    ULONG *reschedule_ticks,
    TX_TIMER **next_timer);

说明

此服务检索有关指定应用程序计时器的信息。

参数

• timer_ptr：指向以前创建的应用程序计时器的指针。
• name：指向计时器名称指针这一目标的指针。
• active：指向计时器活动指示的指针。 如果计时器处于非活动状态或从计时器本身调用此服务，则返回 TX_FALSE 值。 否则，如果计时器处于活动状态，则返回 TX_TRUE 值。
• remaining_ticks：指向在计时器过期前剩余的计时器时钟周期数的指针。
• reschedule_ticks：指向将用于自动重新计划此计时器的计时器时钟周期数的指针。 如果该值为零，则计时器是一次性的，不会重新计划。
• next_timer：指向下一个已创建的应用程序计时器的指针。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0X00) 成功检索计时器信息。
• TX_TIMER_ERROR：(0X15) 应用程序计时器指针无效。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_timer_activate
• tx_timer_change
• tx_timer_create
• tx_timer_deactivate
• tx_timer_delete
• tx_timer_info_get
• tx_timer_performance_info_get
• tx_timer_performance_system_info_get

tx_timer_performance_info_get

获取计时器性能信息

原型

UINT tx_timer_performance_info_get(
    TX_TIMER *timer_ptr,
    ULONG *activates, 
    ULONG *reactivates,
    ULONG *deactivates, 
    ULONG *expirations,
    ULONG *expiration_adjusts);

说明

此服务检索有关指定应用程序计时器的性能信息。

重要

必须使用为此服务定义的 TX_TIMER_ENABLE_PERFORMANCE_INFO 生成 ThreadX 库和应用程序才能返回性能信息。

参数

• timer_ptr：指向之前创建的计时器的指针。
• activates：指向对此计时器执行的激活请求数的指针。
• reactivates：指向对此周期性计时器执行的自动重新激活次数的指针。
• deactivates：指向对此计时器执行的停用请求数的指针。
• expirations：指向此计时器的过期次数的指针。
• expiration_adjusts：指向对此计时器执行的内部过期调整次数的指针。 这些调整是在计时器中断处理中完成的，针对大于默认计时器列表大小的计时器（默认情况下即为过期时间大于 32 个时钟周期的计时器）。

[注意] 为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0X00) 成功获取计时器性能信息。
• TX_PTR_ERROR：(0x03) 计时器指针无效。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时未启用性能信息。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_timer_activate
• tx_timer_change
• tx_timer_create
• tx_timer_deactivate
• tx_timer_delete
• tx_timer_info_get
• tx_timer_performance_system_info_get

tx_timer_performance_system_info_get

获取计时器系统性能信息

原型

UINT tx_timer_performance_system_info_get(
    ULONG *activates,
    ULONG *reactivates, 
    ULONG *deactivates,
    ULONG *expirations, 
    ULONG *expiration_adjusts);

说明

此服务检索有关系统中所有应用程序计时器的性能信息。

重要

必须使用为此服务定义的 TX_TIMER_ENABLE_PERFORMANCE_INFO 生成 ThreadX 库和应用程序才能返回性能信息。

参数

• activates：指向对所有计时器执行的激活请求总数的指针。
• reactivates：指向对所有周期性计时器执行的自动重新激活总次数的指针。
• deactivates：指向对所有计时器执行的停用请求总数的指针。
• expirations：指向所有计时器的过期总次数的指针。
• expiration_adjusts：指向对所有计时器执行的内部过期调整总次数的指针。 这些调整是在计时器中断处理中完成的，针对大于默认计时器列表大小的计时器（默认情况下即为过期时间大于 32 个时钟周期的计时器）。

注意

为任何参数提供 TX_NULL 表示该参数不是必需的。

返回值

• TX_SUCCESS：(0X00) 成功获取计时器系统性能信息。
• TX_FEATURE_NOT_ENABLED：(0xFF) 在编译系统时未启用性能信息。

允许来自

初始化、线程、计时器和 ISR

可以抢占

否

示例

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. */

另请参阅

• tx_timer_activate
• tx_timer_change
• tx_timer_create
• tx_timer_deactivate
• tx_timer_delete
• tx_timer_info_get
• tx_timer_performance_info_get