CMSIS-RTOS2 文档翻译 之 参考（CMSIS-RTOS2 API 之 事件标志）

事件标志

CMSIS-RTOS2 API

使用事件标志同步线程。更多...

数据结构
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 配置选项，请参阅事件标志配置。

与事件一起工作

下面是一个简单的例子，它显示了两个线程如何使用事件标志与对方进行通信：

简单的事件沟通

使用事件标志需要以下步骤：

1. 在应该发送 id 为 sig1_id 的事件的线程中，调用 set 函数：
   osDelay (1000); // wait for 1 second

   osEventFlagsSet (sig1_id, 0x0001U); // set the flag 0x0001U for event sig1_id
2. 在另一个应该等待事件的线程中，调用 wait 函数：
   osEventFlagsWait (sig1_id, 0x0001U, NULL, osWaitForever); // wait forever for any flag

以下完整的示例代码可以直接与 “CMSIS-RTOS2 主模板” 一起使用，也可以作为 RTX5 的独立模板提供：

代码示例

void Thread_EventSender ( void *argument); // thread function 1

void Thread_EventReceiver ( void *argument); // thread function 2

osThreadId_t tid_Thread_EventSender; // thread id 1

osThreadId_t tid_Thread_EventReceiver; // thread id 2

osEventFlagsId_t evt_id; // message queue id

#define FLAGS_MSK1 0x00000001ul

void app_main ( void)

{

tid_Thread_EventSender = osThreadNew (Thread_EventSender, NULL, NULL);

if (tid_Thread_EventSender == NULL) {

; // do something

}

tid_Thread_EventReceiver = osThreadNew (Thread_EventReceiver, NULL, NULL);

if (tid_Thread_EventReceiver == NULL) {

; // do something

}

; // do something

}

void Thread_EventSender ( void *argument)

{

evt_id = osEventFlagsNew(NULL);

while (1) {

osEventFlagsSet(evt_id, FLAGS_MSK1);

osDelay (1000); // suspend thread

}

}

void Thread_EventReceiver ( void *argument)

{

uint32_t flags;

while (1) {

flags = osEventFlagsWait (evt_id,FLAGS_MSK1, osFlagsWaitAny, osWaitForever);

//handle event

}

}

数据结构文档

struct osEventFlagsAttr_t

用于配置事件标志集的属性。

有关使用的详细信息，请参阅内存管理

• osEventFlagsAttr_t::cb_mem
• osEventFlagsAttr_t::cb_size

数据字段
const char *	name	事件标志的名称 指向具有人类可读名称的事件对象的字符串。 默认值：NULL 。
uint32_t	attr_bits	属性位 保留以供将来使用（设为 '0'）。 默认值：0 。
void *	cb_mem	内存控制块 指向事件控制块对象的内存位置的指针。这可以选择用于自定义内存管理系统。 默认值：NULL（使用内核内存管理）。
uint32_t	cb_size	为控制块提供的内存大小 内存块的大小与 cb_mem 一起传递。必须是事件控制块对象的大小或更大。

类型文档

osEventFlagsId_t

事件标志 ID 标识事件标志。

返回者：

• osEventFlagsNew

函数文档

osEventFlagsId_t osEventFlagsNew

(

const osEventFlagsAttr_t *

attr

)

参数

[in]

attr

事件标志属性; NULL：默认值。

返回

事件标志 ID 供其他功能参考，或者在出现错误时为 NULL 。

函数 osEventFlagsNew 创建一个新的事件标志对象，该对象用于跨线程发送事件并返回指向事件标志对象标识符的指针，或者在发生错误时返回NULL 。它可以在 RTOS 启动之前（调用 osKernelStart）安全地调用，但不能在它初始化之前调用（调用 osKernelInitialize）。

参数 attr 设置事件标志属性（请参阅 osEventFlagsAttr_t）。如果设置为 NULL，则会使用缺省属性，即内核内存分配用于事件控制块。

注意

不能从中断服务程序调用。

代码示例

#include "cmsis_os2.h" // CMSIS RTOS header file

osEventFlagsId_t evt_id; // message queue id

void Thread_EventSender ( void *argument)

{

evt_id = osEventFlagsNew(NULL);

while (1) {

osEventFlagsSet(evt_id, FLAGS_MSK1);

osThreadYield (); // suspend thread

}

}

void Thread_EventReceiver ( void *argument)

{

uint32_t flags;

while (1) {

flags = osEventFlagsWait (evt_id,FLAGS_MSK1, osFlagsWaitAny, osWaitForever);

//handle event

}

}

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 不标识有效的事件标志对象或标志的最高位设置。

注意

这个函数可以从中断服务程序中调用。

代码示例

#include "cmsis_os2.h" // CMSIS RTOS header file

osEventFlagsId_t evt_id; // message queue id

void Thread_EventSender ( void *argument)

{

evt_id = osEventFlagsNew(NULL);

while (1) {

osEventFlagsSet(evt_id, FLAGS_MSK1);

osThreadYield (); // suspend thread

}

}

void Thread_EventReceiver ( void *argument)

{

uint32_t flags;

while (1) {

flags = osEventFlagsWait (evt_id,FLAGS_MSK1, osFlagsWaitAny, osWaitForever);

//handle event

}

}

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，可以从中断服务例程调用。

代码示例

#include "cmsis_os2.h" // CMSIS RTOS header file

osEventFlagsId_t evt_id; // message queue id

void Thread_EventSender ( void *argument)

{

evt_id = osEventFlagsNew(NULL);

while (1) {

osEventFlagsSet(evt_id, FLAGS_MSK1);

osThreadYield (); // suspend thread

}

}

void Thread_EventReceiver ( void *argument)

{

uint32_t flags;

while (1) {

flags = osEventFlagsWait (evt_id,FLAGS_MSK1, osFlagsWaitAny, osWaitForever);

//handle event

}

}

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 。

注意

该函数不能从中断服务程序调用。

代码示例

void EvtFlagsGetName_example ( void) {

char id; // id of the event flags object

id = osEventFlagsGetName ();

if ( id == NULL) {

// Failed to get the event flags object name

}

}