Event#

Event 提供事件标志组的创建、写入、读取、清除与销毁功能,支持任务间基于事件标志的同步机制。

模块公共头文件

#include "event/osal_event.h"

接口清单#

接口名称

功能简述

osal_event_init

初始化事件控制块

osal_event_write

向事件控制块写入指定事件

osal_event_read

读取事件控制块中指定事件

osal_event_clear

清除事件控制块中指定事件

osal_event_destroy

销毁事件控制块

Functions#

osal_event_init #

int osal_event_init(osal_event *event_obj)

声明头文件

#include "event/osal_event.h"

功能说明

  • 初始化事件控制块,为事件控制块分配内存资源。

  • 初始化底层事件对象,使其处于可操作状态。

  • 初始化成功后可进行事件的写入、读取与清除操作。

前置条件

  • 调用时序约束:event_obj 指向的内存必须已分配且 event_obj->event 为 NULL。

  • 上下文限制:禁止在中断上下文中调用。

入参

名称

参数类型

说明

约束取值范围

event_obj

osal_event *

指向待初始化的事件控制块

不为 NULL,且 event 成员为 NULL

返回值

返回类型:int

返回值

文字含义

触发场景

OSAL_SUCCESS:0

执行成功

事件控制块初始化成功

OSAL_FAILURE:-1

执行失败

event_obj 为 NULL、event 成员非 NULL 或内存分配失败

参考案例

  • src/middleware/services/wifi_service/wpa/osdep/osdep_osal.c

osal_event_write #

int osal_event_write(osal_event *event_obj, unsigned int mask)

声明头文件

#include "event/osal_event.h"

功能说明

  • 向事件控制块写入指定事件掩码。

  • 写入后等待该事件的任务将被唤醒。

  • 支持 bit[0:30] 的事件位写入。

前置条件

  • 调用时序约束:当前接口必须在 osal_event_init 成功返回后调用。

  • 上下文限制:禁止在中断上下文中调用。

入参

名称

参数类型

说明

约束取值范围

event_obj

osal_event *

指向目标事件控制块

不为 NULL

mask

unsigned int

待写入的事件掩码

bit[0:30],禁止使用 bit[31]

返回值

返回类型:int

返回值

文字含义

触发场景

OSAL_SUCCESS:0

执行成功

事件写入成功

OSAL_FAILURE:-1

执行失败

event_obj 为 NULL

LOS_ERRNO_EVENT_SETBIT_INVALID:0x02001C00

写入位含禁用位

底层 LOS_EventWrite 错误码直接透传;mask 含 bit[25]

LOS_ERRNO_EVENT_PTR_NULL:0x02001C06

事件未初始化

底层直接透传;event 成员为 NULL(未调用 osal_event_init)时调用

参考案例

  • src/middleware/services/wifi_service/wpa/osdep/osdep_osal.c

osal_event_read #

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

声明头文件

#include "event/osal_event.h"

功能说明

  • 读取事件控制块中指定掩码的事件,支持阻塞等待。

  • 支持按 AND 模式(等待所有期望事件发生)或 OR 模式(等待任一期望事件发生)读取事件。

  • 支持读取后立即清除已读取的事件标志。

前置条件

  • 调用时序约束:当前接口必须在 osal_event_init 成功返回后调用。

  • 上下文限制:禁止在中断上下文中调用;不推荐在软件定时器回调中调用。

入参

名称

参数类型

说明

约束取值范围

event_obj

osal_event *

指向目标事件控制块

不为 NULL

mask

unsigned int

期望读取的事件掩码

bit[0:30],禁止使用 bit[31];liteos 上禁止使用 bit[25]

timeout_ms

unsigned int

读取超时时间,单位 ms;OSAL_EVENT_FOREVER:0xFFFFFFFF 表示永久等待

0 ~ 0xFFFFFFFF

mode

unsigned int

事件读取模式,可组合使用

OSAL_WAITMODE_AND:4U;
OSAL_WAITMODE_OR:2U;
OSAL_WAITMODE_CLR:1U。

返回值

返回类型:int

返回值

文字含义

触发场景

实际读取到的事件位值

成功读取到的事件位

等待条件满足,返回命中 mask 的事件位组合(读到 bit[0] 与 bit[2] 时返回 0x5);为 bit[25] 为 0 的正数,下方 LOS_ERRNO_EVENT_* 错误码的 bit[25] 置位

