Semaphore

信号量用于任务间同步和资源访问控制。支持计数信号量（管理多份同类资源）和二元信号量（互斥访问）。提供阻塞获取（down）、带超时获取（down_timeout）、非阻塞尝试（trydown）和释放（up）操作。

与互斥锁的区别：信号量没有"所有者"概念，可以由任务 A 获取、任务 B 释放。适用生产者-消费者模型、资源池管理等场景。

头文件清单

#include "kernel/osal/include/semaphore/osal_semaphore.h"

接口清单

接口名称功能简述

osal_sem_init 创建计数信号量

osal_sem_binary_sem_init 创建二值信号量

osal_sem_down 请求信号量（永久阻塞）

osal_sem_down_timeout 限时请求信号量

osal_sem_down_interruptible 可中断方式请求信号量

osal_sem_trydown 非阻塞方式尝试获取信号量

osal_sem_up 释放信号量

osal_sem_destroy 删除信号量

Functions

osal_sem_init

int osal_sem_init(osal_semaphore *sem, int val)

头文件清单

#include "kernel/osal/include/semaphore/osal_semaphore.h"

功能说明

创建计数信号量控制结构，根据指定初始值初始化信号量可用计数
支持多任务间资源同步与互斥访问
支持系统：linux liteos freertos

前置条件

信号量结构体指针 sem 已分配有效内存空间
调用前信号量尚未被初始化

入参

名称参数类型详细说明约束取值范围

sem osal_semaphore * 信号量控制结构指针非 NULL

val int 信号量初始可用计数 val >= 0

出参

名称数据类型输出说明

sem osal_semaphore * 初始化完成的信号量控制结构

返回值

返回类型：int

返回值文字含义触发场景

OSAL_SUCCESS(0) 创建成功信号量初始化完成

OSAL_FAILURE(-1) 创建失败参数无效或底层信号量创建失败

参考案例

vendor/HiHope_NearLink_DK_WS63E_V03/demo/semaphore/semaphore_example.c#osal_sem_init

osal_sem_binary_sem_init

int osal_sem_binary_sem_init(osal_semaphore *sem, int val)

头文件清单

#include "kernel/osal/include/semaphore/osal_semaphore.h"

功能说明

创建二值信号量控制结构，初始值限定为 0 或 1
适用于任务间简单同步场景，信号量计数不超过 1
支持系统：liteos freertos

前置条件

信号量结构体指针 sem 已分配有效内存空间
调用前信号量尚未被初始化

入参

名称参数类型详细说明约束取值范围

sem osal_semaphore * 信号量控制结构指针非 NULL

val int 二值信号量初始可用计数 [0, 1]

出参

名称数据类型输出说明

sem osal_semaphore * 初始化完成的二值信号量控制结构

返回值

返回类型：int

返回值文字含义触发场景

OSAL_SUCCESS(0) 创建成功二值信号量初始化完成

OSAL_FAILURE(-1) 创建失败参数无效或底层信号量创建失败

参考案例

src/middleware/utils/nv/nv_storage_lib/nv_async_store.c#osal_sem_binary_sem_init
src/middleware/utils/dfx/log_reader/log_uart.c#osal_sem_binary_sem_init

osal_sem_down

int osal_sem_down(osal_semaphore *sem)

头文件清单

#include "kernel/osal/include/semaphore/osal_semaphore.h"

功能说明

请求获取信号量，若信号量可用计数大于 0 则立即获取并计数减 1
若信号量可用计数为 0，调用任务将进入睡眠阻塞，直到信号量被释放
禁止在中断上下文中调用
禁止在系统任务（idle、swtmr）中调用
不推荐在软件定时器回调中使用
支持系统：linux liteos freertos

前置条件

信号量已通过 osal_sem_init 或 osal_sem_binary_sem_init 创建成功
调用上下文为普通任务，禁止中断上下文、系统任务上下文

入参

名称参数类型详细说明约束取值范围

sem osal_semaphore * 待获取的信号量指针非 NULL，已初始化

返回值

返回类型：int

返回值文字含义触发场景

OSAL_SUCCESS(0) 获取成功成功获取信号量

OSAL_FAILURE(-1) 获取失败参数无效或等待超时

参考案例

src/drivers/drivers/hal/sio/hal_sio_v151/hal_sio_v151.c#osal_sem_down
src/drivers/drivers/driver/uart/uart.c#osal_sem_down

osal_sem_down_timeout

int osal_sem_down_timeout(osal_semaphore *sem, unsigned int timeout)

头文件清单

#include "kernel/osal/include/semaphore/osal_semaphore.h"

功能说明

在指定超时时间内请求获取信号量
若信号量可用计数大于 0 则立即获取；若为 0，任务将阻塞等待，直到信号量被释放或超时
超时时间单位为毫秒
禁止在中断上下文中调用
禁止在系统任务（idle、swtmr）中调用
不推荐在软件定时器回调中使用
支持系统：liteos freertos

前置条件

信号量已通过 osal_sem_init 或 osal_sem_binary_sem_init 创建成功
调用上下文为普通任务，禁止中断上下文、系统任务上下文

入参

名称参数类型详细说明约束取值范围

sem osal_semaphore * 待获取的信号量指针非 NULL，已初始化

timeout unsigned int 超时等待时间单位 ms；OSAL_WAIT_FOREVER(-1) 表示永久等待

返回值

返回类型：int

返回值文字含义触发场景

OSAL_SUCCESS(0) 获取成功在超时时间内成功获取信号量

