# 开发指导
#### 使用场景
多任务环境下往往存在多个任务竞争同一临界资源的应用场景，互斥锁可以提供任务间的互斥机制，防止两个任务在同一时刻访问相同的临界资源，从而实现独占式访问。
#### 功能
Huawei LiteOS 的互斥锁模块为用户提供下面几种功能，接口详细信息可以查看API参考。
| 功能分类     | 接口名           | 描述      |
|:---|:---|:---|
| 创建/删除互斥锁 | LOS_MuxCreate | 创建互斥锁   |
| 创建/删除互斥锁 | LOS_MuxDelete | 删除指定互斥锁 |
| 申请/释放互斥锁 | LOS_MuxPend   | 申请指定互斥锁 |
| 申请/释放互斥锁 | LOS_MuxPost   | 释放指定互斥锁 |
   
![](https://support.huaweicloud.com/kernelmanual-LiteOS/public_sys-resources/note_3.0-zh-cn.png)
申请互斥锁有三种模式：无阻塞模式、永久阻塞模式、定时阻塞模式。
- 无阻塞模式：即任务申请互斥锁时，入参timeout等于0。若当前没有任务持有该互斥锁，或者持有该互斥锁的任务和申请该互斥锁的任务为同一个任务，则申请成功，否则立即返回申请失败。
- 永久阻塞模式：即任务申请互斥锁时，入参timeout等于0xFFFFFFFF。若当前没有任务持有该互斥锁，则申请成功。否则，任务进入阻塞态，系统切换到就绪任务中优先级最高者继续执行。任务进入阻塞态后，直到有其他任务释放该互斥锁，阻塞任务才会重新得以执行。
- 定时阻塞模式：即任务申请互斥锁时，0\<timeout\<0xFFFFFFFF。若当前没有任务持有该互斥锁，则申请成功。否则该任务进入阻塞态，系统切换到就绪任务中优先级最高者继续执行。任务进入阻塞态后，超时前如果有其他任务释放该互斥锁，则该任务可成功获取互斥锁继续执行，若超时前未获取到该互斥锁，接口将返回超时错误码。
释放互斥锁：
- 如果有任务阻塞于该互斥锁，则唤醒被阻塞任务中优先级最高的，该任务进入就绪态，并进行任务调度。
- 如果没有任务阻塞于该互斥锁，则互斥锁释放成功。
 
#### 互斥锁错误码
对存在失败可能性的操作返回对应的错误码，以便快速定位错误原因。
| 序号 | 定义                                | 实际数值       | 描述                     | 参考解决方案                                           |
|:---|:---|:---|:---|:---|
| 1  | LOS_ERRNO_MUX_NO_MEMORY           | 0x02001d00 | 初始化互斥锁模块时，内存不足         | 设置更大的系统动态内存池，配置项为OS_SYS_MEM_SIZE，或减少系统支持的最大互斥锁个数 |
| 2  | LOS_ERRNO_MUX_INVALID             | 0x02001d01 | 互斥锁不可用                 | 传入有效的互斥锁ID                                       |
| 3  | LOS_ERRNO_MUX_PTR_NULL            | 0x02001d02 | 创建互斥锁时，入参为空指针          | 传入有效指针                                           |
| 4  | LOS_ERRNO_MUX_ALL_BUSY            | 0x02001d03 | 创建互斥锁时，系统中已经没有可用的互斥锁   | 增加系统支持的最大互斥锁个数                                   |
| 5  | LOS_ERRNO_MUX_UNAVAILABLE         | 0x02001d04 | 申请互斥锁失败，因为锁已经被其他线程持有   | 等待其他线程解锁或者设置等待时间                                 |
| 6  | LOS_ERRNO_MUX_PEND_INTERR         | 0x02001d05 | 在中断中使用互斥锁              | 禁止在中断中申请/释放互斥锁                                   |
| 7  | LOS_ERRNO_MUX_PEND_IN_LOCK        | 0x02001d06 | 锁任务调度时，不允许以阻塞模式申请互斥锁   | 以非阻塞模式申请互斥锁，或使能任务调度后再阻塞申请互斥锁                     |
| 8  | LOS_ERRNO_MUX_TIMEOUT             | 0x02001d07 | 申请互斥锁超时                | 增加等待时间，或采用一直等待模式                                 |
| 9  | LOS_ERRNO_MUX_OVERFLOW            | 0x02001d08 | 暂不使用该错误码               | -                                                |
| 10 | LOS_ERRNO_MUX_PENDED              | 0x02001d09 | 删除正在使用的互斥锁锁            | 等待解锁后再删除该互斥锁                                     |
| 11 | LOS_ERRNO_MUX_GET_COUNT_ERR       | 0x02001d0a | 暂不使用该错误码               | -                                                |
| 12 | LOS_ERRNO_MUX_REG_ERROR           | 0x02001d0b | 暂不使用该错误码               | -                                                |
| 13 | LOS_ERRNO_MUX_PEND_IN_SYSTEM_TASK | 0x02001d0c | 系统任务中获取互斥锁，如idle和软件定时器 | 不在系统任务中申请互斥锁                                     |
   
![](https://support.huaweicloud.com/kernelmanual-LiteOS/public_sys-resources/notice_3.0-zh-cn.png)
错误码定义见[错误码简介](https://support.huaweicloud.com/kernelmanual-LiteOS/zh-cn_topic_0311018405.html#ZH-CN_TOPIC_0311018405__zh-cn_topic_0175230332_section29852515161)。8\~15位的所属模块为互斥锁模块，值为0x1d。
#### 开发流程
互斥锁典型场景的开发流程：
1. 执行make menuconfig命令，进入Kernel ---\> Enable Mutex菜单，完成互斥锁的配置。
   
   | 配置项                        | 含义              | 取值范围    | 默认值  | 依赖                  |
   |:---|:---|:---|:---|:---|
   | LOSCFG_BASE_IPC_MUX        | 互斥锁模块裁剪开关       | YES/NO  | YES  | 无                   |
   | LOSCFG_MUTEX_WAITMODE_PRIO | 互斥锁基于任务优先级的等待模式 | YES/NO  | YES  | LOSCFG_BASE_IPC_MUX |
   | LOSCFG_MUTEX_WAITMODE_FIFO | 互斥锁基于FIFO的等待模式  | YES/NO  | NO   | LOSCFG_BASE_IPC_MUX |
   | LOSCFG_BASE_IPC_MUX_LIMIT  | 系统支持的最大互斥锁个数    | \<65535 | 1024 | LOSCFG_BASE_IPC_MUX |
      
   
2. 创建互斥锁LOS_MuxCreate。
3. 申请互斥锁LOS_MuxPend。
4. 释放互斥锁LOS_MuxPost。
5. 删除互斥锁LOS_MuxDelete。
 
#### 平台差异性
无。