Semaphore#
Semaphore 提供信号量功能,用于任务间同步与互斥,支持计数信号量与二值信号量的创建、获取、释放、超时获取、尝试获取及销毁操作。
模块公共头文件
#include "semaphore/osal_semaphore.h"
接口清单#
接口名称 |
功能简述 |
|---|---|
创建信号量并按指定初始值初始化信号量控制结构 |
|
创建二值信号量并按指定初始值初始化信号量控制结构 |
|
请求获取信号量,未获取时永久阻塞等待 |
|
在指定超时时间内请求获取信号量 |
|
请求获取信号量,阻塞等待期间可被信号中断 |
|
尝试获取信号量,不阻塞等待 |
|
释放信号量 |
|
销毁信号量并释放资源 |
Functions#
osal_sem_init #
int osal_sem_init(osal_semaphore *sem, int val)
声明头文件
#include "semaphore/osal_semaphore.h"
功能说明
创建信号量并按指定初始可用数量初始化信号量控制结构。
支持设置初始信号量计数值(val),作为可用信号量的初始数量。
适用于任务间同步与资源计数场景。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
val |
int |
信号量初始可用数量 |
>= 0 |
出参
名称 |
数据类型 |
输出说明 |
|---|---|---|
sem |
信号量控制结构指针,由函数初始化填充 |
返回值
返回类型:int
返回值 |
文字含义 |
触发场景 |
|---|---|---|
执行成功 |
信号量创建并初始化成功 |
|
OSAL_FAILURE:-1 |
执行失败 |
参数无效(sem 为 NULL、sem 已初始化或 val 为负数)或内存分配失败 |
参考案例
src/middleware/utils/hcc/host/hcc_sdio_host.csrc/protocol/wifi/source/host/hmac/hmac_sniffer.c
osal_sem_binary_sem_init #
int osal_sem_binary_sem_init(osal_semaphore *sem, int val)
声明头文件
#include "semaphore/osal_semaphore.h"
功能说明
创建二值信号量并按指定初始值初始化信号量控制结构。
初始值取值范围为 0 或 1,表示信号量的初始可用状态。
适用于仅需两种状态(可用/不可用)的同步场景。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
val |
int |
二值信号量初始可用数量 |
0 ~ 1 |
出参
名称 |
数据类型 |
输出说明 |
|---|---|---|
sem |
信号量控制结构指针,由函数初始化填充 |
返回值
返回类型:int
返回值 |
文字含义 |
触发场景 |
|---|---|---|
执行成功 |
二值信号量创建并初始化成功 |
|
OSAL_FAILURE:-1 |
执行失败 |
参数无效(sem 为 NULL 或 val 不在 0~1 范围)或创建失败 |
参考案例
src/middleware/utils/dfx/log_reader/log_uart.csrc/middleware/utils/nv/nv_storage_lib/nv_async_store.c
osal_sem_down #
int osal_sem_down(osal_semaphore *sem)
声明头文件
#include "semaphore/osal_semaphore.h"
功能说明
请求获取信号量,若信号量不可用则将当前任务阻塞等待。
信号量可用时获取成功,信号量计数值递减。
阻塞等待为永久等待,直到信号量被释放。
前置条件
调用时序约束:当前接口必须在
osal_sem_init成功返回后调用。上下文限制:禁止在中断上下文调用,禁止在系统任务(idle、swtmr)中调用,不推荐在软件定时器回调中使用。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
sem |
待获取的信号量 |
不为 NULL |
返回值
返回类型:int
返回值 |
文字含义 |
触发场景 |
|---|---|---|
执行成功 |
成功获取信号量 |
|
OSAL_FAILURE:-1 |
执行失败 |
参数无效(sem 为 NULL)或获取信号量失败 |
参考案例
src/middleware/utils/dfx/log_reader/log_uart.csrc/protocol/wifi/source/host/hmac/hmac_sniffer.c
osal_sem_down_timeout #
int osal_sem_down_timeout(osal_semaphore *sem, unsigned int timeout)
声明头文件
#include "semaphore/osal_semaphore.h"
功能说明
在指定超时时间内请求获取信号量。
信号量可用时获取成功;超时未获取则停止等待并返回失败。
超时时间可设置为 OSAL_SEM_WAIT_FOREVER 表示永久等待。
前置条件
调用时序约束:当前接口必须在
osal_sem_init成功返回后调用。上下文限制:禁止在中断上下文调用,禁止在系统任务(idle、swtmr)中调用,不推荐在软件定时器回调中使用。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
sem |
待获取的信号量 |
不为 NULL |
|
timeout |
unsigned int |
等待超时时间(单位 ms) |
OSAL_SEM_WAIT_FOREVER:-1; |
返回值
返回类型:int
返回值 |
文字含义 |
触发场景 |
|---|---|---|
执行成功 |
在超时时间内获取信号量成功 |
|
OSAL_FAILURE:-1 |
执行失败 |
参数无效(sem 为 NULL)、超时未获取或获取失败 |
参考案例
src/middleware/utils/hcc/host/hcc_sdio_host.csrc/middleware/utils/nv/nv_storage_lib/nv_async_store.c
osal_sem_down_interruptible #
int osal_sem_down_interruptible(osal_semaphore *sem)
声明头文件
#include "semaphore/osal_semaphore.h"
功能说明
请求获取信号量,若信号量不可用则将当前任务阻塞等待。
阻塞等待期间可被信号中断,中断后停止等待并返回。
适用于需要在等待信号量时响应信号的场景。
前置条件
调用时序约束:当前接口必须在
osal_sem_init成功返回后调用。上下文限制:接口会使任务进入睡眠,禁止在中断上下文调用。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
sem |
待获取的信号量 |
不为 NULL |
返回值
返回类型:int
返回值 |
文字含义 |
触发场景 |
|---|---|---|
执行成功 |
成功获取信号量 |
|
OSAL_FAILURE:-1 |
执行失败 |
参数无效(sem 为 NULL)或获取信号量失败 |
OSAL_EINTR:-4 |
被信号中断 |
阻塞等待期间被信号中断 |
osal_sem_trydown #
int osal_sem_trydown(osal_semaphore *sem)
声明头文件
#include "semaphore/osal_semaphore.h"
功能说明
尝试获取信号量,不阻塞当前任务。
信号量可用时获取成功,不可用时立即返回失败状态。
可在中断上下文调用,信号量可由任意任务或中断释放。
前置条件
调用时序约束:当前接口必须在
osal_sem_init成功返回后调用。上下文限制:当前接口可在中断上下文调用。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
sem |
待获取的信号量 |
不为 NULL |
返回值
返回类型:int
返回值 |
文字含义 |
触发场景 |
|---|---|---|
0 |
获取信号量成功 |
成功获取信号量 |
1 |
未能获取信号量 |
信号量不可获取或参数无效,函数立即返回不等待 |
osal_sem_up #
void osal_sem_up(osal_semaphore *sem)
声明头文件
#include "semaphore/osal_semaphore.h"
功能说明
释放信号量,信号量计数值递增。
若有任务正在等待该信号量,释放后唤醒等待任务。
可在任意上下文调用,包括未获取过该信号量的任务。
前置条件
调用时序约束:当前接口必须在
osal_sem_init成功返回后调用。上下文限制:当前接口可在任意上下文调用,包括未调用过
osal_sem_down的任务。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
sem |
待释放的信号量 |
不为 NULL |
参考案例
src/middleware/utils/hcc/host/hcc_sdio_host.csrc/middleware/utils/dfx/log_reader/log_uart.c
osal_sem_destroy #
void osal_sem_destroy(osal_semaphore *sem)
声明头文件
#include "semaphore/osal_semaphore.h"
功能说明
销毁信号量并释放其占用的资源。
销毁后信号量控制结构不再可用。
适用于信号量不再需要时的资源回收。
前置条件
调用时序约束:当前接口必须在
osal_sem_init成功返回后调用。依赖关系:销毁后信号量句柄失效,不可再用于其他信号量接口。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
sem |
待销毁的信号量 |
不为 NULL |
参考案例
src/middleware/utils/hcc/host/hcc_sdio_host.c
Structures#
osal_semaphore #
typedef struct {
void *sem;
} osal_semaphore;
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
sem |
void * |
信号量内部句柄指针,由 osal_sem_init 或 osal_sem_binary_sem_init 初始化填充 |
Macros#
OSAL_SEM_WAIT_FOREVER #
#define OSAL_SEM_WAIT_FOREVER (-1)
OSAL_SUCCESS [SDK 公共共享宏]#
#define OSAL_SUCCESS 0
OSAL_FAILURE [SDK 公共共享宏]#
#define OSAL_FAILURE (-1)
OSAL_EINTR [SDK 公共共享宏]#
#define OSAL_EINTR (-4) /* Interrupted system call */