*TencentOS Tiny SDK文档

[TOC]

内核API

系统管理

tos_knl_init

k_err_t tos_knl_init(void);

• 功能描述

  初始化内核。

• 参数解释

  无

• 返回值

  K_ERR_NONE 内核初始化成功。

  非K_ERR_NONE 内核初始化失败。

tos_knl_start

k_err_t tos_knl_start(void);

• 功能描述

  启动内核。

• 参数解释

  无

• 返回值

  K_ERR_NONE 内核启动成功。

  非K_ERR_NONE 内核启动失败。

tos_knl_is_running

int tos_knl_is_running(void);

• 功能描述

  判断内核是否正在运行。

• 参数解释

  无

• 返回值

  0 内核不在运行。

  非0 内核正在运行。

tos_knl_irq_enter

void tos_knl_irq_enter(void);

• 功能描述

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

• 参数解释

  无

• 返回值

  无

tos_knl_irq_leave

void tos_knl_irq_leave(void);

• 功能描述

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

• 参数解释

  无

• 返回值

  无

tos_knl_sched_lock

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

k_err_t tos_knl_sched_unlock(void);

• 功能描述

  解锁内核调度。

• 参数解释

  无

• 返回值

  K_ERR_NONE 内核调度解锁成功。

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

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

任务管理

tos_task_create

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

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

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

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

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

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

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

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

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

void tos_task_yield(void);

• 功能描述

  当前任务主动放弃cpu。

• 参数解释

  无

• 返回值

  无

tos_task_stack_draught_depth

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

k_task_t *tos_task_curr_task_get(void);

• 功能描述

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

• 参数解释

  无

• 返回值

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

  非K_NULL 任务句柄。

tos_task_walkthru

void tos_task_walkthru(k_task_walker walker);

• 功能描述

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

• 参数解释

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

• 返回值

  无

  非K_NULL 任务句柄。

堆内存管理

tos_mmheap_pool_add

 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

 k_err_t tos_mmheap_pool_rmv(void *pool_start);

• 功能描述

  从堆内存中删除内存池。

• 参数解释

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

• 返回值

  无

tos_mmheap_alloc

void *tos_mmheap_alloc(size_t size);

• 功能描述

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

• 参数解释

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

• 返回值

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

tos_mmheap_aligned_alloc

void *tos_mmheap_aligned_alloc(size_t size, size_t align);

• 功能描述

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

• 参数解释

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

• 返回值

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

tos_mmheap_realloc

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

• 功能描述

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

• 参数解释

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

• 返回值

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

tos_mmheap_free

void *tos_mmheap_free(void *ptr);

• 功能描述

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

• 参数解释

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

• 返回值

  无。

tos_mmheap_pool_check

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

k_err_t tos_completion_post(k_completion_t *completion);

• 功能描述

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

• 参数解释

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

• 返回值

  K_ERR_NONE 完成量释放成功。

tos_completion_post_all

k_err_t tos_completion_post_all(k_completion_t *completion);

• 功能描述

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

• 参数解释

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

• 返回值

  K_ERR_NONE 完成量释放成功。

tos_completion_reset

k_err_t tos_completion_reset(k_completion_t *completion);

• 功能描述

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

• 参数解释

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

• 返回值

  K_ERR_NONE 完成量复位成功。

tos_completion_is_done

k_err_t tos_completion_is_done(k_completion_t *completion);

• 功能描述

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

• 参数解释

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

• 返回值

  K_TRUE 完成量已完成。

  K_FALSE 完成量未完成。

计数锁countdown latch

tos_countdownlatch_create

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

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

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

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

k_err_t tos_countdownlatch_post(k_countdownlatch_t *countdownlatch);

• 功能描述

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

• 参数解释

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

• 返回值

  K_ERR_NONE 计数锁释放成功。

tos_countdownlatch_reset

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

k_err_t tos_msg_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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

void tos_chr_fifo_flush(k_chr_fifo_t *chr_fifo);

• 功能描述

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

• 参数解释

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

• 返回值

  无

tos_chr_fifo_is_empty

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

k_err_t tos_timer_destroy(k_timer_t *tmr);

• 功能描述

  销毁一个定时器。

• 参数解释

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

• 返回值

  K_ERR_NONE 定时器启动成功。

  K_ERR_TIMER_INACTIVE 定时器并未被创建。

tos_timer_start

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

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

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

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

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

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

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

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

void tos_stopwatch_delay(k_tick_t tick);

• 功能描述

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

• 参数解释

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

tos_stopwatch_delay_ms

void tos_stopwatch_delay_ms(k_time_t millisec);

• 功能描述

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

• 参数解释

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

tos_stopwatch_remain

k_tick_t tos_stopwatch_remain(k_stopwatch_t *stopwatch);

• 功能描述

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

• 参数解释

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

• 返回值

  计时表剩余时间。

tos_stopwatch_remain_ms

k_tick_t tos_stopwatch_remain_ms(k_stopwatch_t *stopwatch);

• 功能描述

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

• 参数解释

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

• 返回值

  计时表剩余时间。

tos_stopwatch_is_expired

int tos_stopwatch_is_expired(k_stopwatch_t *stopwatch);

• 功能描述

  返回计时表是否已超时。

• 参数解释

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

• 返回值

  K_TRUE 计时表已超时。

  K_FALSE 计时表未超时。

位图bitmap

tos_bitmap_create_empty

__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

__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

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

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

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

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

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

int tos_bitmap_lsb(k_bitmap_t *bitmap);

• 功能描述

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

• 参数解释

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

• 返回值

  位图的最低有效位。

时间管理

tos_systick_get

k_tick_t tos_systick_get(void);

• 功能描述

  获取系统时钟滴答数。

• 参数解释

  无

• 返回值

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

tos_systick_set

void tos_systick_set(k_tick_t tick);