diff --git a/doc/04.Development_Manual.md b/doc/04.Development_Manual.md index 0186b44c..01394a4f 100644 --- a/doc/04.Development_Manual.md +++ b/doc/04.Development_Manual.md @@ -850,11 +850,7 @@ int main(void) ##### 编程实例 -1、在tos_config.h中,配置队列组件开关TOS_CFG_COUNTDOWNLATCH_EN: - -`#define TOS_CFG_COUNTDOWNLATCH_EN 1u` - -2、编写main.c示例代码: +1、编写main.c示例代码: ```c /* @@ -933,7 +929,97 @@ int main(void) [实例代码](./code/2.3.5 countdownlatch/main.c) -#### 2.3.6 消息队列 +#### 2.3.6 栅栏 + +##### 概述 + +栅栏提供了一种设置任务阻塞屏障的机制,栅栏创建的时候会指定一个计数值,每当有任务执行tos_barrier_pend时,该计数锁的计数值减一,直到计数锁的计数值为零时,所有阻塞在tos_barrier_pend点上的任务才可以往下运行。 + +##### API讲解 + +##### 编程实例 + +1、编写main.c示例代码: + +```c +/* + 假设有这样的业务场景,共有三个勇士,此三个勇士分头去寻找三个武器的碎片,任意勇士找到自己的那块武器碎片时,都在原地等待,直到所有的小伙伴都找到了自己的武器碎片后,才各自采取下一步行动。用代码看具体如何使用栅栏来完成这个模型。 + */ + +#include "tos_k.h" +#include "mcu_init.h" + +#define STK_SIZE_TASK_WIZARD 512 +#define STK_SIZE_TASK_WARRIOR 512 + +k_stack_t stack_task_warrior_0[STK_SIZE_TASK_WARRIOR]; +k_stack_t stack_task_warrior_1[STK_SIZE_TASK_WARRIOR]; +k_stack_t stack_task_warrior_2[STK_SIZE_TASK_WARRIOR]; + +k_task_t task_warrior_0; +k_task_t task_warrior_1; +k_task_t task_warrior_2; + +k_barrier_t barrier; + +void entry_task_warrior_0(void *arg) +{ + printf("warrior 0: I'm searching the fragment\n"); + tos_task_delay(1000); + printf("warrior 0: I have done my job, waitting other buddies done their job\n"); + tos_barrier_pend(&barrier); + printf("warrior 0: all buddies find their fragment, do my next job\n"); +} + +void entry_task_warrior_1(void *arg) +{ + printf("warrior 1: I'm searching the fragment\n"); + tos_task_delay(1500); + printf("warrior 1: I have done my job, waitting other buddies done their job\n"); + tos_barrier_pend(&barrier); + printf("warrior 1: all buddies find their fragment, do my next job\n"); +} + +void entry_task_warrior_2(void *arg) +{ + printf("warrior 2: I'm searching the fragment\n"); + tos_task_delay(2000); + printf("warrior 2: I have done my job, waitting other buddies done their job\n"); + tos_barrier_pend(&barrier); + printf("warrior 2: all buddies find their fragment, do my next job\n"); +} + +int main(void) +{ + board_init(); + tos_knl_init(); + tos_barrier_create(&barrier, 3); + + (void)tos_task_create(&task_warrior_0, "warrior_0", entry_task_warrior_0, NULL, + 4, stack_task_warrior_0, STK_SIZE_TASK_WIZARD, 0); + (void)tos_task_create(&task_warrior_1, "warrior_1", entry_task_warrior_1, NULL, + 4, stack_task_warrior_1, STK_SIZE_TASK_WIZARD, 0); + (void)tos_task_create(&task_warrior_2, "warrior_2", entry_task_warrior_2, NULL, + 4, stack_task_warrior_2, STK_SIZE_TASK_WIZARD, 0); + tos_knl_start(); +} +``` + +##### 运行效果 + +> warrior 0: I'm searching the fragment +> warrior 1: I'm searching the fragment +> warrior 2: I'm searching the fragment +> warrior 0: I have done my job, waitting other buddies done their job +> warrior 1: I have done my job, waitting other buddies done their job +> warrior 2: I have done my job, waitting other buddies done their job +> warrior 2: all buddies find their fragment, do my next job +> warrior 0: all buddies find their fragment, do my next job +> warrior 1: all buddies find their fragment, do my next job + +[实例代码](./code/2.3.6 barrier/main.c) + +#### 2.3.7 消息队列 ##### 概述 @@ -1065,9 +1151,9 @@ int main(void) > higher: msg incoming[message for all receivers] > lower: msg incoming[message for all receivers] -[实例代码](./code/2.3.6 message queue/main.c) +[实例代码](./code/2.3.7 message queue/main.c) -#### 2.3.7 邮箱队列 +#### 2.3.8 邮箱队列 ##### 概述 @@ -1214,9 +1300,9 @@ int main(void) > higher: msg incoming[4th time post], payload[4] > lower: msg incoming[4th time post], payload[4] -[实例代码](./code/2.3.7 mail queue/main.c) +[实例代码](./code/2.3.8 mail queue/main.c) -#### 2.3.8 优先级消息队列 +#### 2.3.9 优先级消息队列 ##### 概述 @@ -1305,9 +1391,9 @@ int main(void) > receiver: msg incoming[msg with priority 1] > receiver: msg incoming[msg with priority 2] -[实例代码](./code/2.3.8 priority message queue/main.c) +[实例代码](./code/2.3.9 priority message queue/main.c) -#### 2.3.9 优先级邮箱队列 +#### 2.3.10 优先级邮箱队列 ##### 概述 @@ -1410,7 +1496,7 @@ int main(void) > receiver: msg incoming[priority 1], payload[1] > receiver: msg incoming[priority 2], payload[2] -[实例代码](./code/2.3.9 priority mail queue/main.c) +[实例代码](./code/2.3.10 priority mail queue/main.c) ### 2.4 内存管理 @@ -1551,11 +1637,7 @@ k_err_t tos_mmblk_pool_create(k_mmblk_pool_t *mbp, void *pool_start, size_t blk_ ##### 编程实例 -1、在tos_config.h中,配置静态内存组件开关TOS_CFG_MMBLK_EN: - -`#define TOS_CFG_MMBLK_EN 1u` - -2、编写main.c示例代码: +1、编写main.c示例代码: ```c #include "tos_k.h" diff --git a/doc/05.SDK_Manual.md b/doc/05.SDK_Manual.md index 7033c05a..3915175b 100644 --- a/doc/05.SDK_Manual.md +++ b/doc/05.SDK_Manual.md @@ -1490,6 +1490,384 @@ k_err_t tos_countdownlatch_reset(k_countdownlatch_t *countdownlatch, k_countdown 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 @@ -3251,7 +3629,7 @@ k_err_t tos_timer_start(k_timer_t *tmr); - **功能描述** - 启动一个定时器 + 启动一个定时器。 - **参数解释** @@ -3275,7 +3653,7 @@ k_err_t tos_timer_stop(k_timer_t *tmr); - **功能描述** - 停止一个定时器. + 停止一个定时器。 - **参数解释** @@ -3299,7 +3677,7 @@ k_err_t tos_timer_delay_change(k_timer_t *tmr, k_tick_t delay); - **功能描述** - 修改一个定时器的触发延时. + 修改一个定时器的触发延时。 - **参数解释** @@ -3326,7 +3704,7 @@ k_err_t tos_timer_period_change(k_timer_t *tmr, k_tick_t perio); - **功能描述** - 修改一个定时器的触发周期. + 修改一个定时器的触发周期。 - **参数解释** @@ -3345,6 +3723,391 @@ k_err_t tos_timer_period_change(k_timer_t *tmr, k_tick_t perio); 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 diff --git a/doc/code/2.3.9 priority mail queue/main.c b/doc/code/2.3.10 priority mail queue/main.c similarity index 100% rename from doc/code/2.3.9 priority mail queue/main.c rename to doc/code/2.3.10 priority mail queue/main.c diff --git a/doc/code/2.3.6 barrier/main.c b/doc/code/2.3.6 barrier/main.c new file mode 100644 index 00000000..340b4fc3 --- /dev/null +++ b/doc/code/2.3.6 barrier/main.c @@ -0,0 +1,58 @@ +#include "tos_k.h" +#include "mcu_init.h" + +#define STK_SIZE_TASK_WIZARD 512 +#define STK_SIZE_TASK_WARRIOR 512 + +k_stack_t stack_task_warrior_0[STK_SIZE_TASK_WARRIOR]; +k_stack_t stack_task_warrior_1[STK_SIZE_TASK_WARRIOR]; +k_stack_t stack_task_warrior_2[STK_SIZE_TASK_WARRIOR]; + +k_task_t task_warrior_0; +k_task_t task_warrior_1; +k_task_t task_warrior_2; + +k_barrier_t barrier; + +void entry_task_warrior_0(void *arg) +{ + printf("warrior 0: I'm searching the fragment\n"); + tos_task_delay(1000); + printf("warrior 0: I have done my job, waitting other buddies done their job\n"); + tos_barrier_pend(&barrier); + printf("warrior 0: all buddies find their fragment, do my next job\n"); +} + +void entry_task_warrior_1(void *arg) +{ + printf("warrior 1: I'm searching the fragment\n"); + tos_task_delay(1500); + printf("warrior 1: I have done my job, waitting other buddies done their job\n"); + tos_barrier_pend(&barrier); + printf("warrior 1: all buddies find their fragment, do my next job\n"); +} + +void entry_task_warrior_2(void *arg) +{ + printf("warrior 2: I'm searching the fragment\n"); + tos_task_delay(2000); + printf("warrior 2: I have done my job, waitting other buddies done their job\n"); + tos_barrier_pend(&barrier); + printf("warrior 2: all buddies find their fragment, do my next job\n"); +} + +int main(void) +{ + board_init(); + tos_knl_init(); + tos_barrier_create(&barrier, 3); + + (void)tos_task_create(&task_warrior_0, "warrior_0", entry_task_warrior_0, NULL, + 4, stack_task_warrior_0, STK_SIZE_TASK_WIZARD, 0); + (void)tos_task_create(&task_warrior_1, "warrior_1", entry_task_warrior_1, NULL, + 4, stack_task_warrior_1, STK_SIZE_TASK_WIZARD, 0); + (void)tos_task_create(&task_warrior_2, "warrior_2", entry_task_warrior_2, NULL, + 4, stack_task_warrior_2, STK_SIZE_TASK_WIZARD, 0); + tos_knl_start(); +} + diff --git a/doc/code/2.3.6 message queue/main.c b/doc/code/2.3.7 message queue/main.c similarity index 100% rename from doc/code/2.3.6 message queue/main.c rename to doc/code/2.3.7 message queue/main.c diff --git a/doc/code/2.3.7 mail queue/main.c b/doc/code/2.3.8 mail queue/main.c similarity index 100% rename from doc/code/2.3.7 mail queue/main.c rename to doc/code/2.3.8 mail queue/main.c diff --git a/doc/code/2.3.8 priority message queue/main.c b/doc/code/2.3.9 priority message queue/main.c similarity index 100% rename from doc/code/2.3.8 priority message queue/main.c rename to doc/code/2.3.9 priority message queue/main.c diff --git a/kernel/core/tos_rwlock.c b/kernel/core/tos_rwlock.c index dcf1a05c..48cb663e 100644 --- a/kernel/core/tos_rwlock.c +++ b/kernel/core/tos_rwlock.c @@ -135,7 +135,7 @@ __API__ k_err_t tos_rwlock_rpend_try(k_rwlock_t *rwlock) TOS_PTR_SANITY_CHECK(rwlock); TOS_OBJ_VERIFY(rwlock, KNL_OBJ_TYPE_RWLOCK); - err = tos_mutex_pend(&rwlock->lock); + err = tos_mutex_pend_timed(&rwlock->lock, TOS_TIME_NOWAIT); if (err != K_ERR_NONE) { return err; } @@ -230,7 +230,7 @@ __API__ k_err_t tos_rwlock_wpend_try(k_rwlock_t *rwlock) TOS_PTR_SANITY_CHECK(rwlock); TOS_OBJ_VERIFY(rwlock, KNL_OBJ_TYPE_RWLOCK); - err = tos_mutex_pend(&rwlock->lock); + err = tos_mutex_pend_timed(&rwlock->lock, TOS_TIME_NOWAIT); if (err != K_ERR_NONE) { return err; }