OSAL_FAILURE(-1) 获取失败参数无效或底层信号量请求失败

OSAL_ETIME(-62) 超时等待超时未获取到信号量

参考案例

vendor/HiHope_NearLink_DK_WS63E_V03/demo/semaphore/semaphore_example.c#osal_sem_down_timeout

osal_sem_down_interruptible

int osal_sem_down_interruptible(osal_semaphore *sem)

头文件清单

#include "kernel/osal/include/semaphore/osal_semaphore.h"

功能说明

以可中断方式请求获取信号量
若信号量可用计数大于 0 则立即获取；若为 0，任务将进入睡眠阻塞，直到信号量被释放或被信号中断
支持系统：linux liteos freertos

前置条件

信号量已通过 osal_sem_init 或 osal_sem_binary_sem_init 创建成功
调用上下文为普通任务

入参

名称参数类型详细说明约束取值范围

sem osal_semaphore * 待获取的信号量指针非 NULL，已初始化

返回值

返回类型：int

返回值文字含义触发场景

OSAL_SUCCESS(0) 获取成功成功获取信号量

OSAL_FAILURE(-1) 获取失败信号量请求失败

OSAL_EINTR(-4) 被信号中断睡眠等待期间被信号中断

osal_sem_trydown

int osal_sem_trydown(osal_semaphore *sem)

头文件清单

#include "kernel/osal/include/semaphore/osal_semaphore.h"

功能说明

非阻塞方式尝试获取信号量，不等待
若信号量可用则立即获取，否则立即返回失败
可在中断上下文中调用
信号量可由任何任务或中断释放
返回值语义与 spin_trylock / mutex_trylock 相反：0 表示获取成功，1 表示获取失败
支持系统：linux liteos freertos

前置条件

信号量已通过 osal_sem_init 或 osal_sem_binary_sem_init 创建成功

入参

名称参数类型详细说明约束取值范围

sem osal_semaphore * 待获取的信号量指针非 NULL，已初始化

返回值

返回类型：int

返回值文字含义触发场景

0 获取成功信号量可用，成功获取

1 获取失败信号量不可用，未获取

osal_sem_up

void osal_sem_up(osal_semaphore *sem)

头文件清单

#include "kernel/osal/include/semaphore/osal_semaphore.h"

功能说明

释放信号量，信号量可用计数加 1
可在任意上下文中调用，包括中断上下文
可由未调用 osal_sem_down 的任务释放信号量
支持系统：linux liteos freertos

前置条件

信号量已通过 osal_sem_init 或 osal_sem_binary_sem_init 创建成功

入参

名称参数类型详细说明约束取值范围

sem osal_semaphore * 待释放的信号量指针非 NULL，已初始化

参考案例

vendor/HiHope_NearLink_DK_WS63E_V03/demo/semaphore/semaphore_example.c#osal_sem_up

osal_sem_destroy

void osal_sem_destroy(osal_semaphore *sem)

头文件清单

#include "kernel/osal/include/semaphore/osal_semaphore.h"

功能说明

删除信号量，释放信号量占用的资源空间
信号量删除后不可再使用
支持系统：linux liteos freertos

前置条件

信号量已通过 osal_sem_init 或 osal_sem_binary_sem_init 创建成功
无其他任务正在等待该信号量

入参

名称参数类型详细说明约束取值范围

sem osal_semaphore * 待删除的信号量指针非 NULL，已初始化

参考案例

vendor/HiHope_NearLink_DK_WS63E_V03/demo/semaphore/semaphore_example.c#osal_sem_destroy

Type definitions

osal_semaphore

typedef struct {
    void *sem;
} osal_semaphore;

使用说明：信号量控制结构体，在 osal_sem_init、osal_sem_binary_sem_init、osal_sem_down、osal_sem_down_timeout、osal_sem_down_interruptible、osal_sem_trydown、osal_sem_up、osal_sem_destroy 接口中作为信号量标识载体使用

成员说明：

成员名称数据类型描述

sem void * 底层信号量句柄指针

接口名称	功能简述
osal_sem_init	创建计数信号量
osal_sem_binary_sem_init	创建二值信号量
osal_sem_down	请求信号量（永久阻塞）
osal_sem_down_timeout	限时请求信号量
osal_sem_down_interruptible	可中断方式请求信号量
osal_sem_trydown	非阻塞方式尝试获取信号量
osal_sem_up	释放信号量
osal_sem_destroy	删除信号量

名称	参数类型	详细说明	约束取值范围
sem	osal_semaphore *	信号量控制结构指针	非 NULL
val	int	信号量初始可用计数	val >= 0

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	创建成功	信号量初始化完成
OSAL_FAILURE(-1)	创建失败	参数无效或底层信号量创建失败

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	创建成功	二值信号量初始化完成
OSAL_FAILURE(-1)	创建失败	参数无效或底层信号量创建失败

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	获取成功	成功获取信号量
OSAL_FAILURE(-1)	获取失败	参数无效或等待超时

名称	参数类型	详细说明	约束取值范围
sem	osal_semaphore *	待获取的信号量指针	非 NULL，已初始化
timeout	unsigned int	超时等待时间	单位 ms；OSAL_WAIT_FOREVER(-1) 表示永久等待

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	获取成功	在超时时间内成功获取信号量
OSAL_FAILURE(-1)	获取失败	参数无效或底层信号量请求失败
OSAL_ETIME(-62)	超时	等待超时未获取到信号量

返回值	文字含义	触发场景
0	获取成功	信号量可用，成功获取
1	获取失败	信号量不可用，未获取