ThreadX学习（8）——事件标志

学习参考

• 《Real-Time Embedded Multithreading: Using ThreadX and ARM》
  （链接：https://pan.baidu.com/s/1GMScXSlHq13yS4AVxP_zPw 提取码：ysuw ）
• Chapter 4 - Description of Azure RTOS ThreadX SMP Services 官方

事件标志

事件标志是线程同步的一个强大工具。

事件标志可以被任何线程设置或清除，也可以被任何线程检查。

线程可以在等待设置某些事件标志组时挂起。

事件标志组

每个事件标志用1 bit表示，事件标志以32个为一组排列，组成一个事件标志组。之后的所有操作都是以组为单位。

线程可以同时对一个组中的所有32个事件标志进行操作。

要设置或清除事件标志组，可以使用tx_event_flags_set服务。

使用tx_event_flags_get服务可以“获取”事件标志组。

事件标志等待

获取事件标志时，线程可以等待一个事件标志（一段时间或永久等待），直到该事件标志被另一个线程或中断设置为1(set状态)。

API

1.tx_event_flags_create

TX_EVENT_FLAGS_GROUP group_ptr;//先定义再创建

UINT  tx_event_flags_create(TX_EVENT_FLAGS_GROUP *group_ptr, CHAR *name_ptr)

创建事件标志组：

• 第 1 个参数 group_ptr 是事件标志组控制块指针。
• 第 2 个参数 name_ptr 是事件标志组名称字符串。
• 返回值：
  • TX_SUCCESS: (0x00) 成功。
  • TX_GROUP_ERROR:(0x06)无效的事件组指针。要么指针为NULL，要么事件组已经创建。
  • X_CALLER_ERROR:(0x13)无效的服务调用者。

2.tx_event_flags_delete

UINT  tx_event_flags_delete(TX_EVENT_FLAGS_GROUP *group_ptr)

删除事件标志组：

• 第 1 个参数 group_ptr 是事件标志组控制块指针。
• 返回值：
  • TX_SUCCESS: (0x00) 成功。
  • TX_GROUP_ERROR:(0x06)无效的事件组指针。
  • TX_CALLER_ERROR:(0x13)无效的服务调用者。

当删除一个组时，它挂起的所有线程将恢复，并返回TX_DELETED状态。请确保不要尝试使用已删除的事件标志组

3.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)

获取事件标志组：

• 第 1 个参数 group_ptr 是事件标志组控制块指针。
• 第 2 个参数 requested_flags 是请求的事件标志，如需要获取第0、4、8位的事件标志，则该参数为0x111（… 0000 0001 0001 0001）。
• 第 3 个参数 get_option 是获取选项：
  • TX_OR(0x00)：对请求的所有事件标志进行“或”操作，即只要有一个请求的事件标志为1，则返回TX_SUCCESS。
  • TX_OR_CLEAR(0x01)：同上，且清除所有请求的事件标志。
  • TX_AND(0x02)：对请求的所有事件标志进行“与”操作，即必须所有请求的事件标志都为1，才能返回TX_SUCCESS。
  • TX_AND_CLEAR：同上，且清除所有请求的事件标志。
• 第 4 个参数 actual_flags_ptr 是请求该事件标志组前的旧值（包含未请求部分），所存储的指针。
• 第 5 个参数 wait_option 是等待选项：
  • TX_NO_WAIT(0x00000000)：不等待
  • TX_WAIT_FOREVER(0xFFFFFFFF)：永久等待
  • timeout value(0x00000001-0xFFFFFFFE)：等待指定时间
• 返回值：
  • TX_SUCCESS:(0x00)获得成功。
  • TX_DELETED: (0x01)线程挂起时事件标记组被删除。
  • TX_NO_EVENTS: (0x07)服务无法在指定的等待时间内获得指定的事件。
  • TX_WAIT_ABORTED: (0x1A)挂起被另一个线程、计时器或ISR中止。
  • TX_GROUP_ERROR:(0x06)无效的group_ptr指针。
  • TX_PTR_ERROR:(0x03)无效的actual_flags_ptr指针。
  • TX_WAIT_ERROR: (0x04)在非线程调用时指定了TX_NO_WAIT以外的等待选项。
  • TX_OPTION_ERROR: (0x08)无效的get-option被指定。

4.tx_event_flags_set

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

设置事件标志：

• 第 1 个参数 group_ptr 是事件标志组控制块指针。
• 第 2 个参数 flags_to_set 是设置的事件标志，视设置选项而定。
• 第 3 个参数 set_option 是设置选项：
  • TX_AND: (0x02)将事件标志组旧值与flags_to_set进行“与”操作，一般用于对事件标志的清除，因此flags_to_set中的清除目标应该设为0。如旧值为0x11（0001 0001），要清除第0位，则flags_to_set为0xFE（1111 1110）。
  • TX_OR: (0x00)将事件标志组旧值与flags_to_set进行“或”操作，一般用于对事件标志的设置，因此flags_to_set中的设置目标应该设为1。如旧值为0x11（0001 0001），要设置第1位，则flags_to_set为0x02（0000 0010）。
• 返回值：
  • TX_SUCCESS: (0x00) 成功.
  • TX_GROUP_ERROR: (0x06) 无效的事件标志组指针.
  • TX_OPTION_ERROR: (0x08) 无效的设置选项.

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

获取事件标志组信息：

• 第 1 个参数 group_ptr 是事件标志组控制块指针。
• 第 2 个参数 name 是事件标志组名字符串，获取后存储的指针。
• 第 3 个参数 current_flags 是事件标志组的值，所存储的指针。
• 第 4 个参数 first_suspended 是请求该事件标志组的挂起列表的第一个线程TCB，所存储的指针。
• 第 5 个参数 suspended_count 是请求该事件标志组被挂起的线程数，所存储的指针。
• 第 6 个参数 next_group 是下一个事件标志组，所存储的指针。
• 返回值：
  • TX_SUCCESS:(0x00)成功。
  • TX_GROUP_ERROR:(0x06)无效的事件组指针。

6.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 *));

事件标志设置通知回调：

• 第 1 个参数 group_ptr 是事件标志组控制块指针。
• 第 2 个参数 events_set_notify 是事件标志设置通知函数的指针。如果该值为TX_NULL，则禁用通知。
• 返回值：
  • TX_SUCCESS: (0x00)成功注册事件标志设置通知。
  • TX_GROUP_ERROR:(0x06)无效的事件标志组指针。
  • TX_FEATURE_NOT_ENABLED: (0xFF)系统编译时禁用了通知功能。