OSAL_SUCCESS:0

未读取到事件

timeout_ms 为 0 且无匹配事件时立即返回;阻塞等待超时不返回 0,而是返回下方错误码

OSAL_FAILURE:-1

参数无效

event_obj 为 NULL

LOS_ERRNO_EVENT_READ_TIMEOUT:0x02001C01

读超时

底层 LOS_EventRead 错误码直接透传;阻塞等待超时

LOS_ERRNO_EVENT_EVENTMASK_INVALID:0x02001C02

事件掩码无效

底层直接透传;mask 为 0

LOS_ERRNO_EVENT_READ_IN_INTERRUPT:0x02001C03

中断上下文调用

底层直接透传;在中断中调用本接口

LOS_ERRNO_EVENT_FLAGS_INVALID:0x02001C04

事件模式无效

底层直接透传;mode 非法(AND/OR 并存、含未知位或缺省)

LOS_ERRNO_EVENT_READ_IN_LOCK:0x02001C05

调度锁内调用

底层直接透传;持有调度锁时调用

参考案例

  • src/middleware/services/wifi_service/wpa/osdep/osdep_osal.c

osal_event_clear #

int osal_event_clear(osal_event *event_obj, unsigned int mask)

声明头文件

#include "event/osal_event.h"

功能说明

  • 清除事件控制块中指定掩码的事件标志位。

  • 清除后对应事件位被置为 0。

  • 未在掩码中指定的事件位不受影响。

前置条件

  • 调用时序约束:当前接口必须在 osal_event_init 成功返回后调用。

  • 上下文限制:禁止在中断上下文中调用。

入参

名称

参数类型

说明

约束取值范围

event_obj

osal_event *

指向目标事件控制块

不为 NULL

mask

unsigned int

待清除的事件掩码

0 ~ 0xFFFFFFFF

返回值

返回类型:int

返回值

文字含义

触发场景

OSAL_SUCCESS:0

执行成功

事件清除成功

OSAL_FAILURE:-1

执行失败

event_obj 为 NULL

LOS_ERRNO_EVENT_PTR_NULL:0x02001C06

事件未初始化

底层 LOS_EventClear 错误码直接透传;event 成员为 NULL(未调用 osal_event_init)时调用

参考案例

  • src/middleware/services/wifi_service/wpa/osdep/osdep_osal.c

osal_event_destroy #

int osal_event_destroy(osal_event *event_obj)

声明头文件

#include "event/osal_event.h"

功能说明

  • 销毁事件控制块,释放其占用的内存资源。

  • 销毁后将 event 成员置为 NULL。

  • 销毁后该事件控制块不可再被使用。

前置条件

  • 调用时序约束:当前接口必须在 osal_event_init 成功返回后调用,且 event_obj 应由 osal_event_init 初始化。

  • 上下文限制:禁止在中断上下文中调用。

入参

名称

参数类型

说明

约束取值范围

event_obj

osal_event *

指向待销毁的事件控制块

不为 NULL

返回值

返回类型:int

返回值

文字含义

触发场景

OSAL_SUCCESS:0

执行成功

事件控制块销毁成功

OSAL_FAILURE:-1

执行失败

event_obj 为 NULL

LOS_ERRNO_EVENT_SHOULD_NOT_DESTORY:0x02001C08

存在阻塞等待任务

底层 LOS_EventDestroy 错误码直接透传;仍有任务阻塞等待该事件

LOS_ERRNO_EVENT_PTR_NULL:0x02001C06

事件未初始化

底层直接透传;event 成员为 NULL(未调用 osal_event_init)时调用

参考案例

  • src/middleware/services/wifi_service/wpa/osdep/osdep_osal.c

Structures#

osal_event #

typedef struct {
    void *event;
} osal_event;

成员说明

成员名称

数据类型

描述

event

void *

事件控制块指针,指向底层事件对象

Macros#

OSAL_EVENT_FOREVER #

#define OSAL_EVENT_FOREVER 0xFFFFFFFF

OSAL_WAITMODE_AND #

#define OSAL_WAITMODE_AND 4U

OSAL_WAITMODE_OR #

#define OSAL_WAITMODE_OR 2U

OSAL_WAITMODE_CLR #

#define OSAL_WAITMODE_CLR 1U

OSAL_SUCCESS #

#define OSAL_SUCCESS 0

OSAL_FAILURE #

#define OSAL_FAILURE (-1)