From 1333e0966bf26909d16a67976c88e43d25aa82eb Mon Sep 17 00:00:00 2001 From: daishengdong Date: Tue, 12 Nov 2019 21:45:29 +0800 Subject: [PATCH] refresh sdk.md add new interface comment --- doc/5.TencentOS-tiny-SDK文档.md | 1956 ++++++++++++++++++++++++++----- 1 file changed, 1688 insertions(+), 268 deletions(-) diff --git a/doc/5.TencentOS-tiny-SDK文档.md b/doc/5.TencentOS-tiny-SDK文档.md index b1a8c120..7b875f4e 100644 --- a/doc/5.TencentOS-tiny-SDK文档.md +++ b/doc/5.TencentOS-tiny-SDK文档.md @@ -187,6 +187,44 @@ k_err_t tos_task_create(k_task_t *task, 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 @@ -209,6 +247,28 @@ k_err_t tos_task_destroy(k_task_t *task) K_ERR_TASK_DESTROY_IDLE 试图销毁idle任务（非法）。 +### tos_task_destroy_dyn + +```c +k_err_t tos_task_destroy_dyn(k_task_t *task) +``` + +- **功能描述** + + 销毁动态创建（tos_task_create_dyn）的任务。 + +- **参数解释** + + | **IN/OUT** | **参数名** | **描述** | + | ---------- | ---------- | ---------------- | + | [in] | task | 任务结构体描述符 | + +- **返回值** + + K_ERR_NONE 任务销毁成功。 + + K_ERR_TASK_DESTROY_IDLE 试图销毁idle任务（非法）。 + ### tos_task_delay ```c @@ -363,6 +423,48 @@ k_err_t tos_task_stack_draught_depth(k_task_t *task, int *depth); 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 @@ -492,6 +594,51 @@ void *tos_mmheap_free(void *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 @@ -727,6 +874,30 @@ k_err_t tos_sem_create(k_sem_t *sem, k_sem_cnt_t init_count); 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 @@ -824,157 +995,6 @@ k_err_t tos_sem_post_all(k_sem_t *sem); K_ERR_SEM_OVERFLOW 信号量值溢出。 -## 队列queue - -### tos_queue_create - -```c -k_err_t tos_queue_create(k_queue_t *queue); -``` - -- **功能描述** - - 创建一个队列。 - -- **参数解释** - - | IN/OUT | 参数名 | 描述 | - | ------ | ------ | -------- | - | [in] | queue | 队列句柄 | - -- **返回值** - - K_ERR_NONE 队列创建成功。 - - K_ERR_OBJ_PTR_NULL queue指针为空。 - -### tos_queue_destroy - -```c -k_err_t tos_queue_destroy(k_queue_t *queue); -``` - -- **功能描述** - - 销毁一个队列。 - -- **参数解释** - - | IN/OUT | 参数名 | 描述 | - | ------ | ------ | -------- | - | [in] | queue | 队列句柄 | - -- **返回值** - - K_ERR_NONE 队列销毁成功。 - - K_ERR_OBJ_PTR_NULL queue指针为空。 - - K_ERR_OBJ_INVALID queue指向的不是一个合法的队列。 - -### tos_queue_flush - -```c -k_err_t tos_queue_flush(k_queue_t *queue); -``` - -- **功能描述** - - 冲洗队列（丢弃队列中的所有消息）。 - -- **参数解释** - - | IN/OUT | 参数名 | 描述 | - | ------ | ------ | -------- | - | [in] | queue | 队列句柄 | - -- **返回值** - - K_ERR_NONE 队列冲洗成功。 - - K_ERR_OBJ_PTR_NULL queue指针为空。 - - K_ERR_OBJ_INVALID queue指向的不是一个合法的队列。 - -### tos_queue_pend - -```c -k_err_t tos_queue_pend(k_queue_t *queue, void **msg_addr, size_t *msg_size, k_tick_t timeout); -``` - -- **功能描述** - - 尝试从队列中获取消息。 - -- **参数解释** - - | IN/OUT | 参数名 | 描述 | - | ------ | -------- | ---------------- | - | [in] | queue | 队列句柄 | - | [out] | msg_addr | 获取到的消息地址 | - | [out] | msg_size | 获取到的消息长度 | - | [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_queue_destroy）。 - -### tos_queue_post - -```c -k_err_t tos_queue_post(k_queue_t *queue, void *msg_addr, size_t msg_size); -``` - -- **功能描述** - - 向队列中放入一个消息，并唤醒等待队列上的一个任务。如果有多个任务在此队列的等待队列上，唤醒优先级最高的任务。 - -- **参数解释** - - | IN/OUT | 参数名 | 描述 | - | ------ | -------- | -------- | - | [in] | queue | 队列句柄 | - | [in] | msg_addr | 消息地址 | - | [in] | msg_size | 消息长度 | - -- **返回值** - - K_ERR_NONE 向队列中放入消息成功。 - - K_ERR_QUEUE_FULL 队列已满。 - -### tos_queue_post_all - -```c -k_err_t tos_queue_post_all(k_queue_t *queue, void *msg_addr, size_t msg_size); -``` - -- **功能描述** - - 向队列中放入一个消息，并唤醒等待队列上的所有任务。 - -- **参数解释** - - | IN/OUT | 参数名 | 描述 | - | ------ | -------- | -------- | - | [in] | queue | 队列句柄 | - | [in] | msg_addr | 消息地址 | - | [in] | msg_size | 消息长度 | - -- **返回值** - - K_ERR_NONE 向队列中放入消息成功。 - - K_ERR_QUEUE_FULL 队列已满。 - ## 事件event ### tos_event_create @@ -1144,38 +1164,61 @@ k_err_t tos_event_post_keep(k_event_t *event, k_event_flag_t flag); K_ERR_OBJ_INVALID event指向的并不是一个合法的事件。 -## 消息队列msg_queue +## 消息队列message queue -### tos_msg_queue_create +### tos_msg_q_create ```c -k_err_t tos_msg_queue_create(k_msg_queue_t *msg_queue); +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_queue | 消息队列句柄 | - -- **注意** - - 消息队列msg_queue与队列queue的区别在于，queue提供了一种同步等待机制。实际上，queue的底层实现采用了msg_queue的消息管理机制。 + | IN/OUT | 参数名 | 描述 | + | ------ | ------- | -------------------- | + | [in] | msg_q | 消息队列句柄 | + | [in] | pool | 消息队列的buffer池 | + | [in] | msg_cnt | 消息队列的最大消息数 | - **返回值** - K_ERR_NONE 获取消息成功。 - - K_ERR_OBJ_PTR_NULL msg_queue是空指针。 + K_ERR_NONE 消息队列创建成功。 -### tos_msg_queue_destroy + K_ERR_OBJ_PTR_NULL msg_q指针为空。 + +### tos_msg_q_create_dyn ```c -k_err_t tos_msg_queue_destroy(k_msg_queue_t *msg_queue); +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); ``` - **功能描述** @@ -1184,118 +1227,977 @@ k_err_t tos_msg_queue_destroy(k_msg_queue_t *msg_queue); - **参数解释** - | IN/OUT | 参数名 | 描述 | - | ------ | --------- | ------------ | - | [in] | msg_queue | 消息队列句柄 | + | IN/OUT | 参数名 | 描述 | + | ------ | ------ | ------------ | + | [in] | msg_q | 消息队列句柄 | - **返回值** - K_ERR_NONE 获取消息成功。 + K_ERR_NONE 消息队列销毁成功。 - K_ERR_OBJ_PTR_NULL msg_queue是空指针。 + K_ERR_OBJ_PTR_NULL msg_q指针为空。 - K_ERR_OBJ_INVALID msg_queue指向的不是一个合法的消息队列。 + K_ERR_OBJ_INVALID msg_q指向的不是一个合法的消息队列。 -### tos_msg_queue_get +### tos_msg_q_destroy_dyn ```c -k_err_t tos_msg_queue_get(k_msg_queue_t *msg_queue, void **msg_addr, size_t *msg_size); +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_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 + +```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] | msg_queue | 消息队列句柄 | - | [out] | msg_addr | 获取到的消息地址 | - | [out] | msg_size | 获取到的消息长度 | + | [in] | ring_q | 环形队列句柄 | + | [in] | item | 待入队的元素地址 | + | [in] | item_size | 待入队的元素大小 | - **返回值** - K_ERR_NONE 获取消息成功。 + K_ERR_NONE 元素入队成功。 - K_ERR_QUEUE_EMPTY 消息队列已满。 + K_ERR_RING_Q_FULL 环形队列已满。 -### tos_msg_queue_put +### tos_ring_q_dequeue ```c -k_err_t tos_msg_queue_put(k_msg_queue_t *msg_queue, void *msg_addr, size_t msg_size, k_opt_t opt); +k_err_t tos_ring_q_dequeue(k_ring_q_t *ring_q, void *item, size_t *item_size); ``` - **功能描述** - 向消息队列中放置一个消息。 + 从环形队列中获取一个元素。 - **参数解释** - | IN/OUT | 参数名 | 描述 | - | ------ | --------- | ---------------- | - | [in] | msg_queue | 消息队列句柄 | - | [in] | msg_addr | 待放置的消息地址 | - | [in] | msg_size | 待放置的消息长度 | - | [in] | opt | 选项 | - -- **注意** - - opt选项说明： - - 1、TOS_OPT_MSG_PUT_LIFO - - ​ 消息队列采用last in first out策略，也就是最后入队的消息最先出队。 - - 2、TOS_OPT_MSG_PUT_FIFO - - ​ 消息队列采用first in first out策略，也就是最先入队的消息最先出队。 - + | IN/OUT | 参数名 | 描述 | + | ------ | --------- | ------------------------ | + | [in] | ring_q | 环形队列句柄 | + | [out] | item | 承接出队元素的内存buffer | + | [out] | item_size | 出队的元素大小 | + - **返回值** - K_ERR_NONE 消息放置成功。 + K_ERR_NONE 元素出队成功。 - K_ERR_QUEUE_FULL 消息队列已满。 + K_ERR_RING_Q_EMPTY 环形队列已空。 -### tos_msg_queue_flush +### tos_ring_q_flush ```c -void tos_msg_queue_flush(k_msg_queue_t *msg_queue); +k_err_t tos_ring_q_flush(k_ring_q_t *ring_q); ``` - **功能描述** - 冲洗消息队列（复位消息队列，丢弃消息队列中的所有消息）。 + 冲洗环形队列（复位环形队列，丢弃环形队列中的所有元素）。 - **参数解释** - | IN/OUT | 参数名 | 描述 | - | ------ | --------- | ------------ | - | [in] | msg_queue | 消息队列句柄 | + | 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_fifo_create +### tos_chr_fifo_create ```c -k_err_t tos_fifo_create(k_fifo_t *fifo, uint8_t *buffer, size_t size); +k_err_t tos_chr_fifo_create(k_chr_fifo_t *chr_fifo, uint8_t *buffer, size_t size); ``` - **功能描述** - 创建一个字符流先入先出队列。 + 创建一个字符流先入先出队列。字符流先入先出队列的底层数据容器是环形队列。 - **参数解释** - | IN/OUT | 参数名 | 描述 | - | ------ | ------ | ---------------------------- | - | [in] | fifo | 字符流先入先出队列句柄 | - | [in] | buffer | 字符流先入先出队列内存池 | - | [in] | size | 字符流先入先出队列内存池大小 | + | IN/OUT | 参数名 | 描述 | + | ------ | -------- | ---------------------------- | + | [in] | chr_fifo | 字符流先入先出队列句柄 | + | [in] | buffer | 字符流先入先出队列内存池 | + | [in] | size | 字符流先入先出队列内存池大小 | - **返回值** @@ -1303,10 +2205,35 @@ k_err_t tos_fifo_create(k_fifo_t *fifo, uint8_t *buffer, size_t size); K_ERR_OBJ_PTR_NULL fifo是空指针。 -### tos_fifo_destroy +### tos_chr_fifo_create_dyn ```c -k_err_t tos_fifo_destroy(k_fifo_t *fifo); +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); ``` - **功能描述** @@ -1315,22 +2242,46 @@ k_err_t tos_fifo_destroy(k_fifo_t *fifo); - **参数解释** - | IN/OUT | 参数名 | 描述 | - | ------ | ------ | ---------------------- | - | [in] | fifo | 字符流先入先出队列句柄 | + | IN/OUT | 参数名 | 描述 | + | ------ | -------- | ---------------------- | + | [in] | chr_fifo | 字符流先入先出队列句柄 | - **返回值** K_ERR_NONE 队列创建成功。 - K_ERR_OBJ_PTR_NULL fifo是空指针。 + K_ERR_OBJ_PTR_NULL chr_fifo是空指针。 - K_ERR_OBJ_INVALID fifo指向的不是一个合法的先入先出队列。 + K_ERR_OBJ_INVALID chr_fifo指向的不是一个合法的先入先出队列。 -### tos_fifo_push +### tos_chr_fifo_destroy_dyn ```c -k_err_t tos_fifo_push(k_fifo_t *fifo, uint8_t data); +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); ``` - **功能描述** @@ -1339,10 +2290,10 @@ k_err_t tos_fifo_push(k_fifo_t *fifo, uint8_t data); - **参数解释** - | IN/OUT | 参数名 | 描述 | - | ------ | ------ | ---------------------- | - | [in] | fifo | 字符流先入先出队列句柄 | - | [in] | data | 压入的字符 | + | IN/OUT | 参数名 | 描述 | + | ------ | -------- | ---------------------- | + | [in] | chr_fifo | 字符流先入先出队列句柄 | + | [in] | data | 压入的字符 | - **返回值** @@ -1350,10 +2301,10 @@ k_err_t tos_fifo_push(k_fifo_t *fifo, uint8_t data); K_ERR_FIFO_FULL 字符流先入先出队列已满。 -### tos_fifo_push_stream +### tos_chr_fifo_push_stream ```c -k_err_t tos_fifo_push_stream(k_fifo_t *fifo, uint8_t *stream, size_t size); +k_err_t tos_chr_fifo_push_stream(k_chr_fifo_t *chr_fifo, uint8_t *stream, size_t size); ``` - **功能描述** @@ -1362,20 +2313,20 @@ k_err_t tos_fifo_push_stream(k_fifo_t *fifo, uint8_t *stream, size_t size); - **参数解释** - | IN/OUT | 参数名 | 描述 | - | ------ | ------ | ---------------------- | - | [in] | fifo | 字符流先入先出队列句柄 | - | [in] | stream | 压入的字符流 | - | [in] | size | 字符流长度 | + | IN/OUT | 参数名 | 描述 | + | ------ | -------- | ---------------------- | + | [in] | chr_fifo | 字符流先入先出队列句柄 | + | [in] | stream | 压入的字符流 | + | [in] | size | 字符流长度 | - **返回值** 实际压入的字符流长度。 -### tos_fifo_pop +### tos_chr_fifo_pop ```c -k_err_t tos_fifo_pop(k_fifo_t *fifo, uint8_t *out); +k_err_t tos_chr_fifo_pop(k_chr_fifo_t *chr_fifo, uint8_t *out); ``` - **功能描述** @@ -1384,10 +2335,10 @@ k_err_t tos_fifo_pop(k_fifo_t *fifo, uint8_t *out); - **参数解释** - | IN/OUT | 参数名 | 描述 | - | ------ | ------ | ---------------------- | - | [in] | fifo | 字符流先入先出队列句柄 | - | [out] | out | 弹出的字符 | + | IN/OUT | 参数名 | 描述 | + | ------ | -------- | ---------------------- | + | [in] | chr_fifo | 字符流先入先出队列句柄 | + | [out] | out | 弹出的字符 | - **返回值** @@ -1395,10 +2346,10 @@ k_err_t tos_fifo_pop(k_fifo_t *fifo, uint8_t *out); K_ERR_FIFO_EMPTY 字符流先入先出队列内存池已空。 -### tos_fifo_pop_stream +### tos_chr_fifo_pop_stream ```c -int tos_fifo_pop_stream(k_fifo_t *fifo, uint8_t *buffer, size_t size); +int tos_chr_fifo_pop_stream(k_chr_fifo_t *fifo, uint8_t *buffer, size_t size); ``` - **功能描述** @@ -1407,20 +2358,20 @@ int tos_fifo_pop_stream(k_fifo_t *fifo, uint8_t *buffer, size_t size); - **参数解释** - | IN/OUT | 参数名 | 描述 | - | ------ | ------ | ---------------------- | - | [in] | fifo | 字符流先入先出队列句柄 | - | [out] | stream | 弹出的字符流 | - | [in] | size | 字符流长度 | + | IN/OUT | 参数名 | 描述 | + | ------ | -------- | ---------------------- | + | [in] | chr_fifo | 字符流先入先出队列句柄 | + | [out] | stream | 弹出的字符流 | + | [in] | size | 字符流长度 | - **返回值** 实际弹出的字符流长度。 -### tos_fifo_flush +### tos_chr_fifo_flush ```c -void tos_fifo_flush(k_fifo_t *fifo); +void tos_chr_fifo_flush(k_chr_fifo_t *chr_fifo); ``` - **功能描述** @@ -1429,18 +2380,18 @@ void tos_fifo_flush(k_fifo_t *fifo); - **参数解释** - | IN/OUT | 参数名 | 描述 | - | ------ | ------ | ---------------------- | - | [in] | fifo | 字符流先入先出队列句柄 | + | IN/OUT | 参数名 | 描述 | + | ------ | -------- | ---------------------- | + | [in] | chr_fifo | 字符流先入先出队列句柄 | - **返回值** 无 -### tos_fifo_is_empty +### tos_chr_fifo_is_empty ```c -int tos_fifo_is_empty(k_fifo_t *fifo); +int tos_chr_fifo_is_empty(k_chr_fifo_t *chr_fifo); ``` - **功能描述** @@ -1449,9 +2400,9 @@ int tos_fifo_is_empty(k_fifo_t *fifo); - **参数解释** - | IN/OUT | 参数名 | 描述 | - | ------ | ------ | ---------------------- | - | [in] | fifo | 字符流先入先出队列句柄 | + | IN/OUT | 参数名 | 描述 | + | ------ | -------- | ---------------------- | + | [in] | chr_fifo | 字符流先入先出队列句柄 | - **返回值** @@ -1459,10 +2410,10 @@ int tos_fifo_is_empty(k_fifo_t *fifo); 非0值，fifo为空。 -### tos_fifo_is_full +### tos_chr_fifo_is_full ```c -int tos_fifo_is_full(k_fifo_t *fifo); +int tos_chr_fifo_is_full(k_chr_fifo_t *chr_fifo); ``` - **功能描述** @@ -1471,9 +2422,9 @@ int tos_fifo_is_full(k_fifo_t *fifo); - **参数解释** - | IN/OUT | 参数名 | 描述 | - | ------ | ------ | ---------------------- | - | [in] | fifo | 字符流先入先出队列句柄 | + | IN/OUT | 参数名 | 描述 | + | ------ | -------- | ---------------------- | + | [in] | chr_fifo | 字符流先入先出队列句柄 | - **返回值** @@ -1481,6 +2432,421 @@ int tos_fifo_is_full(k_fifo_t *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 @@ -1599,6 +2965,60 @@ k_err_t tos_timer_stop(k_timer_t *tmr); 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）。 + ## 时间管理 ### tos_systick_get