MsgQueue

MsgQueue 提供操作系统抽象层（OSAL, Operating System Abstract Layer）的消息队列功能，支持消息队列的创建、删除、读写与状态查询操作，适用于 LiteOS 与 FreeRTOS 系统。

模块公共头文件

#include "msgqueue/osal_msgqueue.h"

接口清单

接口名称	功能简述
osal_msg_queue_create	创建消息队列
osal_msg_queue_write_copy	向消息队列写入数据
osal_msg_queue_read_copy	从消息队列读取数据
osal_msg_queue_write_head_copy	向消息队列头部写入数据
osal_msg_queue_delete	删除消息队列
osal_msg_queue_is_full	检查消息队列是否已满
osal_msg_queue_get_msg_num	获取消息队列中的消息数量

Functions

osal_msg_queue_create

int osal_msg_queue_create(const char *name, unsigned short queue_len, unsigned long *queue_id, unsigned int flags, unsigned short max_msgsize)

声明头文件

#include "msgqueue/osal_msgqueue.h"

功能说明

创建消息队列，用于任务间消息传递。
支持配置队列长度与单个消息节点大小。
创建成功后通过 queue_id 返回队列标识。

前置条件

依赖关系：LiteOS 系统下需启用 LOSCFG_QUEUE_DYNAMIC_ALLOCATION 配置。
依赖关系：可用队列数量受 LOSCFG_BASE_IPC_QUEUE_LIMIT 限制。

入参

名称	参数类型	说明	约束取值范围
name	const char *	消息队列名称（保留参数，暂未使用）	可为 NULL
queue_len	unsigned short	队列长度	1 ~ 0xFFFF
flags	unsigned int	队列模式（保留参数，暂未使用）	保留参数
max_msgsize	unsigned short	单个消息节点大小	1 ~ 0xFFFF

出参

名称	数据类型	输出说明
queue_id	unsigned long *	成功创建的队列标识 ID

返回值

返回类型：int

返回值	文字含义	触发场景
0	执行成功	消息队列创建成功
非 0	执行失败	消息队列创建失败

参考案例

src/application/ws53/ws53_application/main.c
src/middleware/chips/ws53/dfx/dfx_system_init.c
src/middleware/services/wifi_service/wpa/liteos_wpa_api/wifi_api.c
src/middleware/utils/nv/nv_storage_lib/nv_async_store.c
src/test/common/testsuite/src/test_suite_task.c

Kconfig配置

配置项	宏类型	说明	默认值
TINY_KERNEL	特性宏	精简内核模式下此接口不编译	由构建目标决定

osal_msg_queue_write_copy

int osal_msg_queue_write_copy(unsigned long queue_id, void *buffer_addr, unsigned int buffer_size, unsigned int timeout)

声明头文件

#include "msgqueue/osal_msgqueue.h"

功能说明

向指定消息队列写入数据。
写入数据的大小由 buffer_size 指定，数据存储于 buffer_addr 指向的地址。
支持超时等待，当队列满时按 timeout 阻塞等待。

前置条件

调用时序约束：当前接口需在 LiteOS 初始化后调用，且目标队列已通过 osal_msg_queue_create 创建。
上下文限制：除 FreeRTOS 外，禁止在中断上下文及软件定时器回调中调用。

入参

名称	参数类型	说明	约束取值范围
queue_id	unsigned long	由 osal_msg_queue_create 创建的队列 ID	由 osal_msg_queue_create 创建
buffer_addr	void *	存储待写入数据的缓冲区起始地址	不为 NULL
buffer_size	unsigned int	待写入数据的缓冲区大小	大于 0
timeout	unsigned int	超时时间（单位：Tick）	OSAL_MSGQ_NO_WAIT：0 ~ OSAL_MSGQ_WAIT_FOREVER：0xFFFFFFFF

返回值

返回类型：int

返回值	文字含义	触发场景
0	执行成功	数据写入成功
非 0	执行失败	数据写入失败

参考案例

src/application/ws53/ws53_application/main.c
src/middleware/services/wifi_service/wpa/liteos_wpa_api/wifi_api.c
src/middleware/utils/nv/nv_storage_lib/nv_async_store.c
src/test/common/testsuite/src/test_suite_task.c

osal_msg_queue_read_copy

int osal_msg_queue_read_copy(unsigned long queue_id, void *buffer_addr, unsigned int *buffer_size, unsigned int timeout)

声明头文件

#include "msgqueue/osal_msgqueue.h"

功能说明

从指定消息队列读取数据。
读取的数据存储于 buffer_addr 指向的地址，实际读取大小通过 buffer_size 返回。
采用 FIFO（First In First Out）方式读取，支持超时等待。

前置条件

调用时序约束：当前接口需在 LiteOS 初始化后调用，且目标队列已通过 osal_msg_queue_create 创建。
上下文限制：除 FreeRTOS 外，禁止在中断上下文及软件定时器回调中调用。

入参

名称	参数类型	说明	约束取值范围
queue_id	unsigned long	由 osal_msg_queue_create 创建的队列 ID	由 osal_msg_queue_create 创建
buffer_size	unsigned int *	读取前为期望读取的缓冲区大小	大于 0
timeout	unsigned int	超时时间（单位：Tick）	OSAL_MSGQ_NO_WAIT：0 ~ OSAL_MSGQ_WAIT_FOREVER：0xFFFFFFFF

