refresh sdk manual and development manul

1. add barrier/bitmap/stopwatch/rwlock API to sdk manual 2. add barrier develop sample to develop manual
2020-04-16 15:50:00 +08:00
parent 788c2389b7
commit c603a605fe
8 changed files with 927 additions and 24 deletions
--- 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