05.SDK_Manual.md

# \*TencentOS Tiny SDK 文档

[TOC]

# 内核 API

## 系统管理

### tos_knl_init

```c
k_err_t tos_knl_init(void);
```

- 功能描述

  初始化内核。

- 参数解释

  无

- 返回值

  K_ERR_NONE 内核初始化成功。

  非 K_ERR_NONE 内核初始化失败。

### tos_knl_start

```c
k_err_t tos_knl_start(void);
```

- 功能描述

  启动内核。

- 参数解释

  无

- 返回值

  K_ERR_NONE 内核启动成功。

  非 K_ERR_NONE 内核启动失败。

### tos_knl_is_running

```c
int tos_knl_is_running(void);
```

- 功能描述

  判断内核是否正在运行。

- 参数解释

  无

- 返回值

  0 内核不在运行。

  非 0 内核正在运行。

### tos_knl_irq_enter

```c
void tos_knl_irq_enter(void);
```

- 功能描述

  此函数应该在中断服务函数开始之前被调用。

- 参数解释

  无

- 返回值

  无

### tos_knl_irq_leave

```c
void tos_knl_irq_leave(void);
```

- 功能描述

  此函数应该在中断服务函数结束之前被调用。

- 参数解释

  无

- 返回值

  无

### tos_knl_sched_lock

```c
k_err_t tos_knl_sched_lock(void);
```

- 功能描述

  锁内核调度。

- 参数解释

  无

- 返回值

  K_ERR_NONE 内核调度锁定成功。

  K_ERR_KNL_NOT_RUNNING 内核并未处于运行状态。

  K_ERR_LOCK_NESTING_OVERFLOW 调度锁溢出。

  K_ERR_IN_IRQ 在中断服务程序ISR中上锁

### tos_knl_sched_unlock

```c
k_err_t tos_knl_sched_unlock(void);
```

- 功能描述

  解锁内核调度。

- 参数解释

  无

- 返回值

  K_ERR_NONE 内核调度解锁成功。

  K_ERR_KNL_NOT_RUNNING 内核并未处于运行状态。

  K_ERR_SCHED_NOT_LOCKED 内核调度并未处于锁定状态。

  K_ERR_IN_IRQ 在中断服务程序ISR中卸锁

## 任务管理

### tos_task_create

```c
k_err_t tos_task_create(k_task_t *task,
                        char *name,
                        k_task_entry_t entry,
                        void *arg,
                        k_prio_t prio,
                        k_stack_t *stk_base,
                        size_t stk_size,
                        k_timeslice_t timeslice);
```

- **功能描述**

  创建任务。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**                                                         |
  | ---------- | :--------- | ---------------------------------------------------------------- |
  | [in]       | task       | 任务结构体描述符                                                 |
  | [in]       | name       | 任务名称                                                         |
  | [in]       | entry      | 任务入口函数                                                     |
  | [in]       | arg        | 任务入口函数参数                                                 |
  | [in]       | prio       | 任务优先级                                                       |
  | [in]       | stk_base   | 任务栈空间首地址                                                 |
  | [in]       | stk_size   | 任务栈空间的大小                                                 |
  | [in]       | timeslice  | 时间片轮转调度侧策略中，时间片的大小设置，0 表示设置为系统默认值 |

- **返回值**

  K_ERR_NONE 任务创建成功。

  K_ERR_TASK_STK_SIZE_INVALID 非法的任务栈大小。

  K_ERR_TASK_PRIO_INVALID 非法的任务优先级。

  K_ERR_IN_IRQ在中断服务程序lSR中创建任务

  K_ERR_OBJ_PTR_NULL传入的指针中包含有NULL指针

  K_ERR_TASK_ALREADY_CREATED 该任务已经被创建

### tos_task_create_dyn

```c
k_err_t tos_task_create_dyn(k_task_t **task,
                        char *name,
                        k_task_entry_t entry,
                        void *arg,
                        k_prio_t prio,
                        size_t stk_size,
                        k_timeslice_t timeslice);
```

- **功能描述**

  动态创建任务，task 句柄及 task 所需的栈皆为系统动态分配。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**                                                         |
  | ---------- | :--------- | ---------------------------------------------------------------- |
  | [out]      | task       | 任务结构体描述符                                                 |
  | [in]       | name       | 任务名称                                                         |
  | [in]       | entry      | 任务入口函数                                                     |
  | [in]       | arg        | 任务入口函数参数                                                 |
  | [in]       | prio       | 任务优先级                                                       |
  | [in]       | stk_size   | 任务栈空间的大小                                                 |
  | [in]       | timeslice  | 时间片轮转调度侧策略中，时间片的大小设置，0 表示设置为系统默认值 |

- **返回值**

  K_ERR_NONE 任务创建成功。

  K_ERR_TASK_STK_SIZE_INVALID 非法的任务栈大小。

  K_ERR_TASK_PRIO_INVALID 非法的任务优先级。

  K_ERR_TASK_OUT_OF_MEMORY 系统堆内存不足。

  K_ERR_IN_IRQ 在中断服务程序ISR中创建任务

  K_ERR_OBJ_PTR_NULL 传入的指针中包含有NULL指针

  K_ERR_TASK_ALREADY_CREATED 该任务已经被创建

### tos_task_destroy

```c
k_err_t tos_task_destroy(k_task_t *task)
```

- **功能描述**

  销毁静态创建的任务。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**         |
  | ---------- | ---------- | ---------------- |
  | [in]       | task       | 任务结构体描述符 |

- **返回值**

  K_ERR_NONE 任务销毁成功。

  K_ERR_TASK_DESTROY_IDLE 试图销毁 idle 任务（非法）。

  K_ERR_IN_IRQ 试图在中断服务程序ISR中销毁任务

  K_ERR_OBJ_INVALID 传入的参数不是一个正确的kernel_object

  K_ERR_SCHED_LOCKED 已经上锁且删除当前任务(非法 导致死锁)

  K_ERR_OBJ_INVALID_ALLOC_TYPE [若开启动态创建]不是一个静态的任务!

### tos_task_destroy_dyn

```c
k_err_t tos_task_destroy_dyn(k_task_t *task)
```

- **功能描述**

  销毁动态创建（tos_task_create_dyn）的任务。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**         |
  | ---------- | ---------- | ---------------- |
  | [in]       | task       | 任务结构体描述符 |

- **返回值**

  K_ERR_NONE 任务销毁成功。

  K_ERR_TASK_DESTROY_IDLE 试图销毁 idle 任务（非法）。

  K_ERR_OBJ_INVALID 传入的参数不是一个正确的kernel_object

  K_ERR_SCHED_LOCKED 已经上锁且删除当前任务(非法 导致死锁)

  K_ERR_OBJ_INVALID_ALLOC_TYPE 删除的任务不是一个dynamic创建的task!

### tos_task_delay

```c
k_err_t tos_task_delay(k_tick_t delay);
```

- **功能描述**

  睡眠当前任务，以系统时钟滴答数为单位。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**     |
  | ---------- | ---------- | ------------ |
  | [in]       | delay      | 任务睡眠时间 |

- **返回值**

  K_ERR_NONE 任务延迟成功。

  K_ERR_DELAY_ZERO delay 值为零（非法）。

  K_ERR_IN_IRQ 试图在中断服务程序ISR延时

  K_ERR_SCHED_LOCKED 已经上锁( 上锁后不能延时当前任务 否则导致无法调度)

  K_ERR_DELAY_FOREVER 使用suspend 代替这个forever 的delay

### tos_task_delay_abort

```c
k_err_t tos_task_delay_abort(k_task_t *task);
```

- **功能描述**

  取消一个任务的 delay 状态。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**         |
  | ---------- | ---------- | ---------------- |
  | [in]       | task       | 任务结构体描述符 |

- **返回值**

  K_ERR_NONE 取消 delay 成功。

  K_ERR_TASK_NOT_DELAY task 并未处于 delay 状态。

  K_ERR_TASK_SUSPENDED task 被挂起（suspend）。

  K_ERR_IN_IRQ 试图在中断服务程序ISR取消延时

  K_ERR_OBJ_PTR_NULL 传入的task任务为Null Ptr

  K_ERR_OBJ_INVALID 传入的task任务不是一个Kernel对象

### tos_task_suspend

```c
k_err_t tos_task_suspend(k_task_t *task);
```

- **功能描述**

  挂起一个任务（剥夺一个任务的运行调度）。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**         |
  | ---------- | ---------- | ---------------- |
  | [in]       | task       | 任务结构体描述符 |

- **返回值**

  TOS_ERR_NONE 挂起任务成功。

  K_ERR_TASK_SUSPEND_IDLE 试图挂起 idle 任务（非法）。

  K_ERR_OBJ_INVALID 传入的task任务不是一个Kernel对象

  K_ERR_SCHED_LOCKED 上锁了同时要挂起自己

### tos_task_resume

```c
k_err_t tos_task_resume(k_task_t *task);
```

- **功能描述**

  恢复一个任务的调度运行。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**         |
  | ---------- | ---------- | ---------------- |
  | [in]       | task       | 任务结构体描述符 |

- **返回值**

  TOS_ERR_NONE 恢复任务运行成功。

  K_ERR_TASK_RESUME_SELF 试图恢复当前任务（非法）。

  K_ERR_OBJ_PTR_NULL 传入的task是一个Null ptr

  K_ERR_OBJ_INVALID 传入的task不是一个kernel 对象

### tos_task_prio_change

```c
k_err_t tos_task_prio_change(k_task_t *task, k_prio_t prio_new);
```

- **功能描述**

  更改一个任务的优先级。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**         |
  | ---------- | ---------- | ---------------- |
  | [in]       | task       | 任务结构体描述符 |
  | [in]       | prio_new   | 新的优先级       |

- **返回值**

  K_ERR_NONE 任务优先级更新成功。

  K_ERR_TASK_PRIO_INVALID 优先级非法。

  K_ERR_OBJ_PTR_NULL 传入的task是一个Null ptr

  K_ERR_OBJ_INVALID 传入的task不是一个kernel 对象

  K_ERR_IN_IRQ 试图在中断服务程序ISR中改变某个任务的优先级

### tos_task_yield

```c
void tos_task_yield(void);
```

- **功能描述**

  当前任务主动放弃 cpu。

- **参数解释**

  无

- **返回值**

  无

### tos_task_stack_draught_depth

```c
k_err_t tos_task_stack_draught_depth(k_task_t *task, int *depth);
```

- **功能描述**

  获取一个任务栈的最大吃水深度。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**         |
  | ---------- | ---------- | ---------------- |
  | [in]       | task       | 任务结构体描述符 |
  | [out]      | depth      | 任务栈的吃水深度 |

- **返回值**

  K_ERR_NONE 任务栈状态正常。

  K_ERR_TASK_STK_OVERFLOW 任务栈溢出。

### tos_task_curr_task_get

```c
k_task_t *tos_task_curr_task_get(void);
```

- **功能描述**

  获取当前正在运行的任务句柄。

- **参数解释**

  无

- **返回值**

  K_NULL 当前无正在运行任务（内核尚未启动）。

  非 K_NULL 任务句柄。

### tos_task_walkthru

```c
void tos_task_walkthru(k_task_walker walker);
```

- **功能描述**

  遍历当前系统已创建的（不包括已删除的）任务，并允许用户传入一个回调，在遍历所有任务时，将任务句柄作为参数调用此回调。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**                                                            |
  | ---------- | ---------- | ------------------------------------------------------------------- |
  | [in]       | walker     | 遍历所有任务时被调用的回调（walker 为一个入参为 k_task_t \*的函数） |

- **返回值**

  无

  非 K_NULL 任务句柄。

## 堆内存管理

### tos_mmheap_pool_add

```c
 k_err_t tos_mmheap_pool_add(void *pool_start, size_t pool_size);
```

- **功能描述**

  向堆内存中添加内存池。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**             |
  | ---------- | ---------- | -------------------- |
  | [in]       | pool_start | 待添加内存池起始地址 |
  | [in]       | pool_size  | 待添加内存池大小     |

- **返回值**

  K_ERR_NONE 添加成功。

  K_ERR_MMHEAP_INVALID_POOL_ADDR 内存池起始地址非法。

  K_ERR_MMHEAP_INVALID_POOL_SIZE 内存池大小非法。

### tos_mmheap_pool_rmv

```c
 k_err_t tos_mmheap_pool_rmv(void *pool_start);
```

- **功能描述**

  从堆内存中删除内存池。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**               |
  | ---------- | ---------- | ---------------------- |
  | [in]       | pool_start | 待删除的内存池起始地址 |

- **返回值**

  无

### tos_mmheap_alloc

```c
void *tos_mmheap_alloc(size_t size);
```

- **功能描述**

  从堆内存中分配一块内存。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**           |
  | ---------- | ---------- | ------------------ |
  | [in]       | size       | 期望分配的内存大小 |

- **返回值**

  分配到的内存起始地址（返回 K_NULL 表示分配失败）。

### tos_mmheap_aligned_alloc

```c
void *tos_mmheap_aligned_alloc(size_t size, size_t align);
```

- **功能描述**

  从堆内存中分配一块内存，此内存起始地址按 align 参数对齐。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**           |
  | ---------- | ---------- | ------------------ |
  | [in]       | size       | 期望分配的内存大小 |
  | [in]       | align      | 对齐参数           |

- **返回值**

  分配到的内存起始地址（返回 K_NULL 表示分配失败）。

### tos_mmheap_realloc

```c
void *tos_mmheap_realloc(void *ptr, size_t size);
```

- **功能描述**

  从堆内存中重新分配一块内存。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**               |
  | ---------- | ---------- | ---------------------- |
  | [in]       | ptr        | 原内存起始地址         |
  | [in]       | size       | 期望重新分配的内存大小 |

- **返回值**

  分配到的内存起始地址（返回 K_NULL 表示分配失败）。

### tos_mmheap_free

```c
void *tos_mmheap_free(void *ptr);
```

- **功能描述**

  释放一片从堆内存中分配到的内存。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**             |
  | ---------- | ---------- | -------------------- |
  | [in]       | ptr        | 待释放的内存起始地址 |

- **返回值**

  无。

### tos_mmheap_pool_check

```c
k_err_t tos_mmheap_pool_check(void *pool_start, k_mmheap_info_t *info);
```

- **功能描述**

  获取堆内存中某个池的使用情况。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**                             |
  | ---------- | ---------- | ------------------------------------ |
  | [in]       | pool_start | 堆内存中某个池的起始地址             |
  | [out]      | info       | 该池的使用情况（使用量和剩余量信息） |

- **返回值**

  K_ERR_NONE 函数返回成功。

  K_ERR_OBJ_PTR_NULL pool_start 或 info 为空指针。

### tos_mmheap_check

```c
k_err_t tos_mmheap_check(k_mmheap_info_t *info);
```

- **功能描述**

  获取堆内存的整体使用情况（包含了所有的池的信息）。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**                                   |
  | ---------- | ---------- | ------------------------------------------ |
  | [out]      | info       | 堆内存的整体使用情况（使用量和剩余量信息） |

- **返回值**

  K_ERR_NONE 函数返回成功。

  K_ERR_OBJ_PTR_NULL info 为空指针。

## 块内存管理

### tos_mmblk_pool_create

```c
k_err_t tos_mmblk_pool_create(k_mmblk_pool_t *mbp, void *pool_start, size_t blk_num, size_t blk_size);
```

- **功能描述**

  创建一个块内存池。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**           |
  | ---------- | ---------- | ------------------ |
  | [in]       | mbp        | 待创建的块内存句柄 |
  | [in]       | pool_start | 块内存池起始地址   |
  | [in]       | blk_num    | 内存块数量         |
  | [in]       | blk_size   | 单个内存块大小     |

- **返回值**

  K_ERR_NONE 块内存创建成功。

  K_ERR_MMBLK_INVALID_POOL_ADDR 块内存池起始地址非法。

  K_ERR_MMBLK_INVALID_BLK_SIZE 块内存大小非法。

### tos_mmblk_alloc

```c
k_err_t tos_mmblk_alloc(k_mmblk_pool_t *mbp, void **blk);
```

- **功能描述**

  从内存池中分配一个内存块。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**             |
  | ---------- | ---------- | -------------------- |
  | [in]       | mbp        | 块内存句柄           |
  | [out]      | blk        | 返回的块内存起始地址 |

- **返回值**

  K_ERR_NONE 块内存分配成功，blk 指向分配到的内存块起始地址。

  K_ERR_MMBLK_POOL_EMPTY 内存池是空的，blk 为 K_NULL。

### tos_mmblk_free

```c
k_err_t tos_mmblk_free(k_mmblk_pool_t *mbp, void *blk);
```

- **功能描述**

  释放一个内存块。

- **参数解释**

  | **IN/OUT** | **参数名** | **描述**               |
  | ---------- | ---------- | ---------------------- |
  | [in]       | mbp        | 块内存句柄             |
  | [in]       | blk        | 待释放的块内存起始地址 |

- **返回值**

  K_ERR_NONE 块内存释放成功。

  K_ERR_MMBLK_POOL_FULL 内存池是满的。

## 互斥量 mutex

### tos_mutex_create

```c
k_err_t tos_mutex_create(k_mutex_t *mutex);
```

- **功能描述**

  创建一个互斥量。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | mutex  | 互斥量句柄 |

- **返回值**

  K_ERR_NONE 互斥量创建成功。

  K_ERR_OBJ_PTR_NULL mutex 为空指针。

### tos_mutex_destroy

```c
k_err_t tos_mutex_destroy(k_mutex_t *mutex);
```

- **功能描述**

  销毁一个互斥量。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | mutex  | 互斥量句柄 |

