PowLu/TencentOS-tiny
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4605e895d3dc754a043ae1c6aae8d44161bab4ad
TencentOS-tiny/doc/05.SDK_Manual.md
Supowang 68167947ca Update 05.SDK_Manual.md
2021-04-26 10:33:41 +08:00

5663 lines
123 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# *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 调度锁溢出。
### 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 内核调度并未处于锁定状态。
## 任务管理
### 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 非法的任务优先级。
### 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 系统堆内存不足。
### 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任务（非法）。
### tos_task_destroy_dyn
```c
k_err_t tos_task_destroy_dyn(k_task_t *task)
```
- **功能描述**
static函数，非对外接口，销毁动态创建（tos_task_create_dyn）的任务，默认由tos_task_destroy()函数调用。
- **参数解释**
| **IN/OUT** | **参数名** | **描述** |
| ---------- | ---------- | ---------------- |
| [in] | task | 任务结构体描述符 |
- **返回值**
K_ERR_NONE 任务销毁成功。
K_ERR_TASK_DESTROY_IDLE 试图销毁idle任务（非法）。
### 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值为零（非法）。
### 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）。
### 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任务（非法）。
### 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 试图恢复当前任务（非法）。
### 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 优先级非法。
### 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，返回失败。
Reference in New Issue View Git Blame Copy Permalink