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

最新推荐文章于 2024-09-06 15:34:49 发布

XinLiBK

最新推荐文章于 2024-09-06 15:34:49 发布

阅读量4.3k

点赞数 3

分类专栏： CMSIS CMSIS-RTOS2 文档翻译文章标签： ARM CMSIS RTOS RTOS2 RTX

CMSIS 同时被 2 个专栏收录

42 篇文章 33 订阅

订阅专栏

CMSIS-RTOS2 文档翻译

42 篇文章 102 订阅

订阅专栏

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

数据结构
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 second

osEventFlagsSet (sig1_id, 0x0001U); // set the flag 0x0001U for event sig1_id
在另一个应该等待事件的线程中，调用 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 
      
        } 
      
        }