- **返回值**

  K_ERR_NONE 互斥量销毁成功。

  K_ERR_OBJ_PTR_NULL mutex 为空指针。

  K_ERR_OBJ_INVALID mutex 指向的不是一个合法的互斥量。

### tos_mutex_pend

```c
k_err_t tos_mutex_pend(k_mutex_t *mutex);
```

- **功能描述**

  尝试获取一个互斥量（永久阻塞式等待）。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | mutex  | 互斥量句柄 |

- **返回值**

  K_ERR_NONE 获取互斥量成功。

  K_ERR_MUTEX_NESTING_OVERFLOW 互斥量拥有者嵌套获取溢出。

  K_ERR_MUTEX_NESTING 互斥量拥有者嵌套获取。

  K_ERR_PEND_SCHED_LOCKED 此互斥量被其他任务持有，且系统调度处于锁定状态。

  K_ERR_PEND_DESTROY 当前任务试图获取的互斥量被销毁（tos_mutex_destroy）了。

### tos_mutex_pend_timed

```c
k_err_t tos_mutex_pend(k_mutex_t *mutex, k_tick_t timeout);
```

- **功能描述**

  尝试获取一个互斥量（有限时间内的阻塞等待）。

- **参数解释**

  | IN/OUT | 参数名  | 描述         |
  | ------ | ------- | ------------ |
  | [in]   | mutex   | 互斥量句柄   |
  | [in]   | timeout | 等待超时参数 |

- **返回值**

  K_ERR_NONE 获取互斥量成功。

  K_ERR_MUTEX_NESTING_OVERFLOW 互斥量拥有者嵌套获取溢出。

  K_ERR_MUTEX_NESTING 互斥量拥有者嵌套获取。

  K_ERR_PEND_NOWAIT 此互斥量被其他任务持有，同时 timeout 参数为 TOS_TIME_NOWAIT（表示获取不到互斥量时立即返回）

  K_ERR_PEND_SCHED_LOCKED 此互斥量被其他任务持有（获取失败），且系统调度处于锁定状态。

  K_ERR_PEND_TIMEOUT 在 timeout 时间范围内未获取到互斥量。

  K_ERR_PEND_DESTROY 当前任务试图获取的互斥量被销毁（tos_mutex_destroy）了。

### tos_mutex_post

```c
k_err_t tos_mutex_post(k_mutex_t *mutex);
```

- **功能描述**

  释放互斥量。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | mutex  | 互斥量句柄 |

- **返回值**

  K_ERR_NONE 互斥量释放成功。

  K_ERR_MUTEX_NOT_OWNER 当前任务并非此互斥量的拥有者。

  K_ERR_MUTEX_NESTING_OVERFLOW 互斥量拥有者嵌套释放溢出。

  K_ERR_MUTEX_NESTING 互斥量拥有者嵌套释放。

## 信号量 semaphore

### tos_sem_create

```c
k_err_t tos_sem_create(k_sem_t *sem, k_sem_cnt_t init_count);
```

- **功能描述**

  创建一个信号量。

- **参数解释**

  | IN/OUT | 参数名     | 描述         |
  | ------ | ---------- | ------------ |
  | [in]   | sem        | 信号量句柄   |
  | [in]   | init_count | 信号量初始量 |

- **返回值**

  K_ERR_NONE 信号量创建成功。

  K_ERR_OBJ_PTR_NULL sem 指针为空。

### tos_sem_create_max

```c
k_err_t tos_sem_create_max(k_sem_t *sem, k_sem_cnt_t init_count, k_sem_cnt_t max_count);
```

- **功能描述**

  创建一个信号量并指定信号量的最大值。

- **参数解释**

  | IN/OUT | 参数名     | 描述           |
  | ------ | ---------- | -------------- |
  | [in]   | sem        | 信号量句柄     |
  | [in]   | init_count | 信号量初始量   |
  | [in]   | max_count  | 信号量的最大值 |

- **返回值**

  K_ERR_NONE 信号量创建成功。

  K_ERR_OBJ_PTR_NULL sem 指针为空。

### tos_sem_destroy

```c
k_err_t tos_sem_destroy(k_sem_t *sem);
```

- **功能描述**

  销毁一个信号量。

- **参数解释**

  | IN/OUT | 参数名 | 描述               |
  | ------ | ------ | ------------------ |
  | [in]   | sem    | 信号量数据结构指针 |

- **返回值**

  K_ERR_NONE 信号量销毁成功。

  K_ERR_OBJ_INVALID sem 指向的不是一个合法的信号量。

  K_ERR_OBJ_PTR_NULL sem 指针为空。

### tos_sem_pend

```c
k_err_t tos_sem_pend(k_sem_t *sem, k_tick_t timeout);
```

- **功能描述**

  尝试获取一个信号量。

- **参数解释**

  | IN/OUT | 参数名  | 描述         |
  | ------ | ------- | ------------ |
  | [in]   | sem     | 信号量句柄   |
  | [in]   | timeout | 等待超时参数 |

- **返回值**

  K_ERR_NONE 获取信号量成功。

  K_ERR_PEND_NOWAIT 获取信号量失败（信号量资源不足），同时 timeout 参数为 TOS_TIME_NOWAIT（表示获取不到信号量时立即返回）

  K_ERR_PEND_SCHED_LOCKED 获取信号量失败，同时系统调度处于锁定状态。

  K_ERR_PEND_TIMEOUT 在 timeout 超时范围内未获取到信号量。

  K_ERR_PEND_DESTROY 试图获取的信号量被销毁了（tos_sem_destroy）

### tos_sem_post

```c
k_err_t tos_sem_post(k_sem_t *sem);
```

- **功能描述**

  释放信号量，并唤醒等待队列上的一个任务。如果有多个任务在此信号量的等待队列上，唤醒优先级最高的任务。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | sem    | 信号量句柄 |

- **返回值**

  K_ERR_NONE 信号量释放成功。

  K_ERR_SEM_OVERFLOW 信号量值溢出。

### tos_sem_post_all

```c
k_err_t tos_sem_post_all(k_sem_t *sem);
```

- **功能描述**

  释放信号量，并唤醒等待队列上的所有任务。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | sem    | 信号量句柄 |

- **返回值**

  K_ERR_NONE 信号量释放成功。

  K_ERR_SEM_OVERFLOW 信号量值溢出。

## 事件 event

### tos_event_create

```c
k_err_t tos_event_create(k_event_t *event, k_event_flag_t init_flag);
```

- **功能描述**

  创建一个事件。

- **参数解释**

  | IN/OUT | 参数名    | 描述         |
  | ------ | --------- | ------------ |
  | [in]   | event     | 事件句柄     |
  | [in]   | init_flag | 事件初始旗标 |

- **返回值**

  K_ERR_NONE 事件创建成功。

  K_ERR_OBJ_PTR_NULL event 指针为空。

### tos_event_destroy

```c
k_err_t tos_event_destroy(k_event_t *event);
```

- **功能描述**

  销毁一个事件。

- **参数解释**

  | IN/OUT | 参数名 | 描述     |
  | ------ | ------ | -------- |
  | [in]   | event  | 事件句柄 |

- **返回值**

  K_ERR_NONE 事件销毁成功。

  K_ERR_OBJ_PTR_NULL event 指针为空。

  K_ERR_OBJ_INVALID event 指向的不是一个合法的事件。

### tos_event_pend

```c
k_err_t tos_event_pend(k_event_t *event, k_event_flag_t flag_expect, k_event_flag_t *flag_match, k_tick_t timeout, k_opt_t opt);
```

- **功能描述**

  尝试获取一个特定的事件。

- **参数解释**

  | IN/OUT | 参数名      | 描述                 |
  | ------ | ----------- | -------------------- |
  | [in]   | event       | 事件句柄             |
  | [in]   | flag_expect | 期望获取到的事件旗标 |
  | [out]  | flag_match  | 实际获取到的事件旗标 |
  | [in]   | timeout     | 等待超时参数         |
  | [in]   | opt         | 选项                 |

- **注意**

  opt 选项说明：

  1、TOS_OPT_EVENT_PEND_ANY

  尝试从事件中获取一组旗标，并且这一组旗标包含 flag_expect 中标识的任意一个旗标，如果在此场景下视作 event 获取成功，则 opt 传递此参数。

  举例来说，如果传入的 flag_expect 为 0x9（0x8 | 0x1），且 opt 为 TOS_OPT_EVENT_PEND_ANY，则 event 包含的旗标包含 0x8 或者 0x1 即视为事件获取成功，也就是说，event 包含的旗标为 (0x8 | X, X 为整数，且 X∈(0, 0xFFFFFFFF])，或者 (0x1 | X, X 为整数，且 X∈(0, 0xFFFFFFFF])。

  2、TOS_OPT_EVENT_PEND_ALL

  尝试从事件中获取一组旗标，并且这一组旗标必须至少包含 flag_expect 中标识的所有旗标，如果只在此种场景下视作 event 获取成功，则 opt 传递此参数。

  举例来说，如果传入的 flag_expect 为 0x9（0x8 | 0x1），且 opt 为 TOS_OPT_EVENT_PEND_ALL，则 event 包含的旗标至少为 0x9 的最小全集才视为事件获取成功，也就是说，event 包含的旗标应为 (0x9 | X, X 为整数，且 X∈(0, 0xFFFFFFFF])。

  3、TOS_OPT_EVENT_PEND_CLR

  如果希望读取完事件后，直接复位清空 event 的所有旗标，则 opt 传递此参数。

  举例来说，原 event 包含旗标为 0x9，在传递 TOS_OPT_EVENT_PEND_CLR 参数并成功获取 event 中的旗标后，event 包含的旗标会复位为 0x0。

  如果希望一次传入多个选项，可以用逻辑“或”将多个参数连接传入，譬如同时希望采用 TOS_OPT_EVENT_PEND_ANY 语义及 TOS_OPT_EVENT_PEND_CLR，可以传入（TOS_OPT_EVENT_PEND_ANY | TOS_OPT_EVENT_PEND_CLR）。

  需要注意的是，不可以同时传入 TOS_OPT_EVENT_PEND_ANY 与 TOS_OPT_EVENT_PEND_ALL。

- **返回值**

  K_ERR_NONE 读取特定的事件成功。

  K_ERR_EVENT_PEND_OPT_INVALID opt 参数非法。

  K_ERR_PEND_NOWAIT 未能从 event 中获取到期望的旗标，并且 timeout 参数为 TOS_TIME_NOWAIT（表示未获取到期望旗标时立即返回）。

  K_ERR_PEND_SCHED_LOCKED 未能从 event 中获取到期望的旗标，并且系统调度处于锁定的状态。

  K_ERR_PEND_TIMEOUT 在超时范围内未能从 event 中获取到期望的旗标。

  K_ERR_PEND_DESTROY 尝试获取旗标的事件被销毁了（tos_event_destroy）。

### tos_event_post

```c
k_err_t tos_event_post(k_event_t *event, k_event_flag_t flag);
```

- **功能描述**

  向事件中放置一组旗标

- **参数解释**

  | IN/OUT | 参数名 | 描述         |
  | ------ | ------ | ------------ |
  | [in]   | event  | 事件句柄     |
  | [in]   | flag   | 要放置的旗标 |

- **注意**

  调用此接口放置一组旗标时，原 event 中包含的旗标将被覆盖。

  举例来说，如果原事件的旗标为 0x1，并且要放置的旗标为 0x8，此接口调用结束后，事件的旗标将被覆写为 0x8。

- **返回值**

  K_ERR_NONE 旗标放置成功。

  K_ERR_OBJ_PTR_NULL event 为空指针。

  K_ERR_OBJ_INVALID event 指向的并不是一个合法的事件。

### tos_event_post_keep

```c
k_err_t tos_event_post_keep(k_event_t *event, k_event_flag_t flag);
```

- **功能描述**

  向事件中放置一组旗标，原 event 中包含的旗标将被保留。

  举例来说，如果原事件的旗标为 0x1，并且要放置的旗标为 0x8，此接口调用结束后，事件的旗标将被修改为 0x9(0x8 | 0x1)，也就是说，原事件的包含的旗标被保留。

- **参数解释**

  | IN/OUT | 参数名 | 描述         |
  | ------ | ------ | ------------ |
  | [in]   | event  | 事件句柄     |
  | [in]   | flag   | 要放置的旗标 |

- **返回值**

  K_ERR_NONE 旗标放置成功。

  K_ERR_OBJ_PTR_NULL event 为空指针。

  K_ERR_OBJ_INVALID event 指向的并不是一个合法的事件。

## 完成量 completion

### tos_completion_create

```c
k_err_t tos_completion_create(k_completion_t *completion);
```

- **功能描述**

  创建一个完成量。

- **参数解释**

  | IN/OUT | 参数名     | 描述       |
  | ------ | ---------- | ---------- |
  | [in]   | completion | 完成量句柄 |

- **返回值**

  K_ERR_NONE 完成量创建成功。

  K_ERR_OBJ_PTR_NULL completion 指针为空。

### tos_completion_destroy

```c
k_err_t tos_completion_destroy(k_completion_t *completion);
```

- **功能描述**

  销毁一个完成量。

- **参数解释**

  | IN/OUT | 参数名     | 描述       |
  | ------ | ---------- | ---------- |
  | [in]   | completion | 完成量句柄 |

- **返回值**

  K_ERR_NONE 完成量销毁成功。

  K_ERR_OBJ_PTR_NULL completion 指针为空。

  K_ERR_OBJ_INVALID completion 指向的不是一个合法的完成量。

### tos_completion_pend

```c
k_err_t tos_completion_pend(k_completion_t *completion);
```

- **功能描述**

  等待完成量完成（永久阻塞等待）。

- **参数解释**

  | IN/OUT | 参数名     | 描述       |
  | ------ | ---------- | ---------- |
  | [in]   | completion | 完成量句柄 |

- **返回值**

  K_ERR_NONE 完成量已完成。

  K_ERR_PEND_SCHED_LOCKED 完成量没有完成，并且系统调度锁处于锁定状态。

  K_ERR_PEND_DESTROY 尝试等待的完成量被删除了。

### tos_completion_pend_timed

```c
k_err_t tos_completion_pend_timed(k_completion_t *completion, k_tick_t timeout);
```

- **功能描述**

  尝试等待完成量完成（有限时间内的阻塞等待）。

- **参数解释**

  | IN/OUT | 参数名     | 描述         |
  | ------ | ---------- | ------------ |
  | [in]   | completion | 完成量句柄   |
  | [in]   | timeout    | 等待超时参数 |

- **返回值**

  K_ERR_NONE 完成量已完成。

  K_ERR_PEND_NOWAIT 此完成量尚未完成，同时 timeout 参数为 TOS_TIME_NOWAIT（表示完成量未完成时立即返回）

  K_ERR_PEND_SCHED_LOCKED 完成量没有完成，并且系统调度锁处于锁定状态。

  K_ERR_PEND_DESTROY 尝试等待的完成量被删除了。

  K_ERR_PEND_TIMEOUT 在 timeout 时间范围内完成量未完成。

### tos_completion_post

```c
k_err_t tos_completion_post(k_completion_t *completion);
```

- **功能描述**

  释放完成量（此完成量状态变为已完成），并唤醒等待队列上的一个任务。如果有多个任务在此完成量的等待队列上，唤醒优先级最高的任务。

- **参数解释**

  | IN/OUT | 参数名     | 描述       |
  | ------ | ---------- | ---------- |
  | [in]   | completion | 完成量句柄 |

- **返回值**

  K_ERR_NONE 完成量释放成功。

### tos_completion_post_all

```c
k_err_t tos_completion_post_all(k_completion_t *completion);
```

- **功能描述**

  释放完成量（此完成量状态变为已完成），并唤醒等待队列上的所有任务。

- **参数解释**

  | IN/OUT | 参数名     | 描述       |
  | ------ | ---------- | ---------- |
  | [in]   | completion | 完成量句柄 |

- **返回值**

  K_ERR_NONE 完成量释放成功。

### tos_completion_reset

```c
k_err_t tos_completion_reset(k_completion_t *completion);
```

- **功能描述**

  复位完成量（将此完成量状态更改为未完成）。

- **参数解释**

  | IN/OUT | 参数名     | 描述       |
  | ------ | ---------- | ---------- |
  | [in]   | completion | 完成量句柄 |

- **返回值**

  K_ERR_NONE 完成量复位成功。

### tos_completion_is_done

```c
k_err_t tos_completion_is_done(k_completion_t *completion);
```

- **功能描述**

  判断此完成量是否已完成。

- **参数解释**

  | IN/OUT | 参数名     | 描述       |
  | ------ | ---------- | ---------- |
  | [in]   | completion | 完成量句柄 |

- **返回值**

  K_TRUE 完成量已完成。

  K_FALSE 完成量未完成。

## 计数锁 countdown latch

### tos_countdownlatch_create

```c
k_err_t tos_countdownlatch_create(k_countdownlatch_t *countdownlatch, k_countdownlatch_cnt_t count);
```

- **功能描述**

  创建一个计数锁。

- **参数解释**

  | IN/OUT | 参数名         | 描述             |
  | ------ | -------------- | ---------------- |
  | [in]   | countdownlatch | 计数锁句柄       |
  | [in]   | count          | 期望等待的计数值 |

- **返回值**

  K_ERR_NONE 计数锁创建成功。

  K_ERR_OBJ_PTR_NULL countdownlatch 指针为空。

### tos_countdownlatch_destroy

```c
k_err_t tos_countdownlatch_destroy(k_countdownlatch_t *countdownlatch);
```

- **功能描述**

  销毁一个计数锁。

- **参数解释**

  | IN/OUT | 参数名         | 描述       |
  | ------ | -------------- | ---------- |
  | [in]   | countdownlatch | 计数锁句柄 |

