数据结构 | |
struct | osEventFlagsAttr_t |
事件标志的属性结构体。更多... | |
类型定义 | |
typedef void * | osEventFlagsId_t |
函数 | |
osEventFlagsId_t | osEventFlagsNew (const osEventFlagsAttr_t *attr) |
创建并初始化事件标志对象。更多... | |
uint32_t | osEventFlagsSet (osEventFlagsId_t ef_id, uint32_t flags) |
设置指定的事件标志。更多... | |
uint32_t | osEventFlagsClear (osEventFlagsId_t ef_id, uint32_t flags) |
清除指定的事件标志。更多... | |
uint32_t | osEventFlagsGet (osEventFlagsId_t ef_id) |
获取当前的事件标志。更多... | |
uint32_t | osEventFlagsWait (osEventFlagsId_t ef_id, uint32_t flags, uint32_t options, uint32_t timeout) |
等待一个或多个事件标志发出信号。更多... | |
osStatus_t | osEventFlagsDelete (osEventFlagsId_t ef_id) |
删除事件标志对象。更多... | |
const char * | osEventFlagsGetName (osEventFlagsId_t ef_id) |
获取事件标志对象的名称。更多... | |
描述
CMSIS-RTOS 中的事件标志管理功能允许您控制或等待事件标志。每个信号最多有31个事件标志。
一个线程
- 可以等待事件标志被设置(使用 osEventFlagsWait)。使用此功能,它进入 BLOCKED 状态。
- 可以在任何其他给定线程中使用 osEventFlagsSet 设置一个或多个标志。
- 可以清除自己的信号或其他线程的信号(使用 osEventFlagsClear)。
当线程唤醒并恢复执行时,其信号标志会自动清除(除非指定了事件标志选项 osFlagsNoClear)。
-
注意
- 可以从中断服务例程调用函数 osEventFlagsSet ,osEventFlagsClear ,osEventFlagsGet 和 osEventFlagsWait 。
- 有关 RTX5 配置选项,请参阅事件标志配置。
与事件一起工作
下面是一个简单的例子,它显示了两个线程如何使用事件标志与对方进行通信:
使用事件标志需要以下步骤:
- 在应该发送 id 为 sig1_id 的事件的线程中,调用 set 函数:
osDelay (1000); // wait for 1 secondosEventFlagsSet (sig1_id, 0x0001U); // set the flag 0x0001U for event sig1_id
- 在另一个应该等待事件的线程中,调用 wait 函数:
以下完整的示例代码可以直接与 “CMSIS-RTOS2 主模板” 一起使用,也可以作为 RTX5 的独立模板提供:
代码示例
数据结构文档
struct osEventFlagsAttr_t |
数据字段 | ||
---|---|---|
const char * | name | 事件标志的名称 指向具有人类可读名称的事件对象的字符串。 |
uint32_t | attr_bits | 属性位 保留以供将来使用(设为 '0')。 |
void * | cb_mem | 内存控制块 指向事件控制块对象的内存位置的指针。这可以选择用于自定义内存管理系统。 |
uint32_t | cb_size | 为控制块提供的内存大小 内存块的大小与 cb_mem 一起传递。必须是事件控制块对象的大小或更大。 |
类型文档
函数文档
osEventFlagsId_t osEventFlagsNew | ( | const osEventFlagsAttr_t * | attr | ) |
-
参数
-
[in] attr 事件标志属性; NULL:默认值。
-
返回
- 事件标志 ID 供其他功能参考,或者在出现错误时为 NULL 。
函数 osEventFlagsNew 创建一个新的事件标志对象,该对象用于跨线程发送事件并返回指向事件标志对象标识符的指针,或者在发生错误时返回NULL 。它可以在 RTOS 启动之前(调用 osKernelStart)安全地调用,但不能在它初始化之前调用(调用 osKernelInitialize)。
参数 attr 设置事件标志属性(请参阅 osEventFlagsAttr_t)。如果设置为 NULL,则会使用缺省属性,即内核内存分配用于事件控制块。
-
注意
- 不能从中断服务程序调用。
代码示例
uint32_t osEventFlagsSet | ( | osEventFlagsId_t | ef_id, |
uint32_t | flags | ||
) |
-
参数
-
[in] ef_id 事件标志 ID 由 osEventFlagsNew 获取。 [in] flags 指定应设置的标志。
-
返回
- 如果设置了最高位,则设置后的事件标志或错误代码。
函数 osEventFlagsSet 将由参数标志指定的事件标志设置在由参数 ef_id 指定的事件标志对象中。所有等待标志集的线程都将被通知从阻塞状态恢复。 该函数在设置后返回事件标志或一个错误代码(设置最高位,参见标志功能错误代码)。
可能的标志功能错误代码返回值:
- osFlagsErrorUnknown: 未指定的错误。
- osFlagsErrorResource: 由参数 ef_id 指定的事件标志对象尚未准备好被使用。
- osFlagsErrorParameter: 参数 ef_id 不标识有效的事件标志对象或标志的最高位设置。
-
注意
- 这个函数可以从中断服务程序中调用。
代码示例
uint32_t osEventFlagsClear | ( | osEventFlagsId_t | ef_id, |
uint32_t | flags | ||
) |
-
参数
-
[in] ef_id 事件标志 ID 由 osEventFlagsNew 获取。 [in] flags 指定应被清除的标志。
-
返回
- 清除前的事件标志或设置最高位时的错误代码。
函数 osEventFlagsClear 清除由参数 ef_id 指定的事件标志对象中的参数标志指定的事件标志。该函数在清除之前返回事件标志或发生错误代码(设置最高位,参见标志函数错误代码)。
可能的标志功能错误代码返回值:
- osFlagsErrorUnknown: 未指定的错误。
- osFlagsErrorResource: 由参数 ef_id 指定的事件标志对象尚未准备好被使用。
- osFlagsErrorParameter: 参数 ef_id 不标识有效的事件标志对象或标志的最高位设置。
-
注意
- 这个函数可以从中断服务程序中调用。
uint32_t osEventFlagsGet | ( | osEventFlagsId_t | ef_id | ) |
-
参数
-
[in] ef_id 事件标志 ID 由 osEventFlagsNew 获取。
-
返回
- 当前事件标志。
函数 osEventFlagsGet 返回当前在参数 ef_id 或 0 指定的事件标志对象中设置的事件标志,以防出错。
-
注意
- 这个函数可以从中断服务程序中调用。
uint32_t osEventFlagsWait | ( | osEventFlagsId_t | ef_id, |
uint32_t | flags, | ||
uint32_t | options, | ||
uint32_t | timeout | ||
) |
-
参数
-
[in] ef_id 事件标志 ID 由 osEventFlagsNew 获取。 [in] flags 指定要等待的标志。 [in] options 指定标志选项(osFlagsXxxx)。 [in] timeout 超时值或 0 在没有超时的情况下。
-
返回
- 清除前的事件标志或设置最高位时的错误代码。
osEventFlagsWait 函数暂停执行当前的 RUNNING 线程,直到设置了由参数 ef_id 指定的事件对象中的参数标志指定的任何或全部事件标志为止。当这些事件标志已被设置时,该功能立即返回。否则,线程被置于 BLOCKED 状态。
options 参数指定等待条件:
选项 | |
---|---|
osFlagsWaitAny | 等待任何标志(默认)。 |
osFlagsWaitAll | 等待所有的标志。 |
osFlagsNoClear | 不要清除已经指定等待的标志。 |
如果在选项中设置了 osFlagsNoClear ,则可以使用 osEventFlagsClear 手动清除标志。
参数 timeout 指定系统等待事件标志的时间。系统等待时,调用此函数的线程将进入 BLOCKED 状态。参数超时可以有以下值:
- 当超时为 0 时,函数立即返回(即尝试语义)。
- 当超时设置为 osWaitForever 时,该函数将等待无限时间,直到事件标志变为可用(即等待语义)。
- 所有其他值都指定了内核中的超时时间(即定时等待语义)。
该函数在清除之前返回事件标志或发生错误代码(设置最高位,参见标志函数错误代码)。
可能的标志功能错误代码返回值:
- osFlagsErrorUnknown: 未指定的错误。
- osFlagsErrorTimeout: 在给定的超时期间,等待的标志没有被设置。
- osFlagsErrorResource: 由参数 ef_id 指定的事件标志对象尚未准备好被使用。
- osFlagsErrorParameter: 参数 ef_id 不标识有效的事件标志对象或标志的最高位设置。
-
注意
- 如果参数 timeout 设置为 0,可以从中断服务例程调用。
代码示例
osStatus_t osEventFlagsDelete | ( | osEventFlagsId_t | ef_id | ) |
-
参数
-
[in] ef_id 事件标志 ID 由 osEventFlagsNew 获取。
-
返回
- 状态代码,指示该功能的执行状态。
函数 osEventFlagsDelete 删除由参数 ef_id 指定的事件标志对象,并释放为事件标志处理获得的内部存储器。在这次调用之后,ef_id 不再有效并且不能使用。这可能会导致等待此事件对象标志的线程挨饿。可以使用函数 osEventFlagsNew 再次创建 ef_id 。
可能的 osStatus_t 返回值:
- osOK: 指定的事件标志对象已被删除。
- osErrorISR: 不能从中断服务例程中调用 osEventFlagsDelete 。
- osErrorParameter: 参数 ef_id 的值不正确。
- osErrorResource: 参数 ef_id 为 NULL 或错误。
-
注意
- 该函数不能从中断服务程序调用。
const char * osEventFlagsGetName | ( | osEventFlagsId_t | ef_id | ) |
-
参数
-
[in] ef_id 事件标志 ID 由 osEventFlagsNew 获取。
-
返回
- 名称为 NULL 终止的字符串。
函数 osEventFlagsGetName 返回指向由参数 ef_id 标识的事件标志对象的名称字符串的指针,或者在出现错误时返回 NULL 。
-
注意
- 该函数不能从中断服务程序调用。
代码示例