mutex

mutex 提供互斥锁功能，用于任务间共享资源的独占式互斥访问，支持阻塞获取、限时获取、可中断获取及非阻塞尝试获取等多种加锁方式。

头文件清单

#include "include/osal/lock/osal_mutex.h"

接口清单

接口名称	功能简述
osal_mutex_init	初始化互斥锁
osal_mutex_lock	获取互斥锁（阻塞等待）
osal_mutex_lock_timeout	限时获取互斥锁
osal_mutex_lock_interruptible	获取互斥锁（可被信号中断）
osal_mutex_trylock	尝试获取互斥锁（非阻塞）
osal_mutex_unlock	释放互斥锁
osal_mutex_is_locked	查询互斥锁是否处于锁定状态
osal_mutex_destroy	销毁互斥锁

Functions

osal_mutex_init

mutex_init osal mutex init osal_mutex_init

int osal_mutex_init(osal_mutex *mutex)

头文件清单

#include "include/osal/lock/osal_mutex.h"

功能说明

• 初始化互斥锁，分配底层锁资源并完成初始状态设置
• 互斥锁初始化后方可被其他互斥锁接口调用，未初始化的互斥锁禁止使用
• 支持 linux、liteos、freertos 系统

前置条件

• 调用时序约束：当前接口需在互斥锁使用前完成初始化调用
• 上下文限制：互斥锁未被初始化（重复初始化将返回失败）

入参

名称	参数类型	详细说明	约束取值范围
mutex	osal_mutex *	指向待初始化的互斥锁结构体指针	非 NULL

返回值

• 返回类型：int

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	初始化成功	互斥锁资源分配成功
OSAL_FAILURE(-1)	初始化失败	mutex 为 NULL、互斥锁已初始化、底层锁资源分配失败

osal_mutex_lock

mutex_lock osal mutex lock osal_mutex_lock

int osal_mutex_lock(osal_mutex *mutex)

头文件清单

#include "include/osal/lock/osal_mutex.h"

功能说明

• 获取互斥锁，独占式加锁，若互斥锁不可用则阻塞等待直至获取
• 互斥锁必须由获取它的同一任务释放，递归加锁不被允许
• 支持 linux、liteos、freertos 系统；LiteOS 和 Freertos 支持嵌套锁特性

前置条件

• 调用时序约束：互斥锁已通过 osal_mutex_init() 初始化成功
• 调用上下文约束：互斥锁不可在中断上下文中使用，禁止递归加锁，任务退出前必须释放互斥锁

入参

名称	参数类型	详细说明	约束取值范围
mutex	osal_mutex *	指向待获取的互斥锁结构体指针	非 NULL，且已初始化

返回值

• 返回类型：int

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	获取互斥锁成功	成功获取互斥锁
OSAL_FAILURE(-1)	获取互斥锁失败	mutex 为 NULL 或底层获取失败

osal_mutex_lock_timeout

mutex_lock_timeout osal mutex lock timeout osal_mutex_lock_timeout

int osal_mutex_lock_timeout(osal_mutex *mutex, unsigned int timeout)

头文件清单

#include "include/osal/lock/osal_mutex.h"

功能说明

• 限时获取互斥锁，在指定时间内等待获取互斥锁，超时则返回失败
• 支持 liteos、freertos 系统；LiteOS 和 Freertos 支持嵌套锁特性
• 当 timeout 为 OSAL_MUTEX_WAIT_FOREVER 时，行为等同于 osal_mutex_lock

前置条件

• 调用时序约束：互斥锁已通过 osal_mutex_init() 初始化成功
• 调用上下文约束：互斥锁不可在中断上下文中使用

入参

名称	参数类型	详细说明	约束取值范围
mutex	osal_mutex *	指向待获取的互斥锁结构体指针	非 NULL，且已初始化
timeout	unsigned int	等待超时时间，单位为毫秒	OSAL_MUTEX_WAIT_FOREVER：永久等待 / 大于 0 且非 OSAL_MUTEX_WAIT_FOREVER：限时等待

返回值

• 返回类型：int

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	获取互斥锁成功	在超时时间内成功获取互斥锁
OSAL_FAILURE(-1)	获取互斥锁失败	mutex 为 NULL、超时未获取或底层获取失败

osal_mutex_lock_interruptible

mutex_lock_interruptible osal mutex lock interruptible osal_mutex_lock_interruptible

int osal_mutex_lock_interruptible(osal_mutex *mutex)

头文件清单

#include "include/osal/lock/osal_mutex.h"

功能说明

• 获取互斥锁，可被信号中断；若等待过程中收到信号，函数将在未获取互斥锁的情况下返回
• 支持 linux、liteos 系统；LiteOS 支持嵌套锁特性
• 适用于需要在等待互斥锁时响应信号的场景

前置条件

• 调用时序约束：互斥锁已通过 osal_mutex_init() 初始化成功
• 调用上下文约束：互斥锁不可在中断上下文中使用

入参