- **返回值**

  K_ERR_NONE 计数锁销毁成功。

  K_ERR_OBJ_PTR_NULL countdownlatch 指针为空。

  K_ERR_OBJ_INVALID countdownlatch 指向的不是一个合法的计数锁。

### tos_countdownlatch_pend

```c
k_err_t tos_countdownlatch_pend(k_countdownlatch_t *countdownlatch);
```

- **功能描述**

  等待计数锁完成（永久阻塞等待）。

- **参数解释**

  | IN/OUT | 参数名         | 描述       |
  | ------ | -------------- | ---------- |
  | [in]   | countdownlatch | 计数量句柄 |

- **返回值**

  K_ERR_NONE 计数锁已完成。

  K_ERR_PEND_SCHED_LOCKED 计数锁没有完成，并且系统调度锁处于锁定状态。

  K_ERR_PEND_DESTROY 尝试等待的计数锁被删除了。

### tos_countdownlatch_pend_timed

```c
k_err_t tos_countdownlatch_pend_timed(k_countdownlatch_t *countdownlatch, k_tick_t timeout);
```

- **功能描述**

  尝试等待计数锁完成（有限时间内的阻塞等待）。

- **参数解释**

  | IN/OUT | 参数名         | 描述         |
  | ------ | -------------- | ------------ |
  | [in]   | countdownlatch | 计数锁句柄   |
  | [in]   | timeout        | 等待超时参数 |

- **返回值**

  K_ERR_NONE 计数锁已完成。

  K_ERR_PEND_NOWAIT 此计数锁尚未完成，同时 timeout 参数为 TOS_TIME_NOWAIT（表示计数锁未完成时立即返回）

  K_ERR_PEND_SCHED_LOCKED 计数锁没有完成，并且系统调度锁处于锁定状态。

  K_ERR_PEND_DESTROY 尝试等待的计数锁被删除了。

  K_ERR_PEND_TIMEOUT 在 timeout 时间范围内计数锁未完成。

### tos_countdownlatch_post

```c
k_err_t tos_countdownlatch_post(k_countdownlatch_t *countdownlatch);
```

- **功能描述**

  计数锁（此计数锁的计数值减一），并唤醒等待队列上的一个任务。如果有多个任务在此计数锁的等待队列上，唤醒优先级最高的任务。

- **参数解释**

  | IN/OUT | 参数名         | 描述       |
  | ------ | -------------- | ---------- |
  | [in]   | countdownlatch | 计数锁句柄 |

- **返回值**

  K_ERR_NONE 计数锁释放成功。

### tos_countdownlatch_reset

```c
k_err_t tos_countdownlatch_reset(k_countdownlatch_t *countdownlatch, k_countdownlatch_cnt_t count);
```

- **功能描述**

  复位计数锁（将此计数锁的计数值复位为新的期望值）。

- **参数解释**

  | IN/OUT | 参数名         | 描述                 |
  | ------ | -------------- | -------------------- |
  | [in]   | countdownlatch | 计数锁句柄           |
  | [in]   | count          | 期望复位的新的计数值 |

- **返回值**

  K_ERR_NONE 计数锁复位成功。

## 栅栏 barrier

### tos_barrier_create

```c
k_err_t tos_barrier_create(k_barrier_t *barrier, k_barrier_cnt_t count);
```

- **功能描述**

  创建一个栅栏。

- **参数解释**

  | IN/OUT | 参数名  | 描述             |
  | ------ | ------- | ---------------- |
  | [in]   | barrier | 栅栏句柄         |
  | [in]   | count   | 期望等待的计数值 |

- **返回值**

  K_ERR_NONE 栅栏创建成功。

  K_ERR_OBJ_PTR_NULL barrier 指针为空。

### tos_barrier_destroy

```c
k_err_t tos_barrier_destroy(k_barrier_t *barrier);
```

- **功能描述**

  销毁一个栅栏。

- **参数解释**

  | IN/OUT | 参数名  | 描述     |
  | ------ | ------- | -------- |
  | [in]   | barrier | 栅栏句柄 |

- **返回值**

  K_ERR_NONE 栅栏销毁成功。

  K_ERR_OBJ_PTR_NULL barrier 指针为空。

  K_ERR_OBJ_INVALID barrier 指向的不是一个合法的栅栏。

### tos_barrier_pend

```c
k_err_t tos_barrier_pend(k_barrier_t *barrier);
```

- **功能描述**

  等待栅栏全部解除（永久阻塞等待）。

- **参数解释**

  | IN/OUT | 参数名  | 描述     |
  | ------ | ------- | -------- |
  | [in]   | barrier | 栅栏句柄 |

- **返回值**

  K_ERR_NONE 栅栏已完成。

  K_ERR_PEND_SCHED_LOCKED 栅栏没有完成，并且系统调度锁处于锁定状态。

  K_ERR_PEND_DESTROY 尝试等待的栅栏被删除了。

  K_ERR_BARRIER_OVERFLOW 栅栏的 pend 次数超过了初始的 count 数量。

### tos_barrier_reset

```c
k_err_t tos_barrier_reset(k_barrier_t *barrier, k_barrier_cnt_t count);
```

- **功能描述**

  复位栅栏（将栅栏的 count 计数复位）。

- **参数解释**

  | IN/OUT | 参数名  | 描述       |
  | ------ | ------- | ---------- |
  | [in]   | barrier | 栅栏句柄   |
  | [in]   | count   | 复位的计数 |

- **返回值**

  K_ERR_NONE 栅栏复位成功。

  K_ERR_OBJ_PTR_NULL barrier 指针为空。

  K_ERR_OBJ_INVALID barrier 指向的不是一个合法的栅栏。

## 读写锁 rwlock

### tos_rwlock_create

```c
k_err_t tos_rwlock_create(k_rwlock_t *rwlock);
```

- **功能描述**

  创建一个读写锁。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | rwlock | 读写锁句柄 |

- **返回值**

  K_ERR_NONE 读写锁创建成功。

  K_ERR_OBJ_PTR_NULL rwlock 指针为空。

### tos_rwlock_destroy

```c
k_err_t tos_rwlock_destroy(k_rwlock_t *rwlock);
```

- **功能描述**

  销毁一个栅栏。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | rwlock | 读写锁句柄 |

- **返回值**

  K_ERR_NONE 读写锁销毁成功。

  K_ERR_OBJ_PTR_NULL rwlock 指针为空。

  K_ERR_OBJ_INVALID rwlock 指向的不是一个合法的读写锁。

### tos_rwlock_rpend_timed

```c
k_err_t tos_rwlock_rpend_timed(k_rwlock_t *rwlock, k_tick_t timeout);
```

- **功能描述**

  有限的时间内尝试获取读锁。

- **参数解释**

  | IN/OUT | 参数名  | 描述       |
  | ------ | ------- | ---------- |
  | [in]   | rwlock  | 读写锁句柄 |
  | [in]   | timeout | 超时时限   |

- **返回值**

  K_ERR_NONE 成功获取读锁。

  K_ERR_PEND_SCHED_LOCKED 未成功获取到读锁，并且系统调度锁处于锁定状态。

  K_ERR_PEND_DESTROY 尝试等待的读锁被删除了。

  K_ERR_PEND_TIMEOUT 未在超时时限内成功获取到读锁。

  K_ERR_RWLOCK_READERS_TO_MANY 已获取读锁的读者过多。

### tos_rwlock_rpend

```c
k_err_t tos_rwlock_rpend(k_rwlock_t *rwlock);
```

- **功能描述**

  永久性阻塞尝试获取读锁。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | rwlock | 读写锁句柄 |

- **返回值**

  K_ERR_NONE 成功获取读锁。

  K_ERR_PEND_SCHED_LOCKED 在超时时限内未成功获取到读锁，并且系统调度锁处于锁定状态。

  K_ERR_PEND_DESTROY 尝试等待的读锁被删除了。

  K_ERR_RWLOCK_READERS_TO_MANY 已获取读锁的读者过多。

### tos_rwlock_rpend_try

```c
k_err_t tos_rwlock_rpend_try(k_rwlock_t *rwlock);
```

- **功能描述**

  尝试获取读锁，且并不阻塞等待，立即返回错误码。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | rwlock | 读写锁句柄 |

- **返回值**

  K_ERR_NONE 成功获取读锁。

  K_ERR_PEND_SCHED_LOCKED 在超时时限内未成功获取到读锁，并且系统调度锁处于锁定状态。

  K_ERR_PEND_DESTROY 尝试等待的读锁被删除了。

  K_ERR_RWLOCK_READERS_TO_MANY 已获取读锁的读者过多。

### tos_rwlock_wpend_timed

```c
k_err_t tos_rwlock_wpend_timed(k_rwlock_t *rwlock, k_tick_t timeout);
```

- **功能描述**

  有限的时间内尝试获取写锁。

- **参数解释**

  | IN/OUT | 参数名  | 描述       |
  | ------ | ------- | ---------- |
  | [in]   | rwlock  | 读写锁句柄 |
  | [in]   | timeout | 超时时限   |

- **返回值**

  K_ERR_NONE 成功获取读锁。

  K_ERR_PEND_SCHED_LOCKED 未成功获取到写锁，并且系统调度锁处于锁定状态。

  K_ERR_PEND_DESTROY 尝试等待的写锁被删除了。

  K_ERR_PEND_TIMEOUT 未在超时时限内成功获取到写锁。

  K_ERR_RWLOCK_WAITING_WRITERS_TO_MANY 尝试获取写锁的任务过多。

### tos_rwlock_wpend

```c
k_err_t tos_rwlock_wpend(k_rwlock_t *rwlock);
```

- **功能描述**

  永久性阻塞尝试获取写锁。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | rwlock | 读写锁句柄 |

- **返回值**

  K_ERR_NONE 成功获取写锁。

  K_ERR_PEND_SCHED_LOCKED 在超时时限内未成功获取到写锁，并且系统调度锁处于锁定状态。

  K_ERR_PEND_DESTROY 尝试等待的写锁被删除了。

  K_ERR_RWLOCK_WAITING_WRITERS_TO_MANY 尝试获取写锁的任务过多。

### tos_rwlock_wpend_try

```c
k_err_t tos_rwlock_wpend_try(k_rwlock_t *rwlock);
```

- **功能描述**

  尝试获取写锁，且并不阻塞等待，立即返回错误码。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | rwlock | 读写锁句柄 |

- **返回值**

  K_ERR_NONE 成功获取写锁。

  K_ERR_PEND_SCHED_LOCKED 在超时时限内未成功获取到写锁，并且系统调度锁处于锁定状态。

  K_ERR_PEND_DESTROY 尝试等待的写锁被删除了。

  K_ERR_RWLOCK_WAITING_WRITERS_TO_MANY 尝试获取写锁的任务过多。

### tos_rwlock_rpost

```c
k_err_t tos_rwlock_rpost(k_rwlock_t *rwlock);
```

- **功能描述**

  释放一个读锁。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | rwlock | 读写锁句柄 |

- **返回值**

  K_ERR_NONE 成功释放读锁。

  K_ERR_RWLOCK_NOT_READING 当前任务并非此读锁拥有者。

### tos_rwlock_wpost

```c
k_err_t tos_rwlock_wpost(k_rwlock_t *rwlock);
```

- **功能描述**

  释放一个写锁。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | rwlock | 读写锁句柄 |

- **返回值**

  K_ERR_NONE 成功释放写锁。

  K_ERR_RWLOCK_NOT_WRITTING 当前任务并非此写锁拥有者。

### tos_rwlock_post

```c
k_err_t tos_rwlock_post(k_rwlock_t *rwlock);
```

- **功能描述**

  释放一个读写锁。

  如果当前读写锁被读者持有，则释放读锁；如果是被写者持有，则释放写锁。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | rwlock | 读写锁句柄 |

- **返回值**

  K_ERR_NONE 成功释放写锁。

  K_ERR_RWLOCK_NOT_TAKEN 此读写锁并未被任何读者或写者占有。

## 消息队列 message queue

### tos_msg_q_create

```c
k_err_t tos_msg_q_create(k_msg_q_t *msg_q, void *pool, size_t msg_cnt);
```

- **功能描述**

  创建一个消息队列（消息就是指针）。消息队列是用来在任务间传递指针信息的机制。pool 由用户传入，pool 是一片大小为 (msg*cnt * sizeof(void \_)) 的内存 buffer。

- **参数解释**

  | IN/OUT | 参数名  | 描述                 |
  | ------ | ------- | -------------------- |
  | [in]   | msg_q   | 消息队列句柄         |
  | [in]   | pool    | 消息队列的 buffer 池 |
  | [in]   | msg_cnt | 消息队列的最大消息数 |

- **返回值**

  K_ERR_NONE 消息队列创建成功。

  K_ERR_OBJ_PTR_NULL msg_q 指针为空。

### tos_msg_q_create_dyn

```c
k_err_t tos_msg_q_create_dyn(k_msg_q_t *msg_q, size_t msg_cnt);
```

- **功能描述**

  动态创建一个消息队列（消息就是指针）。消息队列是用来在任务间传递指针信息的机制。内部 buffer 由动态内存分配。

- **参数解释**

  | IN/OUT | 参数名  | 描述                 |
  | ------ | ------- | -------------------- |
  | [in]   | msg_q   | 消息队列句柄         |
  | [in]   | msg_cnt | 消息队列的最大消息数 |

- **返回值**

  K_ERR_NONE 消息队列创建成功。

  K_ERR_OBJ_PTR_NULL msg_q 指针为空。

  K_ERR_OUT_OF_MEMORY 堆内存不足。

### tos_msg_q_destroy

```c
k_err_t tos_msg_q_destroy(k_msg_q_t *msg_q);
```

- **功能描述**

  销毁一个消息队列。

- **参数解释**

  | IN/OUT | 参数名 | 描述         |
  | ------ | ------ | ------------ |
  | [in]   | msg_q  | 消息队列句柄 |

- **返回值**

  K_ERR_NONE 消息队列销毁成功。

  K_ERR_OBJ_PTR_NULL msg_q 指针为空。

  K_ERR_OBJ_INVALID msg_q 指向的不是一个合法的消息队列。

### tos_msg_q_destroy_dyn

```c
k_err_t tos_msg_q_destroy_dyn(k_msg_q_t *msg_q);
```

- **功能描述**

  销毁一个动态创建的（tos_msg_q_create_dyn）消息队列。

- **参数解释**

  | IN/OUT | 参数名 | 描述         |
  | ------ | ------ | ------------ |
  | [in]   | msg_q  | 消息队列句柄 |

- **返回值**

  K_ERR_NONE 消息队列销毁成功。

  K_ERR_OBJ_PTR_NULL msg_q 指针为空。

  K_ERR_OBJ_INVALID msg_q 指向的不是一个合法的消息队列。

### tos_msg_q_flush

```c
k_err_t tos_msg_q_flush(k_msg_q_t *msg_q);
```

- **功能描述**

  冲洗消息队列（丢弃消息队列中的所有消息）。

- **参数解释**

  | IN/OUT | 参数名 | 描述         |
  | ------ | ------ | ------------ |
  | [in]   | msg_q  | 消息队列句柄 |

- **返回值**

  K_ERR_NONE 消息队列冲洗成功。

  K_ERR_OBJ_PTR_NULL msg_q 指针为空。

  K_ERR_OBJ_INVALID msg_q 指向的不是一个合法的消息队列。

### tos_msg_q_pend

```c
k_err_t tos_msg_q_pend(k_msg_q_t *msg_q, void **msg_ptr, k_tick_t timeout);
```

- **功能描述**

  尝试从消息队列中获取消息。

- **参数解释**

  | IN/OUT | 参数名  | 描述             |
  | ------ | ------- | ---------------- |
  | [in]   | msg_q   | 消息队列句柄     |
  | [out]  | msg_ptr | 获取到的消息地址 |
  | [in]   | timeout | 等待超时参数     |

- **返回值**

  K_ERR_NONE 从消息队列获取消息成功，msg_addr 和 msg_size 分别是获取到的消息地址和消息长度。

  K_ERR_PEND_NOWAIT 未能从消息队列中获取到消息，并且 timeout 参数为 TOS_TIME_NOWAIT（表示获取不到消息时立即返回）。

  K_ERR_PEND_SCHED_LOCKED 未能从消息队列中获取到消息，并且系统调度处于锁定状态。

  K_ERR_PEND_TIMEOUT 在 timeout 超时范围内未能从消息队列中获取到消息。

  K_ERR_PEND_DESTROY 尝试获取消息的队列被销毁了（tos_msg_q_destroy）。

### tos_msg_q_post

```c
k_err_t tos_msg_q_post(k_msg_q_t *msg_q, void *msg_ptr);
```

- **功能描述**

  向消息队列中放入一个消息，并唤醒等待队列上的一个任务。如果有多个任务在此消息队列的等待队列上，唤醒优先级最高的任务。

- **参数解释**

  | IN/OUT | 参数名  | 描述         |
  | ------ | ------- | ------------ |
  | [in]   | msg_q   | 消息队列句柄 |
  | [in]   | msg_ptr | 消息地址     |

- **返回值**

  K_ERR_NONE 向消息队列中放入消息成功。

  K_ERR_RING_Q_FULL 消息队列已满。

### tos_msg_q_post_all

```c
k_err_t tos_msg_q_post_all(k_msg_q_t *msg_q, void *msg_ptr);
```

- **功能描述**

  向消息队列中放入一个消息，并唤醒等待队列上的所有任务。

- **参数解释**

  | IN/OUT | 参数名  | 描述         |
  | ------ | ------- | ------------ |
  | [in]   | msg_q   | 消息队列句柄 |
  | [in]   | msg_ptr | 消息地址     |

