event

event 提供 OSAL (OS Abstract Layer) 的事件机制，支持事件控制块的初始化、写入、读取、清除、销毁与非阻塞轮询操作，兼容 LiteOS 和 FreeRTOS 系统。

头文件清单

#include "include/osal/event/osal_event.h"

接口清单

接口名称	功能简述
osal_event_init	初始化事件控制块
osal_event_write	向事件控制块写入指定事件
osal_event_read	读取事件（支持阻塞等待与超时）
osal_event_clear	清除指定事件标志位
osal_event_destroy	销毁事件控制块并释放资源
osal_event_poll	非阻塞轮询事件状态

Functions

osal_event_init

event_init osal event init osal_event_init

int osal_event_init(osal_event *event_obj)

头文件清单

#include "include/osal/event/osal_event.h"

功能说明

• 初始化事件控制块，分配底层事件资源并完成初始化
• 作为事件读写、清除、销毁等操作的初始化入口
• 支持 LiteOS 和 FreeRTOS 系统

前置条件

• event_obj 指针不为 NULL，且 event_obj->event 为 NULL（未初始化状态）
• 底层系统内存资源充足，可分配事件控制块所需内存

入参

名称	参数类型	详细说明	约束取值范围
event_obj	osal_event *	指向待初始化的事件控制块	非 NULL，且 event 成员为 NULL

返回值

• 返回类型：int

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	初始化成功	事件控制块初始化完成
OSAL_FAILURE(-1)	初始化失败	event_obj 为 NULL、event_obj->event 不为 NULL 或内存分配失败

osal_event_write

event_write osal event write osal_event_write

int osal_event_write(osal_event *event_obj, unsigned int mask)

头文件清单

#include "include/osal/event/osal_event.h"

功能说明

• 向事件控制块写入指定事件掩码，触发等待该事件的任务
• 事件掩码中 bit31 禁止使用，该位被系统内部保留
• 支持 LiteOS 和 FreeRTOS 系统

前置条件

• event_obj 已通过 osal_event_init() 初始化成功
• 事件掩码 mask 的 bit31 为 0

入参

名称	参数类型	详细说明	约束取值范围
event_obj	osal_event *	指向已初始化的事件控制块	非 NULL，且已初始化
mask	unsigned int	待写入的事件掩码	bit31 为 0；其余位按业务需求设置

返回值

• 返回类型：int

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	写入成功	事件写入完成
OSAL_FAILURE(-1)	写入失败	event_obj 为 NULL 或 mask 的 bit31 为 1

osal_event_read

event_read osal event read osal_event_read

int osal_event_read(osal_event *event_obj, unsigned int mask, unsigned int timeout_ms, unsigned int mode)

头文件清单

#include "include/osal/event/osal_event.h"

功能说明

• 读取事件，根据 mode 指定的等待模式（AND/OR/CLR）阻塞或非阻塞等待事件发生
• 超时时间可设置为具体毫秒值或 OSAL_EVENT_FOREVER 永久等待
• LiteOS 系统下事件掩码 bit25 禁止使用
• 支持 LiteOS 和 FreeRTOS 系统

前置条件

• 调用时序约束：event_obj 已通过 osal_event_init() 初始化成功
• 调用上下文约束：不得在中断上下文中调用；不推荐在软件定时器回调中调用
• 事件掩码 mask 的 bit31 为 0；LiteOS 系统下 bit25 禁止使用

入参

名称	参数类型	详细说明	约束取值范围
event_obj	osal_event *	指向已初始化的事件控制块	非 NULL，且已初始化
mask	unsigned int	期望读取的事件掩码	bit31 为 0；LiteOS 下 bit25 禁止使用
timeout_ms	unsigned int	超时等待时间（单位：ms）	OSAL_EVENT_FOREVER(0xFFFFFFFF) / 其他数值（超时毫秒数）
mode	unsigned int	事件读取模式	OSAL_WAITMODE_AND(4) / OSAL_WAITMODE_OR(2) / OSAL_WAITMODE_CLR(1)

返回值

• 返回类型：int

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	读取成功	事件匹配成功
OSAL_FAILURE(-1)	读取失败	event_obj 为 NULL、mask 的 bit31 为 1 或读取超时