名称	参数类型	详细说明	约束取值范围
mutex	osal_mutex *	指向待获取的互斥锁结构体指针	非 NULL，且已初始化

返回值

• 返回类型：int

返回值	文字含义	触发场景
OSAL_SUCCESS(0)	获取互斥锁成功	成功获取互斥锁
OSAL_FAILURE(-1)	获取互斥锁失败	mutex 为 NULL 或底层获取失败
OSAL_EINTR(-4)	被信号中断	等待过程中收到信号，未获取互斥锁即返回

osal_mutex_trylock

mutex_trylock osal mutex trylock osal_mutex_trylock

int osal_mutex_trylock(osal_mutex *mutex)

头文件清单

#include "include/osal/lock/osal_mutex.h"

功能说明

• 尝试获取互斥锁，非阻塞方式；若互斥锁不可用则立即返回，不等待
• 支持 linux、liteos、freertos 系统；LiteOS 和 Freertos 支持嵌套锁特性
• 适用于不能阻塞等待但仍需尝试获取互斥锁的场景

前置条件

• 调用时序约束：互斥锁已通过 osal_mutex_init() 初始化成功
• 调用上下文约束：互斥锁不可在中断上下文中使用

入参

名称	参数类型	详细说明	约束取值范围
mutex	osal_mutex *	指向待获取的互斥锁结构体指针	非 NULL，且已初始化

返回值

• 返回类型：int

返回值	文字含义	触发场景
TRUE(非0)	获取互斥锁成功	互斥锁空闲，成功获取
FALSE(0)	获取互斥锁失败	mutex 为 NULL 或互斥锁已被占用

osal_mutex_unlock

mutex_unlock osal mutex unlock osal_mutex_unlock

void osal_mutex_unlock(osal_mutex *mutex)

头文件清单

#include "include/osal/lock/osal_mutex.h"

功能说明

• 释放互斥锁，解锁由当前任务先前加锁的互斥锁
• 互斥锁必须由获取它的同一任务释放
• 释放未加锁的互斥锁不被允许
• 支持 linux、liteos、freertos 系统

前置条件

• 调用时序约束：互斥锁已通过 osal_mutex_init() 初始化成功，且当前任务已持有该互斥锁
• 调用上下文约束：不可在中断上下文中调用

入参

名称	参数类型	详细说明	约束取值范围
mutex	osal_mutex *	指向待释放的互斥锁结构体指针	非 NULL，且已初始化

osal_mutex_is_locked

mutex_is_locked osal mutex is locked osal_mutex_is_locked

int osal_mutex_is_locked(osal_mutex *mutex)

头文件清单

#include "include/osal/lock/osal_mutex.h"

功能说明

• 查询互斥锁是否处于锁定状态
• 支持 linux、freertos 系统
• 不修改互斥锁状态，仅查询

前置条件

• 调用时序约束：互斥锁已通过 osal_mutex_init() 初始化成功

入参

名称	参数类型	详细说明	约束取值范围
mutex	osal_mutex *	指向待查询的互斥锁结构体指针	非 NULL，且已初始化

返回值

• 返回类型：int

返回值	文字含义	触发场景
true(非0)	互斥锁处于锁定状态	互斥锁已被某任务持有
false(0)	互斥锁处于解锁状态	互斥锁未被任何任务持有

osal_mutex_destroy

mutex_destroy osal mutex destroy osal_mutex_destroy

void osal_mutex_destroy(osal_mutex *mutex)

头文件清单

#include "include/osal/lock/osal_mutex.h"

功能说明

• 销毁互斥锁，释放底层锁资源
• 必须在模块退出时调用，否则将导致内存泄漏
• osal_mutex_destroy 会释放内部内存，调用者应在调用后将指针置为 NULL
• 支持 linux、liteos、freertos 系统

前置条件

• 调用时序约束：互斥锁已通过 osal_mutex_init() 初始化成功，且互斥锁未被任何任务持有（处于解锁状态）
• 依赖关系：模块退出或不再需要该互斥锁时调用

入参

名称	参数类型	详细说明	约束取值范围
mutex	osal_mutex *	指向待销毁的互斥锁结构体指针	非 NULL，且已初始化

参考案例

• src/drivers/drivers/driver/adc/adc.c
• src/drivers/drivers/driver/spi/spi.c
• src/drivers/drivers/driver/i2c/i2c.c

Structures

osal_mutex

osal mutex osal_mutex

typedef struct {
    void *mutex;
} osal_mutex;

成员说明

成员名称	数据类型	描述
mutex	void *	底层互斥锁句柄指针

Macros

OSAL_MUTEX_WAIT_FOREVER

mutex_wait_forever osal mutex wait forever osal_mutex_wait_forever

#define OSAL_MUTEX_WAIT_FOREVER (-1)

OSAL_SUCCESS

osal success osal_success

#define OSAL_SUCCESS 0

OSAL_FAILURE

osal failure osal_failure

#define OSAL_FAILURE (-1)

OSAL_EINTR

osal eintr osal_eintr

#define OSAL_EINTR (-4)  /* Interrupted system call */