- **返回值**

  K_ERR_NONE 向消息队列中放入消息成功。

  K_ERR_RING_Q_FULL 消息队列已满。

## 邮箱队列 mail queue

### tos_mail_q_create

```c
k_err_t tos_mail_q_create(k_mail_q_t *mail_q, void *pool, size_t mail_cnt, size_t mail_size);
```

- **功能描述**

  创建一个邮箱队列（邮件是一片固定大小的内存）。邮箱队列是用来在任务间传递具有特定大小的内存信息的机制。pool 由用户传入，pool 是一片大小为 (mail_cnt\* mail_size) 的内存 buffer。

- **参数解释**

  | IN/OUT | 参数名    | 描述                 |
  | ------ | --------- | -------------------- |
  | [in]   | mail_q    | 邮箱队列句柄         |
  | [in]   | pool      | 邮箱队列的 buffer 池 |
  | [in]   | mail_cnt  | 邮件的最大数量       |
  | [in]   | mail_size | 邮件的大小           |

- **返回值**

  K_ERR_NONE 邮箱队列创建成功。

  K_ERR_OBJ_PTR_NULL mail_q 指针为空。

### tos_mail_q_create_dyn

```c
k_err_t tos_mail_q_create_dyn(k_mail_q_t *mail_q, size_t mail_cnt, size_t mail_size);
```

- **功能描述**

  动态创建一个邮箱队列（邮件是一片固定大小的内存）。邮箱队列是用来在任务间传递具有特定大小的内存信息的机制。内部 buffer 由动态内存分配。

- **参数解释**

  | IN/OUT | 参数名    | 描述           |
  | ------ | --------- | -------------- |
  | [in]   | mail_q    | 邮箱队列句柄   |
  | [in]   | mail_cnt  | 邮件的最大数量 |
  | [in]   | mail_size | 邮件的大小     |

- **返回值**

  K_ERR_NONE 邮箱队列创建成功。

  K_ERR_OBJ_PTR_NULL mail_q 指针为空。

  K_ERR_OUT_OF_MEMORY 堆内存不足。

### tos_mail_q_destroy

```c
k_err_t tos_mail_q_destroy(k_mail_q_t *mail_q);
```

- **功能描述**

  销毁一个邮箱队列。

- **参数解释**

  | IN/OUT | 参数名 | 描述         |
  | ------ | ------ | ------------ |
  | [in]   | mail_q | 邮箱队列句柄 |

- **返回值**

  K_ERR_NONE 邮箱队列销毁成功。

  K_ERR_OBJ_PTR_NULL mail_q 指针为空。

  K_ERR_OBJ_INVALID mail_q 指向的不是一个合法的邮箱队列。

### tos_mail_q_destroy_dyn

```c
k_err_t tos_mail_q_destroy_dyn(k_mail_q_t *mail_q);
```

- **功能描述**

  销毁一个动态创建的（tos_mail_q_create_dyn）邮箱队列。

- **参数解释**

  | IN/OUT | 参数名 | 描述         |
  | ------ | ------ | ------------ |
  | [in]   | mail_q | 邮箱队列句柄 |

- **返回值**

  K_ERR_NONE 邮箱队列销毁成功。

  K_ERR_OBJ_PTR_NULL mail_q 指针为空。

  K_ERR_OBJ_INVALID mail_q 指向的不是一个合法的邮箱队列。

### tos_mail_q_flush

```c
k_err_t tos_mail_q_flush(k_mail_q_t *mail_q);
```

- **功能描述**

  冲洗邮箱队列（丢弃邮箱队列中的所有邮件）。

- **参数解释**

  | IN/OUT | 参数名 | 描述         |
  | ------ | ------ | ------------ |
  | [in]   | mail_q | 邮箱队列句柄 |

- **返回值**

  K_ERR_NONE 邮箱队列冲洗成功。

  K_ERR_OBJ_PTR_NULL mail_q 指针为空。

  K_ERR_OBJ_INVALID mail_q 指向的不是一个合法的邮箱队列。

### tos_mail_q_pend

```c
k_err_t tos_mail_q_pend(k_mail_q_t *mail_q, void *mail_buf, size_t *mail_size, k_tick_t timeout);
```

- **功能描述**

  尝试从邮箱队列中获取邮件。

- **参数解释**

  | IN/OUT | 参数名    | 描述                           |
  | ------ | --------- | ------------------------------ |
  | [in]   | mail_q    | 邮箱队列句柄                   |
  | [out]  | mail_buf  | 用来承载邮件内容的 buffer 地址 |
  | [in]   | mail_size | 获取到的邮件长度               |
  | [in]   | timeout   | 等待超时参数                   |

- **返回值**

  K_ERR_NONE 从邮箱队列获取邮件成功，mail_buf 中被写入邮件内容，msg_size 获取到的邮件长度。

  K_ERR_PEND_NOWAIT 未能从邮箱队列中获取到邮件，并且 timeout 参数为 TOS_TIME_NOWAIT（表示获取不到邮件时立即返回）。

  K_ERR_PEND_SCHED_LOCKED 未能从邮箱队列中获取到邮件，并且系统调度处于锁定状态。

  K_ERR_PEND_TIMEOUT 在 timeout 超时范围内未能从邮箱队列中获取到邮件。

  K_ERR_PEND_DESTROY 尝试获取邮件的队列被销毁了（tos_mail_q_destroy）。

### tos_mail_q_post

```c
k_err_t tos_mail_q_post(k_mail_q_t *mail_q, void *mail_buf, size_t mail_size);
```

- **功能描述**

  向邮箱队列中放入一个邮件，并唤醒等待队列上的一个任务。如果有多个任务在此邮箱队列的等待队列上，唤醒优先级最高的任务。

- **参数解释**

  | IN/OUT | 参数名    | 描述                 |
  | ------ | --------- | -------------------- |
  | [in]   | mail_q    | 邮箱队列句柄         |
  | [in]   | mail_buf  | 要放入邮箱队列的邮件 |
  | [in]   | mail_size | 邮件长度             |

- **返回值**

  K_ERR_NONE 向邮箱队列中放入邮件成功。

  K_ERR_RING_Q_FULL 邮箱队列已满。

### tos_mail_q_post_all

```c
k_err_t tos_mail_q_post_all(k_mail_q_t *mail_q, void *mail_buf, size_t mail_size);
```

- **功能描述**

  向邮箱队列中放入一个邮件，并唤醒等待队列上的所有任务。

- **参数解释**

  | IN/OUT | 参数名    | 描述                 |
  | ------ | --------- | -------------------- |
  | [in]   | mail_q    | 邮箱队列句柄         |
  | [in]   | mail_buf  | 要放入邮箱队列的邮件 |
  | [in]   | mail_size | 邮件长度             |

- **返回值**

  K_ERR_NONE 向邮箱队列中放入邮件成功。

  K_ERR_RING_Q_FULL 邮箱队列已满。

## 优先级消息队列 priority message queue

### tos_prio_msg_q_create

```c
k_err_t tos_prio_msg_q_create(k_prio_msg_q_t *prio_msg_q, void *pool, size_t msg_cnt);
```

- **功能描述**

  创建一个优先级消息队列（消息就是指针）。优先级消息队列是用来在任务间传递指针信息的机制，与消息队列不同的地方在于，优先级消息队列可以给消息赋予一个优先级，较高优先级（数值上更小）的消息会比较低优先级的消息更快传递到等待任务。pool 由用户传入，pool 是一片大小为 (msg*cnt * sizeof(void \_)) 的内存 buffer。

- **参数解释**

  | IN/OUT | 参数名     | 描述                       |
  | ------ | ---------- | -------------------------- |
  | [in]   | prio_msg_q | 优先级消息队列句柄         |
  | [in]   | pool       | 优先级消息队列的 buffer 池 |
  | [in]   | msg_cnt    | 优先级消息队列的最大消息数 |

- **返回值**

  K_ERR_NONE 优先级消息队列创建成功。

  K_ERR_OBJ_PTR_NULL prio_msg_q 指针为空。

### tos_prio_msg_q_create_dyn

```c
k_err_t tos_prio_msg_q_create_dyn(k_prio_msg_q_t *prio_msg_q, size_t msg_cnt);
```

- **功能描述**

  动态创建一个优先级消息队列（消息就是指针）。优先级消息队列是用来在任务间传递指针信息的机制，与消息队列不同的地方在于，优先级队列可以给消息赋予一个优先级，较高优先级（数值上更小）的消息会比较低优先级的消息更快传递到等待任务。内部 buffer 由动态内存分配。

- **参数解释**

  | IN/OUT | 参数名     | 描述                       |
  | ------ | ---------- | -------------------------- |
  | [in]   | prio_msg_q | 优先级消息队列句柄         |
  | [in]   | msg_cnt    | 优先级消息队列的最大消息数 |

- **返回值**

  K_ERR_NONE 优先级消息队列创建成功。

  K_ERR_OBJ_PTR_NULL prio_msg_q 指针为空。

  K_ERR_OUT_OF_MEMORY 堆内存不足。

### tos_prio_msg_q_destroy

```c
k_err_t tos_prio_msg_q_destroy(k_prio_msg_q_t *prio_msg_q);
```

- **功能描述**

  销毁一个优先级消息队列。

- **参数解释**

  | IN/OUT | 参数名     | 描述               |
  | ------ | ---------- | ------------------ |
  | [in]   | prio_msg_q | 优先级消息队列句柄 |

- **返回值**

  K_ERR_NONE 优先级消息队列销毁成功。

  K_ERR_OBJ_PTR_NULL msg_q 指针为空。

  K_ERR_OBJ_INVALID prio_msg_q 指向的不是一个合法的优先级消息队列。

### tos_prio_msg_q_destroy_dyn

```c
k_err_t tos_prio_msg_q_destroy_dyn(k_prio_msg_q_t *prio_msg_q);
```

- **功能描述**

  销毁一个动态创建的（tos_prio_msg_q_create_dyn）优先级消息队列。

- **参数解释**

  | IN/OUT | 参数名     | 描述             |
  | ------ | ---------- | ---------------- |
  | [in]   | prio_msg_q | 优先级息队列句柄 |

- **返回值**

  K_ERR_NONE 优先级消息队列销毁成功。

  K_ERR_OBJ_PTR_NULL prio_msg_q 指针为空。

  K_ERR_OBJ_INVALID prio_msg_q 指向的不是一个合法的优先级消息队列。

### tos_prio_msg_q_flush

```c
k_err_t tos_prio_msg_q_flush(k_prio_msg_q_t *prio_msg_q);
```

- **功能描述**

  冲洗 优先级消息队列（丢弃优先级消息队列中的所有消息）。

- **参数解释**

  | IN/OUT | 参数名     | 描述             |
  | ------ | ---------- | ---------------- |
  | [in]   | prio_msg_q | 优先级息队列句柄 |

- **返回值**

  K_ERR_NONE 优先级消息队列冲洗成功。

  K_ERR_OBJ_PTR_NULL prio_msg_q 指针为空。

  K_ERR_OBJ_INVALID prio_msg_q 指向的不是一个合法的优先级消息队列。

### tos_prio_msg_q_pend

```c
k_err_t tos_prio_msg_q_pend(k_prio_msg_q_t *prio_msg_q, void **msg_ptr, k_tick_t timeout);
```

- **功能描述**

  尝试从消息队列中获取消息。

- **参数解释**

  | IN/OUT | 参数名     | 描述               |
  | ------ | ---------- | ------------------ |
  | [in]   | prio_msg_q | 优先级消息队列句柄 |
  | [out]  | msg_ptr    | 获取到的消息地址   |
  | [in]   | timeout    | 等待超时参数       |

- **返回值**

  K_ERR_NONE 从优先级消息队列获取消息成功，msg_addr 和 msg_size 分别是获取到的消息地址和消息长度。

  K_ERR_PEND_NOWAIT 未能从优先级消息队列中获取到消息，并且 timeout 参数为 TOS_TIME_NOWAIT（表示获取不到消息时立即返回）。

  K_ERR_PEND_SCHED_LOCKED 未能从优先级消息队列中获取到消息，并且系统调度处于锁定状态。

  K_ERR_PEND_TIMEOUT 在 timeout 超时范围内未能从优先级消息队列中获取到消息。

  K_ERR_PEND_DESTROY 尝试获取消息的队列被销毁了（tos_prio_msg_q_destroy）。

### tos_prio_msg_q_post

```c
k_err_t tos_prio_msg_q_post(k_prio_msg_q_t *prio_msg_q, void *msg_ptr, k_prio_t prio);
```

- **功能描述**

  向优先级消息队列中放入一个消息，并唤醒等待队列上的一个任务。如果有多个任务在此优先级消息队列的等待队列上，唤醒优先级最高的任务。

- **参数解释**

  | IN/OUT | 参数名     | 描述               |
  | ------ | ---------- | ------------------ |
  | [in]   | prio_msg_q | 优先级消息队列句柄 |
  | [in]   | msg_ptr    | 消息地址           |
  | [in]   | prio       | 消息的优先级       |

- **返回值**

  K_ERR_NONE 向优先级消息队列中放入消息成功。

  K_ERR_RING_Q_FULL 优先级消息队列已满。

### tos_prio_msg_q_post_all

```c
k_err_t tos_prio_msg_q_post_all(k_prio_msg_q_t *prio_msg_q, void *msg_ptr, k_prio_t prio);
```

- **功能描述**

  向优先级消息队列中放入一个消息，并唤醒等待队列上的所有任务。

- **参数解释**

  | IN/OUT | 参数名     | 描述               |
  | ------ | ---------- | ------------------ |
  | [in]   | prio_msg_q | 优先级消息队列句柄 |
  | [in]   | msg_ptr    | 消息地址           |
  | [in]   | prio       | 消息的优先级       |

- **返回值**

  K_ERR_NONE 向优先级消息队列中放入消息成功。

  K_ERR_RING_Q_FULL 优先级消息队列已满。

## 优先级邮箱队列 priority mail queue

### tos_prio_mail_q_create

```c
k_err_t tos_prio_msg_q_create(k_prio_mail_q_t *prio_mail_q, void *pool, size_t mail_cnt, size_t mail_size);
```

- **功能描述**

  创建一个优先级邮箱队列（邮件是一片固定大小的内存）。优先级邮箱队列是用来在任务间传递具有特定大小的内存信息的机制，与邮箱队列不同的地方在于，优先级邮箱队列可以给邮件赋予一个优先级，较高优先级（数值上更小）的邮件会比较低优先级的邮件更快传递到等待任务。pool 由用户传入，pool 是一片大小为 (mail_cnt\* mail_size) 的内存 buffer。

- **参数解释**

  | IN/OUT | 参数名      | 描述                       |
  | ------ | ----------- | -------------------------- |
  | [in]   | prio_mail_q | 优先级邮箱队列句柄         |
  | [in]   | pool        | 优先级邮箱队列的 buffer 池 |
  | [in]   | mail_cnt    | 邮件的最大数量             |
  | [in]   | mail_size   | 邮件的大小                 |

- **返回值**

  K_ERR_NONE 优先级邮箱队列创建成功。

  K_ERR_OBJ_PTR_NULL prio_mail_q 指针为空。

### tos_prio_mail_q_create_dyn

```c
k_err_t tos_prio_mail_q_create_dyn(k_prio_mail_q_t *prio_mail_q, size_t mail_cnt, size_t mail_size);
```

- **功能描述**

  动态创建一个优先级邮箱队列（邮件是一片固定大小的内存）。优先级邮箱队列是用来在任务间传递具有特定大小的内存信息的机制。内部 buffer 由动态内存分配。

- **参数解释**

  | IN/OUT | 参数名      | 描述               |
  | ------ | ----------- | ------------------ |
  | [in]   | prio_mail_q | 优先级邮箱队列句柄 |
  | [in]   | mail_cnt    | 邮件的最大数量     |
  | [in]   | mail_size   | 邮件的大小         |

- **返回值**

  K_ERR_NONE 优先级邮箱队列创建成功。

  K_ERR_OBJ_PTR_NULL prio_mail_q 指针为空。

  K_ERR_OUT_OF_MEMORY 堆内存不足。

### tos_prio_mail_q_destroy

```c
k_err_t tos_prio_mail_q_destroy(k_prio_mail_q_t *prio_mail_q);
```

- **功能描述**

  销毁一个邮箱队列。

- **参数解释**

  | IN/OUT | 参数名      | 描述               |
  | ------ | ----------- | ------------------ |
  | [in]   | prio_mail_q | 优先级邮箱队列句柄 |

- **返回值**

  K_ERR_NONE 优先级邮箱队列销毁成功。

  K_ERR_OBJ_PTR_NULL prio_mail_q 指针为空。

  K_ERR_OBJ_INVALID prio_mail_q 指向的不是一个合法的邮箱队列。

### tos_prio_mail_q_destroy_dyn

```c
k_err_t tos_prio_mail_q_destroy_dyn(k_prio_mail_q_t *prio_mail_q);
```

- **功能描述**

  销毁一个动态创建的（tos_mail_q_create_dyn）优先级邮箱队列。

- **参数解释**

  | IN/OUT | 参数名      | 描述               |
  | ------ | ----------- | ------------------ |
  | [in]   | prio_mail_q | 优先级邮箱队列句柄 |

- **返回值**

  K_ERR_NONE 优先级邮箱队列销毁成功。

  K_ERR_OBJ_PTR_NULL prio_mail_q 指针为空。

  K_ERR_OBJ_INVALID prio_mail_q 指向的不是一个合法的优先级邮箱队列。

### tos_prio_mail_q_flush

```c
k_err_t tos_prio_mail_q_flush(k_prio_mail_q_t *prio_mail_q);
```