出参

名称	数据类型	输出说明
buffer_addr	void *	读取到的数据存储缓冲区，由调用方分配内存、函数填充
buffer_size	unsigned int *	读取后为实际读取的数据大小

返回值

返回类型：int

返回值	文字含义	触发场景
0	执行成功	数据读取成功
非 0	执行失败	数据读取失败

参考案例

src/application/ws53/ws53_application/main.c
src/middleware/chips/ws53/dfx/dfx_system_init.c
src/middleware/services/wifi_service/wpa/liteos_wpa_api/wifi_api.c
src/middleware/utils/nv/nv_storage_lib/nv_async_store.c
src/test/common/testsuite/src/test_suite_task.c

osal_msg_queue_write_head_copy

int osal_msg_queue_write_head_copy(unsigned long queue_id, void *buffer_addr, unsigned int buffer_size, unsigned int timeout)

声明头文件

#include "msgqueue/osal_msgqueue.h"

功能说明

向指定消息队列头部写入数据。
写入数据的大小由 buffer_size 指定，数据存储于 buffer_addr 指向的地址。
支持超时等待，当队列满时按 timeout 阻塞等待。

前置条件

调用时序约束：当前接口需在 LiteOS 初始化后调用，且目标队列已通过 osal_msg_queue_create 创建。
上下文限制：除 FreeRTOS 外，禁止在中断上下文及软件定时器回调中调用。

入参

名称	参数类型	说明	约束取值范围
queue_id	unsigned long	由 osal_msg_queue_create 创建的队列 ID	由 osal_msg_queue_create 创建
buffer_addr	void *	存储待写入数据的缓冲区起始地址	不为 NULL
buffer_size	unsigned int	待写入数据的缓冲区大小	1 ~ 0xFFFFFFFF
timeout	unsigned int	超时时间（单位：Tick）	OSAL_MSGQ_NO_WAIT：0 ~ OSAL_MSGQ_WAIT_FOREVER：0xFFFFFFFF

返回值

返回类型：int

返回值	文字含义	触发场景
0	执行成功	数据写入成功
非 0	执行失败	数据写入失败

osal_msg_queue_delete

void osal_msg_queue_delete(unsigned long queue_id)

声明头文件

#include "msgqueue/osal_msgqueue.h"

功能说明

删除指定的消息队列。
删除后该队列不可再用于读写操作。
无法删除未创建的队列。

前置条件

调用时序约束：仅可删除已通过 osal_msg_queue_create 创建的队列。
依赖关系：若有任务阻塞在队列上或队列正在被读写，删除操作将失败。

入参

名称	参数类型	说明	约束取值范围
queue_id	unsigned long	由 osal_msg_queue_create 创建的队列 ID	由 osal_msg_queue_create 创建

参考案例

src/test/common/testsuite/src/test_suite_task.c

osal_msg_queue_is_full

int osal_msg_queue_is_full(unsigned long queue_id)

声明头文件

#include "msgqueue/osal_msgqueue.h"

功能说明

检查指定消息队列是否已满。
返回 true 表示队列已满，false 表示未满。
可用于写入前判断队列剩余空间。

入参

名称	参数类型	说明	约束取值范围
queue_id	unsigned long	由 osal_msg_queue_create 创建的队列 ID	由 osal_msg_queue_create 创建

返回值

返回类型：int

返回值	文字含义	触发场景
1	队列已满	队列已满或获取队列信息失败
0	队列未满	队列未满

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_SEC_CORE	特性宏	支持安全内核特性（分支级，Kconfig 未声明）	-

osal_msg_queue_get_msg_num

unsigned int osal_msg_queue_get_msg_num(unsigned long queue_id)

声明头文件

#include "msgqueue/osal_msgqueue.h"

功能说明

获取指定消息队列中当前的消息数量。
返回当前队列中的消息数。
获取失败时返回 OSAL_INVALID_MSG_NUM。

入参

名称	参数类型	说明	约束取值范围
queue_id	unsigned long	由 osal_msg_queue_create 创建的队列 ID	由 osal_msg_queue_create 创建

返回值

返回类型：unsigned int

返回值	文字含义	触发场景
>= 0	当前消息队列中的消息数量	获取成功
OSAL_INVALID_MSG_NUM：0xFFFFFFFF	获取消息数量失败	获取队列信息失败

参考案例

src/middleware/utils/nv/nv_storage_lib/nv_async_store.c

Kconfig配置

配置项	宏类型	说明	默认值
CONFIG_SEC_CORE	特性宏	支持安全内核特性（分支级，Kconfig 未声明）	-

Macros

OSAL_INVALID_MSG_NUM

#define OSAL_INVALID_MSG_NUM 0xFFFFFFFF

OSAL_MSGQ_WAIT_FOREVER

#ifdef LOS_WAIT_FOREVER
#define OSAL_MSGQ_WAIT_FOREVER LOS_WAIT_FOREVER
#else
#define OSAL_MSGQ_WAIT_FOREVER 0xFFFFFFFF
#endif

OSAL_MSGQ_NO_WAIT

#ifdef LOS_NO_WAIT
#define OSAL_MSGQ_NO_WAIT LOS_NO_WAIT
#else
#define OSAL_MSGQ_NO_WAIT 0
#endif