osal_event_clear

event_clear osal event clear osal_event_clear

int osal_event_clear(osal_event *event_obj, unsigned int mask)

头文件清单

#include "include/osal/event/osal_event.h"

功能说明

• 清除事件控制块中指定掩码对应的事件标志位，将匹配的事件 ID 置为 0
• 事件控制块必须指向有效内存
• 支持 LiteOS 和 FreeRTOS 系统

前置条件

• event_obj 已通过 osal_event_init() 初始化成功

入参

名称	参数类型	详细说明	约束取值范围
event_obj	osal_event *	指向已初始化的事件控制块	非 NULL，且已初始化
mask	unsigned int	待清除的事件掩码	按业务需求设置

返回值

• 返回类型：int

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	清除成功	事件标志位清除完成
OSAL_FAILURE(-1)	清除失败	event_obj 为 NULL

osal_event_destroy

event_destroy osal event destroy osal_event_destroy

int osal_event_destroy(osal_event *event_obj)

头文件清单

#include "include/osal/event/osal_event.h"

功能说明

• 销毁事件控制块，释放底层事件资源并释放已分配的内存
• event_obj 必须由 osal_event_init() 初始化获得，本接口会释放内部动态分配的内存
• 支持 LiteOS 和 FreeRTOS 系统

前置条件

• event_obj 已通过 osal_event_init() 初始化成功
• 无其他任务正在等待该事件控制块

入参

名称	参数类型	详细说明	约束取值范围
event_obj	osal_event *	指向待销毁的事件控制块	非 NULL，且已初始化

返回值

• 返回类型：int

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	销毁成功	事件控制块销毁及内存释放完成
OSAL_FAILURE(-1)	销毁失败	event_obj 为 NULL

osal_event_poll

event_poll osal event poll osal_event_poll

int osal_event_poll(osal_event *event_obj, unsigned int mask, unsigned int mode)

头文件清单

#include "include/osal/event/osal_event.h"

功能说明

• 非阻塞轮询事件控制块，检查指定掩码的事件是否已发生
• 根据 mode 指定的模式（AND/OR）判断事件匹配条件
• 不阻塞当前任务，适用于实时性要求较高的场景
• 支持 LiteOS 和 FreeRTOS 系统

前置条件

• event_obj 已通过 osal_event_init() 初始化成功
• mask 不为 0

入参

名称	参数类型	详细说明	约束取值范围
event_obj	osal_event *	指向已初始化的事件控制块	非 NULL，且已初始化
mask	unsigned int	待轮询的事件掩码	非 0
mode	unsigned int	事件轮询模式	OSAL_WAITMODE_AND(4) / OSAL_WAITMODE_OR(2)

返回值

• 返回类型：int

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	轮询成功	指定事件已发生
OSAL_FAILURE(-1)	轮询失败	event_obj 为 NULL 或 mask 为 0

Structures

osal_event

osal event osal_event

typedef struct {
    void *event;
} osal_event;

成员说明

成员名称	数据类型	描述
event	void *	底层事件控制块指针，由 osal_event_init() 内部分配，由 osal_event_destroy() 释放

Macros

OSAL_EVENT_FOREVER

event_forever osal event forever osal_event_forever

#define OSAL_EVENT_FOREVER 0xFFFFFFFF

OSAL_WAITMODE_AND

osal waitmode and osal_waitmode_and waitmode_and

// Event reading mode: The task waits for all its expected events to occur.
#define OSAL_WAITMODE_AND 4U

OSAL_WAITMODE_OR

osal waitmode or osal_waitmode_or waitmode_or

// Event reading mode: The task waits for any of its expected events to occur.
#define OSAL_WAITMODE_OR 2U

OSAL_WAITMODE_CLR

osal waitmode clr osal_waitmode_clr waitmode_clr

// Event reading mode: The event flag is immediately cleared after the event is read.
#define OSAL_WAITMODE_CLR 1U

OSAL_SUCCESS [SDK公共共享宏]

osal success osal_success

#define OSAL_SUCCESS 0

OSAL_FAILURE [SDK公共共享宏]

osal failure osal_failure

#define OSAL_FAILURE (-1)