- **功能描述**

  冲洗邮箱队列（丢弃邮箱队列中的所有邮件）。

- **参数解释**

  | IN/OUT | 参数名      | 描述               |
  | ------ | ----------- | ------------------ |
  | [in]   | prio_mail_q | 优先级邮箱队列句柄 |

- **返回值**

  K_ERR_NONE 优先级邮箱队列冲洗成功。

  K_ERR_OBJ_PTR_NULL prio_mail_q 指针为空。

  K_ERR_OBJ_INVALID prio_mail_q 指向的不是一个合法的邮箱队列。

### tos_prio_mail_q_pend

```c
k_err_t tos_prio_mail_q_pend(k_prio_mail_q_t *prio_mail_q, void *mail_buf, size_t *mail_size, k_tick_t timeout);
```

- **功能描述**

  尝试从邮箱队列中获取邮件。

- **参数解释**

  | IN/OUT | 参数名      | 描述                           |
  | ------ | ----------- | ------------------------------ |
  | [in]   | prio_mail_q | 优先级邮箱队列句柄             |
  | [out]  | mail_buf    | 用来承载邮件内容的 buffer 地址 |
  | [in]   | mail_size   | 获取到的邮件长度               |
  | [in]   | timeout     | 等待超时参数                   |

- **返回值**

  K_ERR_NONE 从优先级邮箱队列获取邮件成功，mail_buf 中被写入邮件内容，msg_size 获取到的邮件长度。

  K_ERR_PEND_NOWAIT 未能从优先级邮箱队列中获取到邮件，并且 timeout 参数为 TOS_TIME_NOWAIT（表示获取不到邮件时立即返回）。

  K_ERR_PEND_SCHED_LOCKED 未能从优先级邮箱队列中获取到邮件，并且系统调度处于锁定状态。

  K_ERR_PEND_TIMEOUT 在 timeout 超时范围内未能从优先级邮箱队列中获取到邮件。

  K_ERR_PEND_DESTROY 尝试获取邮件的队列被销毁了（tos_prio_mail_q_destroy）。

### tos_prio_mail_q_post

```c
k_err_t tos_prio_mail_q_post(k_prio_mail_q_t *prio_mail_q, void *mail_buf, size_t mail_size, k_prio_t prio);
```

- **功能描述**

  向优先级邮箱队列中放入一个邮件，并唤醒等待队列上的一个任务。如果有多个任务在此优先级邮箱队列的等待队列上，唤醒优先级最高的任务。

- **参数解释**

  | IN/OUT | 参数名      | 描述                       |
  | ------ | ----------- | -------------------------- |
  | [in]   | prio_mail_q | 优先级邮箱队列句柄         |
  | [in]   | mail_buf    | 要放入优先级邮箱队列的邮件 |
  | [in]   | mail_size   | 邮件长度                   |
  | [in]   | prio        | 邮件的优先级               |

- **返回值**

  K_ERR_NONE 向优先级邮箱队列中放入邮件成功。

  K_ERR_RING_Q_FULL 优先级邮箱队列已满。

### tos_prio_mail_q_post_all

```c
k_err_t tos_prio_mail_q_post_all(k_prio_mail_q_t *prio_mail_q, void *mail_buf, size_t mail_size, k_prio_t prio);
```

- **功能描述**

  向优先级邮箱队列中放入一个邮件，并唤醒等待队列上的所有任务。

- **参数解释**

  | IN/OUT | 参数名      | 描述                       |
  | ------ | ----------- | -------------------------- |
  | [in]   | prio_mail_q | 优先级邮箱队列句柄         |
  | [in]   | mail_buf    | 要放入优先级邮箱队列的邮件 |
  | [in]   | mail_size   | 邮件长度                   |
  | [in]   | prio        | 邮件的优先级               |

- **返回值**

  K_ERR_NONE 向优先级邮箱队列中放入邮件成功。

  K_ERR_RING_Q_FULL 优先级邮箱队列已满。

## 环形队列 ring queue

### tos_ring_q_create

```c
k_err_t tos_ring_q_create(k_ring_q_t *ring_q, void *pool, size_t item_cnt, size_t item_size);
```

- **功能描述**

  创建一个环形队列。环形队列提供了一种对数据进行先入先出管理的机制，可以作为上层数据结构或算法的底层数据容器。pool 由用户传入，pool 是一片大小为 (item_cnt \* item_size) 的内存 buffer。

- **参数解释**

  | IN/OUT | 参数名    | 描述                     |
  | ------ | --------- | ------------------------ |
  | [in]   | ring_q    | 环形队列句柄             |
  | [in]   | pool      | 环形队列的 buffer 池     |
  | [in]   | item_cnt  | 环形队列管理的元素的数量 |
  | [in]   | item_size | 环形队列管理的元素的大小 |

- **返回值**

  K_ERR_NONE 环形队列创建成功。

### tos_ring_q_create_dyn

```c
k_err_t tos_ring_q_create(k_ring_q_t *ring_q, size_t item_cnt, size_t item_size);
```

- **功能描述**

  创建一个动态分配的环形队列。环形队列提供了一种对数据进行先入先出管理的机制，可以作为上层数据结构或算法的底层数据容器。内部的 pool 池由动态内存分配。

- **参数解释**

  | IN/OUT | 参数名    | 描述                     |
  | ------ | --------- | ------------------------ |
  | [in]   | ring_q    | 环形队列句柄             |
  | [in]   | item_cnt  | 环形队列管理的元素的数量 |
  | [in]   | item_size | 环形队列管理的元素的大小 |

- **返回值**

  K_ERR_NONE 环形队列创建成功。

  K_ERR_OUT_OF_MEMORY 堆内存不足。

### tos_ring_q_destroy

```c
k_err_t tos_ring_q_destroy(k_ring_q_t *ring_q);
```

- **功能描述**

  销毁一个环形队列。

- **参数解释**

  | IN/OUT | 参数名 | 描述         |
  | ------ | ------ | ------------ |
  | [in]   | ring_q | 环形队列句柄 |

- **返回值**

  K_ERR_NONE 销毁环形队列成功。

  K_ERR_OBJ_INVALID ring_q 指向的不是一个合法的环形队列。

### tos_ring_q_destroy_dyn

```c
k_err_t tos_ring_q_destroy_dyn(k_ring_q_t *ring_q);
```

- **功能描述**

  销毁一个动态创建的环形队列。

- **参数解释**

  | IN/OUT | 参数名 | 描述         |
  | ------ | ------ | ------------ |
  | [in]   | ring_q | 环形队列句柄 |

- **返回值**

  K_ERR_NONE 销毁环形队列成功。

  K_ERR_OBJ_INVALID ring_q 指向的不是一个合法的环形队列。

### tos_ring_q_enqueue

```c
k_err_t tos_ring_q_enqueue(k_ring_q_t *ring_q, void *item, size_t item_size);
```

- **功能描述**

  向环形队列中放入一个元素。

- **参数解释**

  | IN/OUT | 参数名    | 描述             |
  | ------ | --------- | ---------------- |
  | [in]   | ring_q    | 环形队列句柄     |
  | [in]   | item      | 待入队的元素地址 |
  | [in]   | item_size | 待入队的元素大小 |

- **返回值**

  K_ERR_NONE 元素入队成功。

  K_ERR_RING_Q_FULL 环形队列已满。

### tos_ring_q_dequeue

```c
k_err_t tos_ring_q_dequeue(k_ring_q_t *ring_q, void *item, size_t *item_size);
```

- **功能描述**

  从环形队列中获取一个元素。

- **参数解释**

  | IN/OUT | 参数名    | 描述                      |
  | ------ | --------- | ------------------------- |
  | [in]   | ring_q    | 环形队列句柄              |
  | [out]  | item      | 承接出队元素的内存 buffer |
  | [out]  | item_size | 出队的元素大小            |

- **返回值**

  K_ERR_NONE 元素出队成功。

  K_ERR_RING_Q_EMPTY 环形队列已空。

### tos_ring_q_flush

```c
k_err_t tos_ring_q_flush(k_ring_q_t *ring_q);
```

- **功能描述**

  冲洗环形队列（复位环形队列，丢弃环形队列中的所有元素）。

- **参数解释**

  | IN/OUT | 参数名 | 描述         |
  | ------ | ------ | ------------ |
  | [in]   | ring_q | 环形队列句柄 |

- **返回值**

  K_ERR_NONE 冲洗环形队列成功。

### tos_ring_q_is_empty

```c
k_err_t tos_ring_q_is_empty(k_ring_q_t *ring_q);
```

- **功能描述**

  判断一个环形队列是否为空。

- **参数解释**

  | IN/OUT | 参数名 | 描述         |
  | ------ | ------ | ------------ |
  | [in]   | ring_q | 环形队列句柄 |

- **返回值**

  K_TRUE 环形队列为空。

  K_FALSE 环形队列非空。

### tos_ring_q_is_full

```c
k_err_t tos_ring_q_is_full(k_ring_q_t *ring_q);
```

- **功能描述**

  判断一个环形队列是否为满。

- **参数解释**

  | IN/OUT | 参数名 | 描述         |
  | ------ | ------ | ------------ |
  | [in]   | ring_q | 环形队列句柄 |

- **返回值**

  K_TRUE 环形队列为满。

  K_FALSE 环形队列非满。

## 字符流先入先出队列 fifo

### tos_chr_fifo_create

```c
k_err_t tos_chr_fifo_create(k_chr_fifo_t *chr_fifo, uint8_t *buffer, size_t size);
```

- **功能描述**

  创建一个字符流先入先出队列。字符流先入先出队列的底层数据容器是环形队列。

- **参数解释**

  | IN/OUT | 参数名   | 描述                         |
  | ------ | -------- | ---------------------------- |
  | [in]   | chr_fifo | 字符流先入先出队列句柄       |
  | [in]   | buffer   | 字符流先入先出队列内存池     |
  | [in]   | size     | 字符流先入先出队列内存池大小 |

- **返回值**

  K_ERR_NONE 队列创建成功。

  K_ERR_OBJ_PTR_NULL fifo 是空指针。

### tos_chr_fifo_create_dyn

```c
k_err_t tos_chr_fifo_create(k_chr_fifo_t *chr_fifo, size_t fifo_size);
```

- **功能描述**

  动态创建一个字符流先入先出队列（内部 buffer 动态分配）。

- **参数解释**

  | IN/OUT | 参数名   | 描述                         |
  | ------ | -------- | ---------------------------- |
  | [in]   | chr_fifo | 字符流先入先出队列句柄       |
  | [in]   | size     | 字符流先入先出队列内存池大小 |

- **返回值**

  K_ERR_NONE 队列创建成功。

  K_ERR_OBJ_PTR_NULL chr_fifo 是空指针。

  K_ERR_OUT_OF_MEMORY 堆内存不足。

### tos_chr_fifo_destroy

```c
k_err_t tos_chr_fifo_destroy(k_chr_fifo_t *chr_fifo);
```

- **功能描述**

  销毁一个字符流先入先出队列。

- **参数解释**

  | IN/OUT | 参数名   | 描述                   |
  | ------ | -------- | ---------------------- |
  | [in]   | chr_fifo | 字符流先入先出队列句柄 |

- **返回值**

  K_ERR_NONE 队列创建成功。

  K_ERR_OBJ_PTR_NULL chr_fifo 是空指针。

  K_ERR_OBJ_INVALID chr_fifo 指向的不是一个合法的先入先出队列。

### tos_chr_fifo_destroy_dyn

```c
k_err_t tos_chr_fifo_destroy_dyn(k_chr_fifo_t *chr_fifo);
```

- **功能描述**

  销毁一个动态创建（tos_chr_fifo_create_dyn）的字符流先入先出队列。

- **参数解释**

  | IN/OUT | 参数名   | 描述                   |
  | ------ | -------- | ---------------------- |
  | [in]   | chr_fifo | 字符流先入先出队列句柄 |

- **返回值**

  K_ERR_NONE 队列创建成功。

  K_ERR_OBJ_PTR_NULL chr_fifo 是空指针。

  K_ERR_OBJ_INVALID chr_fifo 指向的不是一个合法的先入先出队列。

### tos_chr_fifo_push

```c
k_err_t tos_chr_fifo_push(k_chr_fifo_t *chr_fifo, uint8_t data);
```

- **功能描述**

  向字符流先入先出队列压入一个字符。

- **参数解释**

  | IN/OUT | 参数名   | 描述                   |
  | ------ | -------- | ---------------------- |
  | [in]   | chr_fifo | 字符流先入先出队列句柄 |
  | [in]   | data     | 压入的字符             |

- **返回值**

  K_ERR_NONE 字符压入成功。

  K_ERR_FIFO_FULL 字符流先入先出队列已满。

### tos_chr_fifo_push_stream

```c
k_err_t tos_chr_fifo_push_stream(k_chr_fifo_t *chr_fifo, uint8_t *stream, size_t size);
```

- **功能描述**

  向字符流先入先出队列压入一个字符流。

- **参数解释**

  | IN/OUT | 参数名   | 描述                   |
  | ------ | -------- | ---------------------- |
  | [in]   | chr_fifo | 字符流先入先出队列句柄 |
  | [in]   | stream   | 压入的字符流           |
  | [in]   | size     | 字符流长度             |

- **返回值**

  实际压入的字符流长度。

### tos_chr_fifo_pop

```c
k_err_t tos_chr_fifo_pop(k_chr_fifo_t *chr_fifo, uint8_t *out);
```

- **功能描述**

  从字符流先入先出队列弹出一个字符。

- **参数解释**

  | IN/OUT | 参数名   | 描述                   |
  | ------ | -------- | ---------------------- |
  | [in]   | chr_fifo | 字符流先入先出队列句柄 |
  | [out]  | out      | 弹出的字符             |

- **返回值**

  K_ERR_NONE 字符弹出成功。

  K_ERR_FIFO_EMPTY 字符流先入先出队列内存池已空。

### tos_chr_fifo_pop_stream

```c
int tos_chr_fifo_pop_stream(k_chr_fifo_t *fifo, uint8_t *buffer, size_t size);
```

- **功能描述**

  从字符流先入先出队列弹出一个字符流。

- **参数解释**

  | IN/OUT | 参数名   | 描述                   |
  | ------ | -------- | ---------------------- |
  | [in]   | chr_fifo | 字符流先入先出队列句柄 |
  | [out]  | stream   | 弹出的字符流           |
  | [in]   | size     | 字符流长度             |

- **返回值**

  实际弹出的字符流长度。

### tos_chr_fifo_flush

```c
void tos_chr_fifo_flush(k_chr_fifo_t *chr_fifo);
```

- **功能描述**

  冲洗字符流先入先出队列。

- **参数解释**

  | IN/OUT | 参数名   | 描述                   |
  | ------ | -------- | ---------------------- |
  | [in]   | chr_fifo | 字符流先入先出队列句柄 |

- **返回值**

  无

### tos_chr_fifo_is_empty

```c
int tos_chr_fifo_is_empty(k_chr_fifo_t *chr_fifo);
```

- **功能描述**

  判断字符流先入先出队列是否为空。

- **参数解释**

  | IN/OUT | 参数名   | 描述                   |
  | ------ | -------- | ---------------------- |
  | [in]   | chr_fifo | 字符流先入先出队列句柄 |

- **返回值**

  0，fifo 不为空。

  非 0 值，fifo 为空。

### tos_chr_fifo_is_full

```c
int tos_chr_fifo_is_full(k_chr_fifo_t *chr_fifo);
```

- **功能描述**

  判断字符流先入先出队列是否为满。

- **参数解释**

  | IN/OUT | 参数名   | 描述                   |
  | ------ | -------- | ---------------------- |
  | [in]   | chr_fifo | 字符流先入先出队列句柄 |

- **返回值**

  0，fifo 不为满。

  非 0 值，fifo 为满。

## 二项堆 binary heap

### tos_bin_heap_create

```c
k_err_t tos_bin_heap_create(k_bin_heap_t *bin_heap, void *pool, size_t item_cnt, size_t item_size, k_bin_heap_cmp cmp);
```

- **功能描述**

  创建一个二项堆。二项堆是实现优先级队列的底层数据结构。pool 由用户传入，pool 是一片大小为 (item_cnt \* item_size) 的内存 buffer，cmp 是比较两个元素大小的比较函数。

- **参数解释**

  | IN/OUT | 参数名    | 描述                         |
  | ------ | --------- | ---------------------------- |
  | [in]   | bin_heap  | 二项堆句柄                   |
  | [in]   | pool      | 二项堆的 buffer 池           |
  | [in]   | item_cnt  | 二项堆管理的元素的数量       |
  | [in]   | item_size | 二项堆管理的元素的大小       |
  | [in]   | cmp       | 比较两个二项堆元素大小的接口 |

- **返回值**

  K_ERR_NONE 二项堆创建成功。

### tos_bin_heap_create_dyn

```c
k_err_t tos_bin_heap_create_dyn(k_bin_heap_t *bin_heap, size_t item_cnt, size_t item_size, k_bin_heap_cmp cmp);
```

- **功能描述**

  动态创建一个二项堆。内部的 pool 池由动态内存分配。

- **参数解释**

  | IN/OUT | 参数名    | 描述                         |
  | ------ | --------- | ---------------------------- |
  | [in]   | bin_heap  | 环形队列句柄                 |
  | [in]   | item_cnt  | 此环形队列管理的元素的数量   |
  | [in]   | item_size | 从环形队列管理的元素的大小   |
  | [in]   | cmp       | 比较两个二项堆元素大小的接口 |

- **返回值**

  K_ERR_NONE 二项堆创建成功。

  K_ERR_OUT_OF_MEMORY 堆内存不足。

### tos_bin_heap_destroy

```c
k_err_t tos_bin_heap_destroy(k_bin_heap_t *bin_heap);
```

- **功能描述**

  销毁一个二项堆。

- **参数解释**

  | IN/OUT | 参数名   | 描述       |
  | ------ | -------- | ---------- |
  | [in]   | bin_heap | 二项堆句柄 |

- **返回值**

  K_ERR_NONE 销毁二项堆成功。

  K_ERR_OBJ_INVALID bin_heap 指向的不是一个合法的二项堆。

### tos_bin_heap_destroy_dyn

```c
k_err_t tos_bin_heap_destroy_dyn(k_bin_heap_t *bin_heap);
```

- **功能描述**

  销毁一个动态创建的二项堆。

- **参数解释**

  | IN/OUT | 参数名   | 描述       |
  | ------ | -------- | ---------- |
  | [in]   | bin_heap | 二项堆句柄 |

- **返回值**

  K_ERR_NONE 销毁二项堆成功。

  K_ERR_OBJ_INVALID bin_heap 指向的不是一个合法的二项堆。

### tos_bin_heap_push

```c
k_err_t tos_bin_heap_push(k_bin_heap_t *bin_heap, void *item, size_t item_size);
```

- **功能描述**

  向二项堆中放入一个元素。

- **参数解释**

  | IN/OUT | 参数名    | 描述             |
  | ------ | --------- | ---------------- |
  | [in]   | bin_heap  | 二项堆句柄       |
  | [out]  | item      | 待入堆的元素地址 |
  | [out]  | item_size | 待入堆的元素大小 |

- **返回值**

  K_ERR_NONE 元素入堆成功。

  K_ERR_BIN_HEAP_FULL 二项堆已满。

### tos_bin_heap_pop

```c
k_err_t tos_bin_heap_pop(k_bin_heap_t *bin_heap, void *item, size_t *item_size);
```

- **功能描述**

  从二项堆中获取一个元素。

- **参数解释**

  | IN/OUT | 参数名    | 描述                      |
  | ------ | --------- | ------------------------- |
  | [in]   | bin_heap  | 二项堆句柄                |
  | [out]  | item      | 承接出堆元素的内存 buffer |
  | [out]  | item_size | 出堆的元素大小            |

- **返回值**

  K_ERR_NONE 元素出堆成功。

  K_ERR_BIN_HEAP_EMPTY 二项堆已空。

### tos_bin_heap_flush

```c
k_err_t tos_bin_heap_flush(k_bin_heap_t *bin_heap);
```

- **功能描述**

  冲洗二项堆（复位二项堆，丢弃二项堆中的所有元素）。

- **参数解释**

  | IN/OUT | 参数名   | 描述       |
  | ------ | -------- | ---------- |
  | [in]   | bin_heap | 二项堆句柄 |

- **返回值**

  K_ERR_NONE 冲洗二项堆成功。

### tos_bin_heap_is_empty

```c
int tos_bin_heap_is_empty(k_bin_heap_t *bin_heap);
```

- **功能描述**

  判断一个二项堆是否为空。

- **参数解释**

  | IN/OUT | 参数名   | 描述       |
  | ------ | -------- | ---------- |
  | [in]   | bin_heap | 二项堆句柄 |

- **返回值**

  K_TRUE 二项堆为空。

  K_FALSE 二项堆非空。

### tos_bin_heap_is_full

```c
int tos_bin_heap_is_full(k_bin_heap_t *bin_heap);
```

- **功能描述**

  判断一个二项堆是否为满。

- **参数解释**

  | IN/OUT | 参数名   | 描述       |
  | ------ | -------- | ---------- |
  | [in]   | bin_heap | 二项堆句柄 |

- **返回值**

  K_TRUE 二项堆为满。

  K_FALSE 二项堆非满。

## 优先级队列 priority queue

### tos_prio_q_create

```c
k_err_t tos_prio_q_create(k_prio_q_t *prio_q, void *mgr_array, void *pool, size_t item_cnt, size_t item_size);
```

- **功能描述**

  创建一个优先级队列。优先级提供了一种对数据进行基于优先级管理的机制，每次出队的总是队列中优先级最高的元素，可以作为上层数据结构或算法的底层数据容器。pool 由用户传入，pool 是一片大小为 (item_cnt \* item_size) 的内存 buffer，mgr_array 也是由用户传入，是一片大小为 TOS_PRIO_Q_MGR_ARRAY_SIZE(item_cnt) 的内存 buffer。

- **参数解释**

  | IN/OUT | 参数名    | 描述                       |
  | ------ | --------- | -------------------------- |
  | [in]   | prio_q    | 优先级队列句柄             |
  | [in]   | mgr_array | 优先级队列的内部管理数据池 |
  | [in]   | pool      | 优先级队列的 buffer 池     |
  | [in]   | item_cnt  | 优先级队列管理的元素的数量 |
  | [in]   | item_size | 优先级队列管理的元素的大小 |

- **返回值**

  K_ERR_NONE 优先级队列创建成功。

### tos_prio_q_create_dyn

```c
k_err_t tos_prio_q_create_dyn(k_prio_q_t *prio_q, size_t item_cnt, size_t item_size);
```

- **功能描述**

  创建一个动态分配的优先级队列。优先级提供了一种对数据进行基于优先级管理的机制，每次出队的总是队列中优先级最高的元素，可以作为上层数据结构或算法的底层数据容器。内部的 pool 池及管理数据池由动态内存分配。

- **参数解释**

  | IN/OUT | 参数名    | 描述                       |
  | ------ | --------- | -------------------------- |
  | [in]   | prio_q    | 优先级队列句柄             |
  | [in]   | item_cnt  | 优先级队列管理的元素的数量 |
  | [in]   | item_size | 优先级队列管理的元素的大小 |

- **返回值**

  K_ERR_NONE 优先级队列创建成功。

  K_ERR_OUT_OF_MEMORY 堆内存不足。

### tos_prio_q_destroy

```c
k_err_t tos_prio_q_destroy(k_prio_q_t *prio_q);
```

- **功能描述**

  销毁一个优先级队列。

- **参数解释**

  | IN/OUT | 参数名 | 描述           |
  | ------ | ------ | -------------- |
  | [in]   | prio_q | 优先级队列句柄 |

- **返回值**

  K_ERR_NONE 销毁优先级队列成功。

  K_ERR_OBJ_INVALID prio_q 指向的不是一个合法的优先级队列。

### tos_prio_q_destroy_dyn

```c
k_err_t tos_prio_q_destroy_dyn(k_prio_q_t *prio_q);
```

- **功能描述**

  销毁一个动态创建的优先级队列。

- **参数解释**

  | IN/OUT | 参数名 | 描述           |
  | ------ | ------ | -------------- |
  | [in]   | prio_q | 优先级队列句柄 |

- **返回值**

  K_ERR_NONE 销毁优先级队列成功。

  K_ERR_OBJ_INVALID prio_q 指向的不是一个合法的优先级队列。

### tos_prio_q_enqueue

```c
k_err_t tos_prio_q_enqueue(k_prio_q_t *prio_q, void *item, size_t item_size, k_prio_t prio);
```

- **功能描述**

  向优先级队列中放入一个元素。

- **参数解释**

  | IN/OUT | 参数名    | 描述             |
  | ------ | --------- | ---------------- |
  | [in]   | prio_q    | 优先级队列句柄   |
  | [in]   | item      | 待入队的元素地址 |
  | [in]   | item_size | 待入队的元素大小 |
  | [in]   | prio      | 入队元素的优先级 |

- **返回值**

  K_ERR_NONE 元素入队成功。

  K_ERR_PRIO_Q_FULL 优先级队列已满。

### tos_prio_q_dequeue

```c
k_err_t tos_prio_q_dequeue(k_prio_q_t *prio_q, void *item, size_t *item_size, k_prio_t *prio);
```

- **功能描述**

  从优先级队列中获取一个元素。

- **参数解释**

  | IN/OUT | 参数名    | 描述                      |
  | ------ | --------- | ------------------------- |
  | [in]   | prio_q    | 优先级队列句柄            |
  | [out]  | item      | 承接出队元素的内存 buffer |
  | [out]  | item_size | 出队的元素大小            |
  | [out]  | prio      | 出队的元素的优先级        |

- **返回值**

  K_ERR_NONE 元素出队成功。

  K_ERR_PRIO_Q_EMPTY 优先级队列已空。

### tos_prio_q_flush

```c
k_err_t tos_prio_q_flush(k_prio_q_t *prio_q);
```

- **功能描述**

  冲洗优先级队列（复位优先级队列，丢弃优先级队列中的所有元素）。

- **参数解释**

  | IN/OUT | 参数名 | 描述           |
  | ------ | ------ | -------------- |
  | [in]   | prio_q | 优先级队列句柄 |

- **返回值**

  K_ERR_NONE 冲洗优先级队列成功。

### tos_prio_q_is_empty

```c
int tos_prio_q_is_empty(k_prio_q_t *prio_q);
```

- **功能描述**

  判断一个优先级队列是否为空。

- **参数解释**

  | IN/OUT | 参数名 | 描述           |
  | ------ | ------ | -------------- |
  | [in]   | prio_q | 优先级队列句柄 |

- **返回值**

  K_TRUE 优先级队列为空。

  K_FALSE 优先级队列非空。

### tos_prio_q_is_full

```c
int tos_prio_q_is_full(k_prio_q_t *prio_q);
```

- **功能描述**

  判断一个优先级队列是否为满。

- **参数解释**

  | IN/OUT | 参数名 | 描述           |
  | ------ | ------ | -------------- |
  | [in]   | prio_q | 优先级队列句柄 |

- **返回值**

  K_TRUE 优先级队列为满。

  K_FALSE 优先级队列非满。

## 定时器 timer

### tos_timer_create

```c
k_err_t tos_timer_create(k_timer_t *tmr,
                         k_tick_t delay,
                         k_tick_t period,
						 k_timer_callback_t callback,
                         void *cb_arg,
                         k_opt_t opt);
```

- **功能描述**

  创建一个定时器。

- **参数解释**

  | IN/OUT | 参数名   | 描述                 |
  | ------ | -------- | -------------------- |
  | [in]   | tmr      | 定时器句柄           |
  | [in]   | delay    | 定时器延迟多久后执行 |
  | [in]   | period   | 周期性 timer 的周期  |
  | [in]   | callback | 定时器回调           |
  | [in]   | cb_arg   | 定时器回调参数       |
  | [in]   | opt      | 选项                 |

- **注意**

  opt 选项说明：

  1、TOS_OPT_TIMER_ONESHOT

  一次性定时器，创建定时器时传入此参数，表示该定时器是一次性的，只会执行一次。

  2、TOS_OPT_TIMER_PERIODIC

  周期性定时器，创建定时器时传入此参数，表示该定时器是周期性的，定时器到期后，会按 period 参数开启下一个周期。

- **返回值**

  K_ERR_NONE 定时器创建成功。

  K_ERR_TIMER_INVALID_PERIOD 非法的 period 参数。

  K_ERR_TIMER_INVALID_DELAY 非法的 delay 参数。

### tos_timer_destroy

```c
k_err_t tos_timer_destroy(k_timer_t *tmr);
```

- **功能描述**

  销毁一个定时器。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | tmr    | 定时器句柄 |

- **返回值**

  K_ERR_NONE 定时器启动成功。

  K_ERR_TIMER_INACTIVE 定时器并未被创建。

### tos_timer_start

```c
k_err_t tos_timer_start(k_timer_t *tmr);
```

- **功能描述**

  启动一个定时器。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | tmr    | 定时器句柄 |

- **返回值**

  K_ERR_NONE 定时器启动成功。

  K_ERR_TIMER_INACTIVE 定时器并未被创建。

  K_ERR_TIMER_INVALID_STATE 定时器状态非法。

### tos_timer_stop

```c
k_err_t tos_timer_stop(k_timer_t *tmr);
```

- **功能描述**

  停止一个定时器。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | tmr    | 定时器句柄 |

- **返回值**

  K_ERR_NONE 停止定时器成功。

  K_ERR_TIMER_INACTIVE 定时器并未被创建。

  K_ERR_TIMER_STOPPED 定时器已经处于停止状态。

### tos_timer_delay_change

```c
k_err_t tos_timer_delay_change(k_timer_t *tmr, k_tick_t delay);
```

- **功能描述**

  修改一个定时器的触发延时。

- **参数解释**

  | IN/OUT | 参数名 | 描述                 |
  | ------ | ------ | -------------------- |
  | [in]   | tmr    | 定时器句柄           |
  | [in]   | delay  | 修改后的触发延时参数 |

- **返回值**

  K_ERR_NONE 修改定时器触发延时成功。

  K_ERR_TIMER_INACTIVE 定时器并未被创建。

  K_ERR_TIMER_RUNNING 定时器正处于运行状态（不允许修改运行中的定时器的触发延时参数）。

  K_ERR_TIMER_INVALID_DELAY 非法的 delay 参数（试图将一个一次性定时器的 delay 参数修改为 0）。

### tos_timer_period_change

```c
k_err_t tos_timer_period_change(k_timer_t *tmr, k_tick_t perio);
```

- **功能描述**

  修改一个定时器的触发周期。

- **参数解释**

  | IN/OUT | 参数名 | 描述                 |
  | ------ | ------ | -------------------- |
  | [in]   | tmr    | 定时器句柄           |
  | [in]   | period | 修改后的触发周期参数 |

- **返回值**

  K_ERR_NONE 修改定时器触发周期成功。

  K_ERR_TIMER_INACTIVE 定时器并未被创建。

  K_ERR_TIMER_RUNNING 定时器正处于运行状态（不允许修改运行中的定时器的触发延时参数）。

  K_ERR_TIMER_INVALID_PERIOD 非法的 period 参数（试图将一个周期性定时器的 period 参数修改为 0）。

## 计时表 stopwatch

### tos_stopwatch_create

```c
k_err_t tos_stopwatch_create(k_stopwatch_t *stopwatch);
```

- **功能描述**

  创建一个计时表。

- **参数解释**

  | IN/OUT | 参数名    | 描述       |
  | ------ | --------- | ---------- |
  | [in]   | stopwatch | 计时表句柄 |

- **返回值**

  K_ERR_NONE 计时表创建成功。

  K_ERR_OBJ_PTR_NULL stopwatch 是空指针。

### tos_stopwatch_destroy

```c
k_err_t tos_stopwatch_destroy(k_stopwatch_t *stopwatch);
```

- **功能描述**

  销毁一个计时表。

- **参数解释**

  | IN/OUT | 参数名    | 描述       |
  | ------ | --------- | ---------- |
  | [in]   | stopwatch | 计时表句柄 |

- **返回值**

  K_ERR_NONE 计时表销毁成功。

  K_ERR_OBJ_PTR_NULL stopwatch 是空指针。

  K_ERR_OBJ_INVALID stopwatch 指向的不是一个合法的计时表。

### tos_stopwatch_countdown

```c
k_err_t tos_stopwatch_countdown(k_stopwatch_t *stopwatch, k_tick_t tick);
```

- **功能描述**

  开始计时，时间单位为系统滴答数。

- **参数解释**

  | IN/OUT | 参数名    | 描述           |
  | ------ | --------- | -------------- |
  | [in]   | stopwatch | 定时器句柄     |
  | [in]   | tick      | 计时的时间长度 |

- **返回值**

  K_ERR_NONE 计时表启动成功。

### tos_stopwatch_countdown_ms

```c
k_err_t tos_stopwatch_countdown_ms(k_stopwatch_t *stopwatch, k_time_t millisec);
```

- **功能描述**

  开始计时，时间单位为毫秒。

- **参数解释**

  | IN/OUT | 参数名    | 描述           |
  | ------ | --------- | -------------- |
  | [in]   | stopwatch | 定时器句柄     |
  | [in]   | millisec  | 计时的时间长度 |

- **返回值**

  K_ERR_NONE 计时表启动成功。

### tos_stopwatch_delay

```c
void tos_stopwatch_delay(k_tick_t tick);
```

- **功能描述**

  利用计时表进行一次延时，时间单位为系统滴答数。

- **参数解释**

  | IN/OUT | 参数名    | 描述           |
  | ------ | --------- | -------------- |
  | [in]   | stopwatch | 定时器句柄     |
  | [in]   | tick      | 延迟的时间长度 |

### tos_stopwatch_delay_ms

```c
void tos_stopwatch_delay_ms(k_time_t millisec);
```

- **功能描述**

  利用计时表进行一次延时，时间单位为毫秒。

- **参数解释**

  | IN/OUT | 参数名    | 描述           |
  | ------ | --------- | -------------- |
  | [in]   | stopwatch | 定时器句柄     |
  | [in]   | millisec  | 延迟的时间长度 |

### tos_stopwatch_remain

```c
k_tick_t tos_stopwatch_remain(k_stopwatch_t *stopwatch);
```

- **功能描述**

  返回计时表剩余的时间，时间单位为系统滴答数，如果计时已到则返回 0。

- **参数解释**

  | IN/OUT | 参数名    | 描述       |
  | ------ | --------- | ---------- |
  | [in]   | stopwatch | 定时器句柄 |

- **返回值**

  计时表剩余时间。

### tos_stopwatch_remain_ms

```c
k_tick_t tos_stopwatch_remain_ms(k_stopwatch_t *stopwatch);
```

- **功能描述**

  返回计时表剩余的时间，时间单位为毫秒，如果计时已到则返回 0。

- **参数解释**

  | IN/OUT | 参数名    | 描述       |
  | ------ | --------- | ---------- |
  | [in]   | stopwatch | 定时器句柄 |

- **返回值**

  计时表剩余时间。

### tos_stopwatch_is_expired

```c
int tos_stopwatch_is_expired(k_stopwatch_t *stopwatch);
```

- **功能描述**

  返回计时表是否已超时。

- **参数解释**

  | IN/OUT | 参数名    | 描述       |
  | ------ | --------- | ---------- |
  | [in]   | stopwatch | 定时器句柄 |

- **返回值**

  K_TRUE 计时表已超时。

  K_FALSE 计时表未超时。

## 位图 bitmap

### tos_bitmap_create_empty

```c
__API__ k_err_t tos_bitmap_create_empty(k_bitmap_t *bitmap, k_bmtbl_t *bitmap_tbl, uint32_t bit_max);
```

- **功能描述**

  创建一个全 0 的位图。

- **参数解释**

  | IN/OUT | 参数名     | 描述                            |
  | ------ | ---------- | ------------------------------- |
  | [in]   | bitmap     | 位图句柄                        |
  | [in]   | bitmap_tbl | 位图所需的存储表。              |
  | [in]   | bit_max    | 位图中可记录的最大的 bit 位长度 |

- 注意

  bitmap_tbl 是由用户传入的一片内存区域，其长度由 TOS_BITMAP_SIZE 计算，对于最大的 bit 位长度为 bit_max 的位图存储表来说，其长度为 TOS_BITMAP_SIZE(bit_max)，那么用户可以定义一个 k_bmtbl_t bitmap_tbl[TOS_BITMAP_SIZE(bit_max)]，bitmap_tbl 作为此接口的第二个入参。

- 返回值\*\*

  K_ERR_NONE 计时表创建成功。

  K_ERR_OBJ_PTR_NULL bitmap 或 bitmap_tbl 是空指针。

### tos_bitmap_create_full

```c
__API__ k_err_t tos_bitmap_create_full(k_bitmap_t *bitmap, k_bmtbl_t *bitmap_tbl, uint32_t bit_max);
```

- **功能描述**

  创建一个全 1 的位图。

- **参数解释**

  | IN/OUT | 参数名     | 描述                            |
  | ------ | ---------- | ------------------------------- |
  | [in]   | bitmap     | 位图句柄                        |
  | [in]   | bitmap_tbl | 位图所需的存储表。              |
  | [in]   | bit_max    | 位图中可记录的最大的 bit 位长度 |

- 注意

  bitmap_tbl 是由用户传入的一片内存区域，其长度由 TOS_BITMAP_SIZE 计算，对于最大的 bit 位长度为 bit_max 的位图存储表来说，其长度为 TOS_BITMAP_SIZE(bit_max)，那么用户可以定义一个 k_bmtbl_t bitmap_tbl[TOS_BITMAP_SIZE(bit_max)]，bitmap_tbl 作为此接口的第二个入参。

- 返回值\*\*

  K_ERR_NONE 计时表创建成功。

  K_ERR_OBJ_PTR_NULL bitmap 或 bitmap_tbl 是空指针。

### tos_bitmap_destroy

```c
k_err_t tos_bitmap_destroy(k_bitmap_t *bitmap);
```

- **功能描述**

  销毁一个位图。

- **参数解释**

  | IN/OUT | 参数名 | 描述     |
  | ------ | ------ | -------- |
  | [in]   | bitmap | 位图句柄 |

- **返回值**

  K_ERR_NONE 位图销毁成功。

  K_ERR_OBJ_PTR_NULL bitmap 是空指针。

  K_ERR_OBJ_INVALID bitmap 指向的不是一个合法的位图。

### tos_bitmap_set

```c
k_err_t tos_bitmap_set(k_bitmap_t *bitmap, uint32_t bit);
```

- **功能描述**

  设置一个 bit 位，即将此 bit 位标记为 1。

- **参数解释**

  | IN/OUT | 参数名 | 描述            |
  | ------ | ------ | --------------- |
  | [in]   | bitmap | 位图句柄        |
  | [in]   | bit    | 要设置的 bit 位 |

- **返回值**

  K_ERR_NONE bit 位设置成功。

  K_ERR_BITMAP_EXCEED bit 超出了 bitmap 可以记录的范围。

### tos_bitmap_reset

```c
k_err_t tos_bitmap_reset(k_bitmap_t *bitmap, uint32_t bit);
```

- **功能描述**

  复位一个 bit 位，即将此 bit 位标记为 0。

- **参数解释**

  | IN/OUT | 参数名 | 描述            |
  | ------ | ------ | --------------- |
  | [in]   | bitmap | 位图句柄        |
  | [in]   | bit    | 要设置的 bit 位 |

- **返回值**

  K_ERR_NONE bit 位复位成功。

  K_ERR_BITMAP_EXCEED bit 超出了 bitmap 可以记录的范围。

### tos_bitmap_is_set

```c
k_err_t tos_bitmap_is_set(k_bitmap_t *bitmap, uint32_t bit);
```

- **功能描述**

  判断某 bit 位是否处于设置状态，也即是否为 1。

- **参数解释**

  | IN/OUT | 参数名 | 描述     |
  | ------ | ------ | -------- |
  | [in]   | bitmap | 位图句柄 |
  | [in]   | bit    | bit 位   |

- **返回值**

  K_TRUE 该位被设置，即为 1。

  K_FALSE 该位未被设置，即为 0。

  K_ERR_BITMAP_EXCEED bit 超出了 bitmap 可以记录的范围。

### tos_bitmap_is_reset

```c
k_err_t tos_bitmap_is_reset(k_bitmap_t *bitmap, uint32_t bit);
```

- **功能描述**

  判断某 bit 位是否处于复位状态，也即是否为 0。

- **参数解释**

  | IN/OUT | 参数名 | 描述     |
  | ------ | ------ | -------- |
  | [in]   | bitmap | 位图句柄 |
  | [in]   | bit    | bit 位   |

- **返回值**

  K_TRUE 该位被复位，即为 0。

  K_FALSE 该位未被设置，即为 1。

### tos_bitmap_lsb

```c
int tos_bitmap_lsb(k_bitmap_t *bitmap);
```

- **功能描述**

  获取位图的最低有效位，也即最低的被设置为 1 的位。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | bitmap | 定时器句柄 |

- **返回值**

  位图的最低有效位。

## 时间管理

### tos_systick_get

```c
k_tick_t tos_systick_get(void);
```

- **功能描述**

  获取系统时钟滴答数。

- **参数解释**

  无

- **返回值**

  系统自启动为止到目前为止的时钟滴答数。

### tos_systick_set

```c
void tos_systick_set(k_tick_t tick);
```

- **功能描述**

  设置系统时钟滴答数。

- **参数解释**

  | IN/OUT | 参数名 | 描述           |
  | ------ | ------ | -------------- |
  | [in]   | tick   | 系统时钟滴答数 |

- **返回值**

  无

### tos_tick2millisec

```c
k_time_t tos_tick2millisec(k_tick_t tick);
```

- **功能描述**

  系统时钟滴答数转化为毫秒。

- **参数解释**

  | IN/OUT | 参数名 | 描述           |
  | ------ | ------ | -------------- |
  | [in]   | tick   | 系统时钟滴答数 |

- **返回值**

  毫秒数。

### tos_millisec2tick

```c
k_tick_t tos_millisec2tick(k_time_t millisec);
```

- **功能描述**

  毫秒转化为系统时钟滴答数。

- **参数解释**

  | IN/OUT | 参数名   | 描述   |
  | ------ | -------- | ------ |
  | [in]   | millisec | 毫秒数 |

- **返回值**

  系统时钟滴答数。

### tos_sleep_ms

```c
k_err_t tos_sleep_ms(k_time_t millisec);
```

- **功能描述**

  睡眠当前任务，以毫秒为单位。

- **参数解释**

  | IN/OUT | 参数名   | 描述           |
  | ------ | -------- | -------------- |
  | [in]   | millisec | 任务睡眠毫秒数 |

- **返回值**

  K_ERR_NONE 睡眠成功。

  K_ERR_DELAY_ZERO 毫秒数为 0。

### tos_sleep_hmsm

```c
k_err_t tos_sleep_hmsm(k_time_t hour, k_time_t minute, k_time_t second, k_time_t millisec);
```

- **功能描述**

  睡眠当前任务，睡眠时长以特定的时分秒毫秒度量。

- **参数解释**

  | IN/OUT | 参数名   | 描述   |
  | ------ | -------- | ------ |
  | [in]   | hour     | 小时数 |
  | [in]   | minute   | 分钟数 |
  | [in]   | second   | 秒数   |
  | [in]   | millisec | 毫秒数 |

- **返回值**

  K_ERR_NONE 睡眠成功。

  K_ERR_DELAY_ZERO 毫秒数为 0。

## 功耗管理

### tos_pm_cpu_lpwr_mode_set

```c
k_err_t tos_pm_cpu_lpwr_mode_set(k_cpu_lpwr_mode_t cpu_lpwr_mode);
```

- **功能描述**

  设置 CPU 的低功耗模式。

- **参数解释**

  | IN/OUT | 参数名        | 描述             |
  | ------ | ------------- | ---------------- |
  | [in]   | cpu_lpwr_mode | CPU 的低功耗模式 |

- **返回值**

  K_ERR_PM_WKUP_SOURCE_NOT_INSTALL 对应低功耗模式下的唤醒源没有安装。

  K_ERR_NONE 低功耗模式设置成功。

### tos_pm_device_register

```c
int tos_pm_device_register(k_pm_device_t *device);
```

- **功能描述**

  注册一个低功耗管理设备。

- **参数解释**

  | IN/OUT | 参数名 | 描述               |
  | ------ | ------ | ------------------ |
  | [in]   | device | 低功耗管理设备句柄 |

- **返回值**

  K_ERR_NONE 注册成功。

  K_ERR_OBJ_PTR_NULL device 为空。

  K_ERR_PM_DEVICE_ALREADY_REG 设备已注册过。

  K_ERR_PM_DEVICE_OVERFLOW 注册设备数量太多。

### tos_tickless_wkup_alarm_install

```c
void tos_tickless_wkup_alarm_install(k_cpu_lpwr_mode_t mode, k_tickless_wkup_alarm_t *wkup_alarm);
```

- **功能描述**

  安装一个低功耗模式下的唤醒时钟。

- **参数解释**

  | IN/OUT | 参数名     | 描述       |
  | ------ | ---------- | ---------- |
  | [in]   | mode       | 低功耗模式 |
  | [in]   | wkup_alarm | 唤醒时钟   |

- **返回值**

  无

### tos_tickless_wkup_alarm_init

```c
int tos_tickless_wkup_alarm_init(k_cpu_lpwr_mode_t mode);
```

- **功能描述**

  初始化特定低功耗模式下的唤醒时钟。

- **参数解释**

  | IN/OUT | 参数名 | 描述       |
  | ------ | ------ | ---------- |
  | [in]   | mode   | 低功耗模式 |

- **返回值**

  K_ERR_TICKLESS_WKUP_ALARM_NOT_INSTALLED 对应低功耗模式的唤醒闹钟没有被安装

  K_ERR_TICKLESS_WKUP_ALARM_NO_INIT 对应低功耗模式的唤醒闹钟没有初始化函数

# 组件 API

## MQTT 端云对接

### tos_mqtt_connect

```c
int tos_mqtt_connect(char *host, const char *port, mqtt_con_param_t *param);
```

- **功能描述**

  连接 MQTT 服务器。

- **参数解释**

  | IN/OUT | 参数名 | 描述                 |
  | ------ | ------ | -------------------- |
  | [in]   | host   | 服务器 IP 地址或域名 |
  | [in]   | port   | 服务器端口           |
  | [in]   | param  | 连接参数             |

- **返回值**

  成功，返回 socket fd。

  失败，返回 -1。

### tos_mqtt_publish

```c
int tos_mqtt_publish(int sock, mqtt_pub_param_t *param);
```

- **功能描述**

  发布 MQTT 消息

- **参数解释**

  | IN/OUT | 参数名 | 描述                                  |
  | ------ | ------ | ------------------------------------- |
  | [in]   | sock   | socket fd，由 tos_mqtt_connect 获取。 |
  | [in]   | param  | 消息发布参数                          |

- **返回值**

  0，发布成功。

  -1，发布失败。

### tos_mqtt_subscribe

```c
int tos_mqtt_subscribe(int sock, mqtt_sub_param_t *param);
```

- **功能描述**

  订阅 MQTT 消息

- **参数解释**

  | IN/OUT | 参数名 | 描述                                  |
  | ------ | ------ | ------------------------------------- |
  | [in]   | sock   | socket fd，由 tos_mqtt_connect 获取。 |
  | [in]   | param  | 消息订阅参数                          |

- **返回值**

  0，订阅成功。

  -1，订阅失败。

### tos_mqtt_receive

```c
int tos_mqtt_receive(char *topic, int topic_len, unsigned char *payload, int payload_len);
```

- **功能描述**

  收取 MQTT 消息

- **参数解释**

  | IN/OUT | 参数名      | 描述                   |
  | ------ | ----------- | ---------------------- |
  | [out]  | topic       | 收取到的 MQTT topic    |
  | [in]   | topic_len   | MQTT topic buffer 长度 |
  | [out]  | payload     | 收取到的 payload       |
  | [in]   | payload_len | payload buffer 长度    |

- **返回值**

  成功，返回收取到的 payload 长度。

  失败，返回 -1。

## CMSIS 适配层

### osKernelStart

```c
osStatus osKernelStart(void);
```

- **功能描述**

  启动内核

- **参数解释**
  无

- **返回值**
  osOK，返回成功。

  osErrorOS，返回失败。

### osKernelInitialize

```c
osStatus osKernelInitialize(void);
```

- **功能描述**

  初始化内核

- **参数解释**

  无

- **返回值**

  osOK，返回成功。

  osErrorOS，返回失败。

### osKernelRunning

```c
int32_t osKernelRunning(void);
```

- **功能描述**

  返回内核是否正在运行

- **参数解释**
  无

- **返回值**
  0，内核不在运行。

  非 0，内核正在运行。

### osKernelSysTick

```c
uint32_t osKernelSysTick(void);
```

- **功能描述**

  获取系统时钟滴答数

- **参数解释**
  无

- **返回值**
  系统自启动开始到目前的时钟滴答数。

### osThreadCreate

```c
osThreadId osThreadCreate(const osThreadDef_t *thread_def, void *argument);
```

- **功能描述**

  创建任务

- **参数解释**

  | IN/OUT | 参数名     | 描述           |
  | ------ | ---------- | -------------- |
  | [in]   | thread_def | 任务初始化参数 |
  | [in]   | argument   | 传递给任务入参 |

- **返回值**

  成功，则返回创建的任务句柄。

  失败，返回 NULL。

### osThreadGetId

```c
osThreadId osThreadGetId(void);
```

- **功能描述**

  获取当前任务句柄

- **参数解释**

  无

- **返回值**

  当前任务句柄。

### osThreadTerminate

```c
osStatus osThreadTerminate(osThreadId thread_id);
```

- **功能描述**

  终止任务运行并删除任务

- **参数解释**

  | IN/OUT | 参数名    | 描述     |
  | ------ | --------- | -------- |
  | [in]   | thread_id | 任务句柄 |

- **返回值**

  osOK，返回成功。

  osErrorOS，返回失败。

### osThreadSetPriority

```c
osStatus osThreadSetPriority(osThreadId thread_id, osPriority priority);
```

- **功能描述**

  设置任务优先级

- **参数解释**

  | IN/OUT | 参数名    | 描述     |
  | ------ | --------- | -------- |
  | [in]   | thread_id | 任务句柄 |
  | [in]   | priority  | 优先级   |

- **返回值**

  osOK，返回成功。

  osErrorOS，返回失败。

### osThreadGetPriority

```c
osPriority osThreadGetPriority(osThreadId thread_id);
```

- **功能描述**

  获取任务优先级

- **参数解释**

  | IN/OUT | 参数名    | 描述     |
  | ------ | --------- | -------- |
  | [in]   | thread_id | 任务句柄 |

- **返回值**

  任务优先级。

### osDelay

```c
osStatus osDelay(uint32_t millisec);
```

- **功能描述**

  睡眠当前任务，以毫秒为单位。

- **参数解释**

  | IN/OUT | 参数名   | 描述           |
  | ------ | -------- | -------------- |
  | [in]   | millisec | 睡眠时间毫秒数 |

- **返回值**

  osOK，返回成功。

  osErrorOS，返回失败。

### osTimerCreate

```c
osTimerId osTimerCreate(const osTimerDef_t *timer_def, os_timer_type type, void *argument);
```

- **功能描述**

  创建一个定时器。

- **参数解释**

  | IN/OUT | 参数名    | 描述             |
  | ------ | --------- | ---------------- |
  | [in]   | timer_def | 定时器初始化参数 |
  | [in]   | type      | 定时器类型       |
  | [in]   | argument  | 定时器回调入参   |

- **返回值**

  成功，则返回创建的定时器句柄。

  失败，返回 NULL。

### osTimerStart

```c
osStatus osTimerStart(osTimerId timer_id, uint32_t millisec);
```

- **功能描述**

  启动定时器

- **参数解释**

  | IN/OUT | 参数名   | 描述         |
  | ------ | -------- | ------------ |
  | [in]   | timer_id | 定时器句柄   |
  | [in]   | millisec | 执行延迟参数 |

- **返回值**

  osOK，返回成功。

  osErrorOS，返回失败。

### osTimerStop

```c
osStatus osTimerStop(osTimerId timer_id);
```

- **功能描述**

  停止定时器

- **参数解释**

  | IN/OUT | 参数名   | 描述       |
  | ------ | -------- | ---------- |
  | [in]   | timer_id | 定时器句柄 |

- **返回值**

  osOK，返回成功。

  osErrorOS，返回失败。

### osTimerDelete

```c
osStatus osTimerDelete(osTimerId timer_id);
```

- **功能描述**

  销毁定时器

- **参数解释**

  | IN/OUT | 参数名   | 描述       |
  | ------ | -------- | ---------- |
  | [in]   | timer_id | 定时器句柄 |

- **返回值**

  osOK，返回成功。

  osErrorOS，返回失败。

### osMutexCreate

```c
osStatus osMutexCreate(const osMutexDef_t *mutex_def);
```

- **功能描述**

  创建互斥量

- **参数解释**

  | IN/OUT | 参数名    | 描述             |
  | ------ | --------- | ---------------- |
  | [in]   | mutex_def | 互斥量初始化参数 |

- **返回值**

  成功，则返回创建的互斥量句柄。

  失败，返回 NULL。

### osMutexWait

```c
osStatus osMutexWait(osMutexId mutex_id, uint32_t millisec);
```

- **功能描述**

  尝试获取一个互斥量

- **参数解释**

  | IN/OUT | 参数名   | 描述       |
  | ------ | -------- | ---------- |
  | [in]   | mutex_id | 互斥量句柄 |
  | [in]   | millisec | 超时参数   |

- **返回值**

  osOK，返回成功。

  osErrorOS，返回失败。

### osMutexRelease

```c
osStatus osMutexRelease(osMutexId mutex_id);
```

- **功能描述**

  释放互斥量

- **参数解释**

  | IN/OUT | 参数名   | 描述       |
  | ------ | -------- | ---------- |
  | [in]   | mutex_id | 互斥量句柄 |

- **返回值**

  osOK，返回成功。

  osErrorOS，返回失败。

### osMutexDelete

```c
osStatus osMutexDelete(osMutexId mutex_id);
```

- **功能描述**

  销毁互斥量

- **参数解释**

  | IN/OUT | 参数名   | 描述       |
  | ------ | -------- | ---------- |
  | [in]   | mutex_id | 互斥量句柄 |

- **返回值**

  osOK，返回成功。

  osErrorOS，返回失败。

### osSemaphoreCreate

```c
osSemaphoreId osSemaphoreCreate(const osSemaphoreDef_t *semaphore_def, int32_t count);
```

- **功能描述**

  创建一个信号量

- **参数解释**

  | IN/OUT | 参数名        | 描述             |
  | ------ | ------------- | ---------------- |
  | [in]   | semaphore_def | 信号量初始化参数 |
  | [in]   | count         | 信号量初始值     |

- **返回值**

  成功，则返回创建的信号量句柄。

  失败，返回 NULL。

### osSemaphoreWait

```c
int32_t osSemaphoreWait(osSemaphoreId semaphore_id, uint32_t millisec);
```

- **功能描述**

  等待一个信号量

- **参数解释**

  | IN/OUT | 参数名       | 描述       |
  | ------ | ------------ | ---------- |
  | [in]   | semaphore_id | 信号量句柄 |
  | [in]   | millisec     | 超时参数   |

- **返回值**

  成功，则返回信号量可用的资源数。

  失败，返回 -1。

### osSemaphoreRelease

```c
osStatus osSemaphoreRelease(osSemaphoreId semaphore_id);
```

- **功能描述**

  释放信号量

- **参数解释**

  | IN/OUT | 参数名       | 描述       |
  | ------ | ------------ | ---------- |
  | [in]   | semaphore_id | 信号量句柄 |

- **返回值**

  osOK，返回成功。

  osErrorOS，返回失败。

### osSemaphoreDelete

```c
osStatus osSemaphoreDelete(osSemaphoreId semaphore_id);
```

- **功能描述**

  销毁信号量

- **参数解释**

  | IN/OUT | 参数名       | 描述       |
  | ------ | ------------ | ---------- |
  | [in]   | semaphore_id | 信号量句柄 |

- **返回值**

  osOK，返回成功。

  osErrorOS，返回失败。

### osPoolCreate

```c
osPoolId osPoolCreate(const osPoolDef_t *pool_def);
```

- **功能描述**

  创建一个内存池

- **参数解释**

  | IN/OUT | 参数名   | 描述             |
  | ------ | -------- | ---------------- |
  | [in]   | pool_def | 内存池初始化参数 |

- **返回值**

  成功，则返回创建的内存池句柄。

  失败，返回 NULL。

### osPoolAlloc

```c
void *osPoolAlloc(osPoolId pool_id);
```

- **功能描述**

  从内存池中获取一个内存块

- **参数解释**

  | IN/OUT | 参数名  | 描述       |
  | ------ | ------- | ---------- |
  | [in]   | pool_id | 内存池句柄 |

- **返回值**

  成功，则返回分配到的内存块起始地址。

  失败，返回 NULL。

### osPoolCAlloc

```c
void *osPoolCAlloc(osPoolId pool_id);
```

- **功能描述**

  从内存池中获取一个内存块，并将此内存块清空为 0。

- **参数解释**

  | IN/OUT | 参数名  | 描述       |
  | ------ | ------- | ---------- |
  | [in]   | pool_id | 内存池句柄 |

- **返回值**

  成功，则返回分配到的内存块起始地址。

  失败，返回 NULL。

### osPoolFree

```c
osStatus osPoolFree(osPoolId pool_id, void *block);
```

- **功能描述**

  释放一个内存块

- **参数解释**

  | IN/OUT | 参数名  | 描述           |
  | ------ | ------- | -------------- |
  | [in]   | pool_id | 内存池句柄     |
  | [in]   | block   | 内存块起始地址 |

- **返回值**

  osOK，返回成功。

  osErrorOS，返回失败。

### osMessageCreate

```c
osMessageQId osMessageCreate(const osMessageQDef_t *queue_def, osThreadId thread_id);
```

- **功能描述**

  创建一个队列

- **参数解释**

  | IN/OUT | 参数名    | 描述           |
  | ------ | --------- | -------------- |
  | [in]   | queue_def | 队列初始化参数 |
  | [in]   | thread_id | 任务句柄       |

- **返回值**

  成功，则返回创建的队列句柄。

  失败，返回 NULL。

### osMessagePut

```c
osStatus osMessagePut(osMessageQId queue_id, uint32_t info, uint32_t millisec);
```

- **功能描述**

  向队列中放置一个消息

- **参数解释**

  | IN/OUT | 参数名   | 描述           |
  | ------ | -------- | -------------- |
  | [in]   | queue_id | 队列句柄       |
  | [in]   | info     | 要放置的消息体 |
  | [in]   | millisec | 超时参数       |

- **返回值**

  osOK，返回成功。

  osErrorOS，返回失败。

### osMessageGet

```c
osEvent osMessageGet(osMessageQId queue_id, uint32_t millisec);
```

- **功能描述**

  从内存池中获取一个消息

- **参数解释**

  | IN/OUT | 参数名   | 描述     |
  | ------ | -------- | -------- |
  | [in]   | queue_id | 队列句柄 |
  | [in]   | millisec | 超时参数 |

- **返回值**

  一个包含了返回状态的 osEvent 信息结构体。

# 网络 API

## sal 模组联网接口

### tos_sal_module_register

```c
int tos_sal_module_register(sal_module_t *module);
```

- **功能描述**

  注册一个联网模组

- **参数解释**

  | IN/OUT | 参数名 | 描述         |
  | ------ | ------ | ------------ |
  | [in]   | module | 联网模组句柄 |

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_sal_module_init

```c
int tos_sal_module_init(void);
```

- **功能描述**

  初始化模组

- **参数解释**

  无

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_sal_module_parse_domain

```c
int tos_sal_module_parse_domain(const char *host_name, char *host_ip);
```

- **功能描述**

  域名解析，将一个域名转换为 IP 地址。

- **参数解释**

  | IN/OUT | 参数名    | 描述             |
  | ------ | --------- | ---------------- |
  | [in]   | host_name | 待解析的域名     |
  | [out]  | host_ip   | 解析后的 IP 地址 |

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_sal_module_connect

```c
int tos_sal_module_connect(const char *ip, const char *port, sal_proto_t proto);
```

- **功能描述**

  向远端发起连接

- **参数解释**

  | IN/OUT | 参数名 | 描述         |
  | ------ | ------ | ------------ |
  | [in]   | ip     | IP 地址      |
  | [in]   | port   | 端口         |
  | [in]   | proto  | TCP/UDP 协议 |

- **返回值**

  成功，则返回连接的 socket id。

  失败，返回 -1。

### tos_sal_module_send

```c
int tos_sal_module_send(int sock, const void *buf, size_t len);
```

- **功能描述**

  向远端发送数据（TCP 协议栈）

- **参数解释**

  | IN/OUT | 参数名 | 描述                                      |
  | ------ | ------ | ----------------------------------------- |
  | [in]   | sock   | socket id(由 tos_sal_module_connect 获取) |
  | [in]   | buf    | 发送的数据起始地址                        |
  | [in]   | len    | 发送的数据长度                            |

- **返回值**
  发送的数据长度。

### tos_sal_module_recv

```c
int tos_sal_module_recv(int sock, void *buf, size_t len);
```

- **功能描述**

  从远端读取数据（TCP 协议栈）

- **参数解释**

  | IN/OUT | 参数名 | 描述                                        |
  | ------ | ------ | ------------------------------------------- |
  | [in]   | sock   | socket id（由 tos_sal_module_connect 获取） |
  | [out]  | buf    | 接收数据 buffer                             |
  | [in]   | len    | 接收数据 buffer 长度                        |

- **返回值**
  实际接收到的数据长度。

### tos_sal_module_recv_timeout

```c
int tos_sal_module_recv_timeout(int sock, void *buf, size_t len, uint32_t timeout);
```

- **功能描述**

  从远端接收数据（TCP 协议栈）

- **参数解释**

  | IN/OUT | 参数名  | 描述                                        |
  | ------ | ------- | ------------------------------------------- |
  | [in]   | sock    | socket id（由 tos_sal_module_connect 获取） |
  | [in]   | buf     | 数据起始地址                                |
  | [in]   | len     | 数据长度                                    |
  | [in]   | timeout | 超时参数                                    |

- **返回值**
  实际接收到的数据长度。

### tos_sal_module_sendto

```c
int tos_sal_module_sendto(int sock, char *ip, char *port, void *buf, size_t len);
```

- **功能描述**

  向远端发送数据（UDP 协议栈）

- **参数解释**

  | IN/OUT | 参数名 | 描述                                        |
  | ------ | ------ | ------------------------------------------- |
  | [in]   | sock   | socket id（由 tos_sal_module_connect 获取） |
  | [in]   | ip     | IP 地址                                     |
  | [in]   | port   | 端口                                        |
  | [in]   | buf    | 待发送数据起始地址                          |
  | [in]   | len    | 待发送数据长度                              |

- **返回值**
  发送的数据长度。

### tos_sal_module_recvfrom

```c
int tos_sal_module_recvfrom(int sock, char *ip, char *port, void *buf, size_t len);
```

- **功能描述**

  从远端接收数据（UDP 协议栈）

- **参数解释**

  | IN/OUT | 参数名 | 描述                                        |
  | ------ | ------ | ------------------------------------------- |
  | [in]   | sock   | socket id（由 tos_sal_module_connect 获取） |
  | [in]   | ip     | IP 地址                                     |
  | [in]   | port   | 端口                                        |
  | [in]   | buf    | 接收数据 buffer 起始地址                    |
  | [in]   | len    | 接收数据 buffer 长度                        |

- **返回值**
  实际接收到的数据长度。

### tos_sal_module_close

```c
int tos_sal_module_close(int sock);
```

- **功能描述**

  关闭与远端的连接

- **参数解释**

  | IN/OUT | 参数名 | 描述                                        |
  | ------ | ------ | ------------------------------------------- |
  | [in]   | sock   | socket id（由 tos_sal_module_connect 获取） |

- **返回值**

  0，返回成功。

  -1，返回失败。

## lora 模组联网接口

### tos_lora_module_register

```c
int tos_lora_module_register(lora_module_t *module);
```

- **功能描述**

  注册一个 lora 模组

- **参数解释**

  | IN/OUT | 参数名 | 描述          |
  | ------ | ------ | ------------- |
  | [in]   | module | lora 模组句柄 |

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_lora_module_init

```c
int tos_lora_module_init(void);
```

- **功能描述**

  初始化 lora 模组

- **参数解释**

  无

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_lora_module_join

```c
int tos_lora_module_join(void);
```

- **功能描述**

  加入 lora 网关

- **参数解释**

  无

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_lora_module_send

```c
int tos_lora_module_send(const void *buf, size_t len);
```

- **功能描述**

  通过 lora 模组发送数据

- **参数解释**

  | IN/OUT | 参数名 | 描述                 |
  | ------ | ------ | -------------------- |
  | [in]   | buf    | 要发送的数据起始地址 |
  | [in]   | len    | 要发送的数据长度     |

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_lora_module_recv

```c
int tos_lora_module_recv(void *buf, size_t len);
```

- **功能描述**

  通过 lora 模组接收数据

- **参数解释**

  | IN/OUT | 参数名 | 描述                   |
  | ------ | ------ | ---------------------- |
  | [out]  | buf    | 接收数据的 buffer 地址 |
  | [in]   | len    | buffer 长度            |

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_lora_module_recv_timeout

```c
int tos_lora_module_recv_timeout(void *buf, size_t len, uint32_t timeout);
```

- **功能描述**

  通过 lora 模组接收数据

- **参数解释**

  | IN/OUT | 参数名  | 描述                   |
  | ------ | ------- | ---------------------- |
  | [in]   | buf     | 接收数据的 buffer 地址 |
  | [in]   | len     | buffer 长度            |
  | [in]   | timeout | 超时参数               |

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_lora_module_close

```c
int tos_lora_module_close(void);
```

- **功能描述**

  关闭 lora 模组

- **参数解释**

  无

- **返回值**

  0，返回成功。

  -1，返回失败。

## 腾讯定制固件模组联网接口

### tos_tf_module_register

```c
int tos_tf_module_register(tencent_firmware_module_t *module);
```

- **功能描述**

  注册一个腾讯定制固件模组

- **参数解释**

  | IN/OUT | 参数名 | 描述                 |
  | ------ | ------ | -------------------- |
  | [in]   | module | 腾讯定制固件模组句柄 |

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_tf_module_init

```c
int tos_tf_module_init(void);
```

- **功能描述**

  初始化腾讯定制固件模组

- **参数解释**

  无

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_tf_module_info_set

```c
int tos_tf_module_info_set(device_info_t *info, tls_mode_t tls_mode);
```

- **功能描述**

  设置腾讯定制固件模组设备信息

- **参数解释**

  | IN/OUT | 参数名        | 描述                               |
  | ------ | ------------- | ---------------------------------- |
  | [in]   | device_info_t | 腾讯定制固件模组设备信息描述结构体 |
  | [in]   | tls_mode      | tls 校验模式                       |

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_tf_module_mqtt_conn

```c
int tos_tf_module_mqtt_conn(mqtt_param_t init_params);
```

- **功能描述**

  通过腾讯定制固件模组发起 MQTT 连接

- **参数解释**

  | IN/OUT | 参数名      | 描述          |
  | ------ | ----------- | ------------- |
  | [in]   | init_params | MQTT 连接参数 |

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_tf_module_mqtt_discon

```c
int tos_tf_module_mqtt_discon(void);
```

- **功能描述**

  断开腾讯定制固件模组的 MQTT 连接

- **参数解释**

  无

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_tf_module_mqtt_pub

```c
int tos_tf_module_mqtt_pub(const char *topic, qos_t qos, char *payload);
```

- **功能描述**

  发布主题

- **参数解释**

  | IN/OUT | 参数名  | 描述           |
  | ------ | ------- | -------------- |
  | [in]   | topic   | 主题           |
  | [in]   | qos     | qos            |
  | [in]   | payload | 主题的消息负载 |

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_tf_module_mqtt_publ

```c
int tos_tf_module_mqtt_publ(const char *topic, qos_t qos, char *payload);
```

- **功能描述**

  发布长消息负载（> 200）主题

- **参数解释**

  | IN/OUT | 参数名  | 描述           |
  | ------ | ------- | -------------- |
  | [in]   | topic   | 主题           |
  | [in]   | qos     | qos            |
  | [in]   | payload | 主题的消息负载 |

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_tf_module_mqtt_sub

```c
int tos_tf_module_mqtt_sub(char *topic, qos_t qos);
```

- **功能描述**

  订阅主题

- **参数解释**

  | IN/OUT | 参数名 | 描述 |
  | ------ | ------ | ---- |
  | [in]   | topic  | 主题 |
  | [in]   | qos    | qos  |

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_tf_module_mqtt_unsub

```c
int tos_tf_module_mqtt_unsub(char *topic);
```

- **功能描述**

  取消订阅主题

- **参数解释**

  | IN/OUT | 参数名 | 描述 |
  | ------ | ------ | ---- |
  | [in]   | topic  | 主题 |

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_tf_module_mqtt_state

```c
int tos_tf_module_mqtt_state(mqtt_state_t *state);
```

- **功能描述**

  查询 MQTT 连接状态

- **参数解释**

  | IN/OUT | 参数名 | 描述     |
  | ------ | ------ | -------- |
  | [out]  | state  | 连接状态 |

- **返回值**

  0，返回成功。

  -1，返回失败。

### tos_tf_module_debug_level_set

```c
int tos_tf_module_debug_level_set(int log_level);
```

- **功能描述**

  设置模组调试日志级别

- **参数解释**

  | IN/OUT | 参数名    | 描述         |
  | ------ | --------- | ------------ |
  | [in]   | log_level | 调试日志级别 |

- **返回值**

  0，返回成功。

  -1，返回失败。