refresh 开发指南.pdf

add new interface develop guide and sample code

doc/5.TencentOS-tiny-SDK文档.md → doc/5.TencentOS tiny SDK文档.md

@@ -1164,6 +1164,332 @@ k_err_t tos_event_post_keep(k_event_t *event, k_event_flag_t flag);
 
   K_ERR_OBJ_INVALID event指向的并不是一个合法的事件。
 
+## 完成量completion
+
+### tos_completion_create
+
+```c
+k_err_t tos_completion_create(k_completion_t *completion);
+```
+
+- **功能描述**
+
+  创建一个完成量。
+
+- **参数解释**
+
+  | IN/OUT | 参数名     | 描述       |
+  | ------ | ---------- | ---------- |
+  | [in]   | completion | 完成量句柄 |
+
+- **返回值**
+
+  K_ERR_NONE 完成量创建成功。
+
+  K_ERR_OBJ_PTR_NULL completion指针为空。
+
+### tos_completion_destroy
+
+```c
+k_err_t tos_completion_destroy(k_completion_t *completion);
+```
+
+- **功能描述**
+
+  销毁一个完成量。
+
+- **参数解释**
+
+  | IN/OUT | 参数名     | 描述       |
+  | ------ | ---------- | ---------- |
+  | [in]   | completion | 完成量句柄 |
+
+- **返回值**
+
+  K_ERR_NONE 完成量销毁成功。
+
+  K_ERR_OBJ_PTR_NULL completion指针为空。
+
+  K_ERR_OBJ_INVALID completion指向的不是一个合法的完成量。
+
+### tos_completion_pend
+
+```c
+k_err_t tos_completion_pend(k_completion_t *completion);
+```
+
+- **功能描述**
+
+  等待完成量完成（永久阻塞等待）。
+
+- **参数解释**
+
+  | IN/OUT | 参数名     | 描述       |
+  | ------ | ---------- | ---------- |
+  | [in]   | completion | 完成量句柄 |
+
+- **返回值**
+
+  K_ERR_NONE 完成量已完成。
+
+  K_ERR_PEND_SCHED_LOCKED 完成量没有完成，并且系统调度锁处于锁定状态。
+
+  K_ERR_PEND_DESTROY 尝试等待的完成量被删除了。
+
+### tos_completion_pend_timed
+
+```c
+k_err_t tos_completion_pend_timed(k_completion_t *completion, k_tick_t timeout);
+```
+
+- **功能描述**
+
+  尝试等待完成量完成（有限时间内的阻塞等待）。
+
+- **参数解释**
+
+  | IN/OUT | 参数名     | 描述         |
+  | ------ | ---------- | ------------ |
+  | [in]   | completion | 完成量句柄   |
+  | [in]   | timeout    | 等待超时参数 |
+
+- **返回值**
+
+  K_ERR_NONE 完成量已完成。
+
+  K_ERR_PEND_NOWAIT 此完成量尚未完成，同时timeout参数为TOS_TIME_NOWAIT（表示完成量未完成时立即返回）
+
+  K_ERR_PEND_SCHED_LOCKED 完成量没有完成，并且系统调度锁处于锁定状态。
+
+  K_ERR_PEND_DESTROY 尝试等待的完成量被删除了。
+
+  K_ERR_PEND_TIMEOUT 在timeout时间范围内完成量未完成。
+
+### tos_completion_post
+
+```c
+k_err_t tos_completion_post(k_completion_t *completion);
+```
+
+- **功能描述**
+
+  释放完成量（此完成量状态变为已完成），并唤醒等待队列上的一个任务。如果有多个任务在此完成量的等待队列上，唤醒优先级最高的任务。
+
+- **参数解释**
+
+  | IN/OUT | 参数名     | 描述       |
+  | ------ | ---------- | ---------- |
+  | [in]   | completion | 完成量句柄 |
+
+- **返回值**
+
+  K_ERR_NONE 完成量释放成功。
+
+### tos_completion_post_all
+
+```c
+k_err_t tos_completion_post_all(k_completion_t *completion);
+```
+
+- **功能描述**
+
+  释放完成量（此完成量状态变为已完成），并唤醒等待队列上的所有任务。
+
+- **参数解释**
+
+  | IN/OUT | 参数名     | 描述       |
+  | ------ | ---------- | ---------- |
+  | [in]   | completion | 完成量句柄 |
+
+- **返回值**
+
+  K_ERR_NONE 完成量释放成功。
+
+### tos_completion_reset
+
+```c
+k_err_t tos_completion_reset(k_completion_t *completion);
+```
+
+- **功能描述**
+
+  复位完成量（将此完成量状态更改为未完成）。
+
+- **参数解释**
+
+  | IN/OUT | 参数名     | 描述       |
+  | ------ | ---------- | ---------- |
+  | [in]   | completion | 完成量句柄 |
+
+- **返回值**
+
+  K_ERR_NONE 完成量复位成功。
+
+### tos_completion_is_done
+
+```c
+k_err_t tos_completion_is_done(k_completion_t *completion);
+```
+
+- **功能描述**
+
+  判断此完成量是否已完成。
+
+- **参数解释**
+
+  | IN/OUT | 参数名     | 描述       |
+  | ------ | ---------- | ---------- |
+  | [in]   | completion | 完成量句柄 |
+
+- **返回值**
+
+  K_TRUE 完成量已完成。
+
+  K_FALSE 完成量未完成。
+
+## 计数锁countdown latch
+
+### tos_countdownlatch_create
+
+```c
+k_err_t tos_countdownlatch_create(k_countdownlatch_t *countdownlatch, k_countdownlatch_cnt_t count);
+```
+
+- **功能描述**
+
+  创建一个计数锁。
+
+- **参数解释**
+
+  | IN/OUT | 参数名         | 描述             |
+  | ------ | -------------- | ---------------- |
+  | [in]   | countdownlatch | 计数锁句柄       |
+  | [in]   | count          | 期望等待的计数值 |
+
+- **返回值**
+
+  K_ERR_NONE 计数锁创建成功。
+
+  K_ERR_OBJ_PTR_NULL countdownlatch指针为空。
+
+### tos_countdownlatch_destroy
+
+```c
+k_err_t tos_countdownlatch_destroy(k_countdownlatch_t *countdownlatch);
+```
+
+- **功能描述**
+
+  销毁一个计数锁。
+
+- **参数解释**
+
+  | IN/OUT | 参数名         | 描述       |
+  | ------ | -------------- | ---------- |
+  | [in]   | countdownlatch | 计数锁句柄 |
+
+- **返回值**
+
+  K_ERR_NONE 计数锁销毁成功。
+
+  K_ERR_OBJ_PTR_NULL countdownlatch指针为空。
+
+  K_ERR_OBJ_INVALID countdownlatch指向的不是一个合法的计数锁。
+
+### tos_countdownlatch_pend
+
+```c
+k_err_t tos_countdownlatch_pend(k_countdownlatch_t *countdownlatch);
+```
+
+- **功能描述**
+
+  等待计数锁完成（永久阻塞等待）。
+
+- **参数解释**
+
+  | IN/OUT | 参数名         | 描述       |
+  | ------ | -------------- | ---------- |
+  | [in]   | countdownlatch | 计数量句柄 |
+
+- **返回值**
+
+  K_ERR_NONE 计数锁已完成。
+
+  K_ERR_PEND_SCHED_LOCKED 计数锁没有完成，并且系统调度锁处于锁定状态。
+
+  K_ERR_PEND_DESTROY 尝试等待的计数锁被删除了。
+
+### tos_countdownlatch_pend_timed
+
+```c
+k_err_t tos_countdownlatch_pend_timed(k_countdownlatch_t *countdownlatch, k_tick_t timeout);
+```
+
+- **功能描述**
+
+  尝试等待计数锁完成（有限时间内的阻塞等待）。
+
+- **参数解释**
+
+  | IN/OUT | 参数名         | 描述         |
+  | ------ | -------------- | ------------ |
+  | [in]   | countdownlatch | 计数锁句柄   |
+  | [in]   | timeout        | 等待超时参数 |
+
+- **返回值**
+
+  K_ERR_NONE 计数锁已完成。
+
+  K_ERR_PEND_NOWAIT 此计数锁尚未完成，同时timeout参数为TOS_TIME_NOWAIT（表示计数锁未完成时立即返回）
+
+  K_ERR_PEND_SCHED_LOCKED 计数锁没有完成，并且系统调度锁处于锁定状态。
+
+  K_ERR_PEND_DESTROY 尝试等待的计数锁被删除了。
+
+  K_ERR_PEND_TIMEOUT 在timeout时间范围内计数锁未完成。
+
+### tos_countdownlatch_post
+
+```c
+k_err_t tos_countdownlatch_post(k_countdownlatch_t *countdownlatch);
+```
+
+- **功能描述**
+
+  计数锁（此计数锁的计数值减一），并唤醒等待队列上的一个任务。如果有多个任务在此计数锁的等待队列上，唤醒优先级最高的任务。
+
+- **参数解释**
+
+  | IN/OUT | 参数名         | 描述       |
+  | ------ | -------------- | ---------- |
+  | [in]   | countdownlatch | 计数锁句柄 |
+
+- **返回值**
+
+  K_ERR_NONE 计数锁释放成功。
+
+### tos_countdownlatch_reset
+
+```c
+k_err_t tos_countdownlatch_reset(k_countdownlatch_t *countdownlatch, k_countdownlatch_cnt_t count);
+```
+
+- **功能描述**
+
+  复位计数锁（将此计数锁的计数值复位为新的期望值）。
+
+- **参数解释**
+
+  | IN/OUT | 参数名         | 描述                 |
+  | ------ | -------------- | -------------------- |
+  | [in]   | countdownlatch | 计数锁句柄           |
+  | [in]   | count          | 期望复位的新的计数值 |
+
+- **返回值**
+
+  K_ERR_NONE 计数锁复位成功。
+
 ## 消息队列message queue
 
 ### tos_msg_q_create

doc/code/2.3.4 completion/main.c

+#include "tos.h"
+#include "mcu_init.h"
+
+#define STK_SIZE_TASK_WAIT      512
+#define STK_SIZE_TASK_TRIGGER   512
+
+k_stack_t stack_task_wait[STK_SIZE_TASK_WAIT];
+k_stack_t stack_task_trigger[STK_SIZE_TASK_TRIGGER];
+
+k_task_t task_wait;
+k_task_t task_trigger;
+
+k_completion_t completion;
+
+void entry_task_wait(void *arg)
+{
+    printf("wait: I won't go further until someone do the trigger(make it 'complete')\n");
+    tos_completion_pend(&completion);
+    printf("wait: someone has made it complete, so I'm here\n");
+}
+
+void entry_task_trigger(void *arg)
+{
+    printf("trigger: I'm the one who make complete, anyone waitting for the complete won't go further until I do the trigger\n");
+    tos_completion_post(&completion);
+    printf("trigger: I have done the completion\n");
+}
+
+int main(void)
+{
+    board_init();
+    tos_knl_init();
+    tos_completion_create(&completion);
+    (void)tos_task_create(&task_wait, "wait", entry_task_wait, NULL,
+                            3, stack_task_wait, STK_SIZE_TASK_WAIT, 0);
+    (void)tos_task_create(&task_trigger, "trigger", entry_task_trigger, NULL,
+                            4, stack_task_trigger, STK_SIZE_TASK_TRIGGER, 0);
+    tos_knl_start();
+}

doc/code/2.3.5 countdownlatch/main.c

+#include "tos.h"
+#include "mcu_init.h"
+
+#define STK_SIZE_TASK_WIZARD    512
+#define STK_SIZE_TASK_WARRIOR   512
+
+k_stack_t stack_task_wizard[STK_SIZE_TASK_WIZARD];
+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_wizard;
+k_task_t task_warrior_0;
+k_task_t task_warrior_1;
+k_task_t task_warrior_2;
+
+k_countdownlatch_t countdownlatch;
+
+void entry_task_warrior_0(void *arg)
+{
+    printf("warrior 0: I have done my job\n");
+    tos_countdownlatch_post(&countdownlatch);
+}
+
+void entry_task_warrior_1(void *arg)
+{
+    printf("warrior 1: I have done my job\n");
+    tos_countdownlatch_post(&countdownlatch);
+}
+
+void entry_task_warrior_2(void *arg)
+{
+    printf("warrior 2: I have done my job\n");
+    tos_countdownlatch_post(&countdownlatch);
+}
+
+
+void entry_task_wizard(void *arg)
+{
+    printf("wizard: I will set 3 warriors to find the fragments\n");
+    tos_countdownlatch_create(&countdownlatch, 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);
+    printf("wizard: now warriors are on their way, I will wait here until they all done the job\n");
+    tos_countdownlatch_pend(&countdownlatch);
+    printf("wizard: the warriors all have done their jobs, let's make the weapon\n");
+}
+
+int main(void)
+{
+    board_init();
+    tos_knl_init();
+    (void)tos_task_create(&task_wizard, "wizard", entry_task_wizard, NULL,
+                            3, stack_task_wizard, STK_SIZE_TASK_WIZARD, 0);
+    tos_knl_start();
+}
+

doc/code/2.3.4 queue/main.c → doc/code/2.3.6 message queue/main.c

@@ -7,15 +7,19 @@
 #define PRIO_TASK_RECEIVER_HIGHER_PRIO      4
 #define PRIO_TASK_RECEIVER_LOWER_PRIO       (PRIO_TASK_RECEIVER_HIGHER_PRIO + 1)
 
+#define MESSAGE_MAX     10
+
 k_stack_t stack_task_receiver_higher_prio[STK_SIZE_TASK_RECEIVER];
 k_stack_t stack_task_receiver_lower_prio[STK_SIZE_TASK_RECEIVER];
 k_stack_t stack_task_sender[STK_SIZE_TASK_SENDER];
 
+uint8_t msg_pool[MESSAGE_MAX * sizeof(void *)];
+
 k_task_t task_receiver_higher_prio;
 k_task_t task_receiver_lower_prio;
 k_task_t task_sender;
 
-k_queue_t queue;
+k_msg_q_t msg_q;
 
 extern void entry_task_receiver_higher_prio(void *arg);
 extern void entry_task_receiver_lower_prio(void *arg);
@@ -25,14 +29,11 @@ void entry_task_receiver_higher_prio(void *arg)
 {
     k_err_t err;
     void *msg_received;
-    size_t msg_size;
 
     while (K_TRUE) {
-        err = tos_queue_pend(&queue, &msg_received, &msg_size, TOS_TIME_FOREVER);
+        err = tos_msg_q_pend(&msg_q, &msg_received, TOS_TIME_FOREVER);
         if (err == K_ERR_NONE) {
-            printf("entry_task_receiver_higher_prio:\n");
-            printf("message body: %s\n", (char *)msg_received);
-            printf("message size: %d\n", msg_size);
+            printf("higher: msg incoming[%s]\n", (char *)msg_received);
         }
     }
 }
@@ -41,14 +42,11 @@ void entry_task_receiver_lower_prio(void *arg)
 {
     k_err_t err;
     void *msg_received;
-    size_t msg_size;
 
     while (K_TRUE) {
-        err = tos_queue_pend(&queue, &msg_received, &msg_size, TOS_TIME_FOREVER);
+        err = tos_msg_q_pend(&msg_q, &msg_received, TOS_TIME_FOREVER);
         if (err == K_ERR_NONE) {
-            printf("entry_task_receiver_lower_prio:\n");
-            printf("message body: %s\n", (char *)msg_received);
-            printf("message size: %d\n", msg_size);
+            printf("lower: msg incoming[%s]\n", (char *)msg_received);
         }
     }
 }
@@ -56,29 +54,25 @@ void entry_task_receiver_lower_prio(void *arg)
 void entry_task_sender(void *arg)
 {
     int i = 1;
-    char *msg_to_one_receiver = "message for one receiver[with highest priority]";
+    char *msg_to_one_receiver = "message for one receiver(with highest priority)";
     char *msg_to_all_receiver = "message for all receivers";
 
     while (K_TRUE) {
         if (i == 2) {
-            printf("entry_task_sender:\n");
-            printf("send a message to one receiver, and shoud be the highest priority one\n");
-            tos_queue_post(&queue, msg_to_one_receiver, strlen(msg_to_one_receiver));
+            printf("sender: send a message to one receiver, and shoud be the highest priority one\n");
+            tos_msg_q_post(&msg_q, msg_to_one_receiver);
         }
         if (i == 3) {
-            printf("entry_task_sender:\n");
-            printf("send a message to all recevier\n");
-            tos_queue_post_all(&queue, msg_to_all_receiver, strlen(msg_to_all_receiver));
+            printf("sender: send a message to all recevier\n");
+            tos_msg_q_post_all(&msg_q, msg_to_all_receiver);
         }
         if (i == 4) {
-            printf("entry_task_sender:\n");
-            printf("send a message to one receiver, and shoud be the highest priority one\n");
-            tos_queue_post(&queue, msg_to_one_receiver, strlen(msg_to_one_receiver));
+            printf("sender: send a message to one receiver, and shoud be the highest priority one\n");
+            tos_msg_q_post(&msg_q, msg_to_one_receiver);
         }
         if (i == 5) {
-            printf("entry_task_sender:\n");
-            printf("send a message to all recevier\n");
-            tos_queue_post_all(&queue, msg_to_all_receiver, strlen(msg_to_all_receiver));
+            printf("sender: send a message to all recevier\n");
+            tos_msg_q_post_all(&msg_q, msg_to_all_receiver);
         }
         tos_task_delay(1000);
         ++i;
@@ -89,7 +83,7 @@ int main(void)
 {
     board_init();
     tos_knl_init();
-    tos_queue_create(&queue);
+    tos_msg_q_create(&msg_q, msg_pool, MESSAGE_MAX);
     (void)tos_task_create(&task_receiver_higher_prio, "receiver_higher_prio",
                             entry_task_receiver_higher_prio, NULL, PRIO_TASK_RECEIVER_HIGHER_PRIO,
                             stack_task_receiver_higher_prio, STK_SIZE_TASK_RECEIVER, 0);
@@ -100,4 +94,3 @@ int main(void)
                             4, stack_task_sender, STK_SIZE_TASK_SENDER, 0);
     tos_knl_start();
 }
-

doc/code/2.3.7 mail queue/main.c

+#include "tos.h"
+#include "mcu_init.h"
+
+#define STK_SIZE_TASK_RECEIVER      512
+#define STK_SIZE_TASK_SENDER        512
+
+#define PRIO_TASK_RECEIVER_HIGHER_PRIO      4
+#define PRIO_TASK_RECEIVER_LOWER_PRIO       (PRIO_TASK_RECEIVER_HIGHER_PRIO + 1)
+
+#define MAIL_MAX    10
+
+k_stack_t stack_task_receiver_higher_prio[STK_SIZE_TASK_RECEIVER];
+k_stack_t stack_task_receiver_lower_prio[STK_SIZE_TASK_RECEIVER];
+k_stack_t stack_task_sender[STK_SIZE_TASK_SENDER];
+
+typedef struct mail_st {
+    char   *message;
+    int     payload;
+} mail_t;
+
+uint8_t mail_pool[MAIL_MAX * sizeof(mail_t)];
+
+k_task_t task_receiver_higher_prio;
+k_task_t task_receiver_lower_prio;
+k_task_t task_sender;
+
+k_mail_q_t mail_q;
+
+extern void entry_task_receiver_higher_prio(void *arg);
+extern void entry_task_receiver_lower_prio(void *arg);
+extern void entry_task_sender(void *arg);
+
+void entry_task_receiver_higher_prio(void *arg)
+{
+    k_err_t err;
+    mail_t mail;
+    size_t mail_size;
+
+    while (K_TRUE) {
+        err = tos_mail_q_pend(&mail_q, &mail, &mail_size, TOS_TIME_FOREVER);
+        if (err == K_ERR_NONE) {
+            TOS_ASSERT(mail_size == sizeof(mail_t));
+            printf("higher: msg incoming[%s], payload[%d]\n", mail.message, mail.payload);
+        }
+    }
+}
+
+void entry_task_receiver_lower_prio(void *arg)
+{
+    k_err_t err;
+    mail_t mail;
+    size_t mail_size;
+
+    while (K_TRUE) {
+        err = tos_mail_q_pend(&mail_q, &mail, &mail_size, TOS_TIME_FOREVER);
+        if (err == K_ERR_NONE) {
+            TOS_ASSERT(mail_size == sizeof(mail_t));
+            printf("lower: msg incoming[%s], payload[%d]\n", mail.message, mail.payload);
+        }
+    }
+}
+
+void entry_task_sender(void *arg)
+{
+    int i = 1;
+    mail_t mail;
+
+    while (K_TRUE) {
+        if (i == 2) {
+            printf("sender: send a mail to one receiver, and shoud be the highest priority one\n");
+            mail.message = "1st time post";
+            mail.payload = 1;
+            tos_mail_q_post(&mail_q, &mail, sizeof(mail_t));
+        }
+        if (i == 3) {
+            printf("sender: send a message to all recevier\n");
+            mail.message = "2nd time post";
+            mail.payload = 2;
+            tos_mail_q_post_all(&mail_q, &mail, sizeof(mail_t));
+        }
+        if (i == 4) {
+            printf("sender: send a message to one receiver, and shoud be the highest priority one\n");
+            mail.message = "3rd time post";
+            mail.payload = 3;
+            tos_mail_q_post(&mail_q, &mail, sizeof(mail_t));
+        }
+        if (i == 5) {
+            printf("sender: send a message to all recevier\n");
+            mail.message = "4th time post";
+            mail.payload = 4;
+            tos_mail_q_post_all(&mail_q, &mail, sizeof(mail_t));
+        }
+        tos_task_delay(1000);
+        ++i;
+    }
+}
+
+int main(void)
+{
+    board_init();
+    tos_knl_init();
+    tos_mail_q_create(&mail_q, mail_pool, MAIL_MAX, sizeof(mail_t));
+    (void)tos_task_create(&task_receiver_higher_prio, "receiver_higher_prio",
+                            entry_task_receiver_higher_prio, NULL, PRIO_TASK_RECEIVER_HIGHER_PRIO,
+                            stack_task_receiver_higher_prio, STK_SIZE_TASK_RECEIVER, 0);
+    (void)tos_task_create(&task_receiver_lower_prio, "receiver_lower_prio",
+                            entry_task_receiver_lower_prio, NULL, PRIO_TASK_RECEIVER_LOWER_PRIO,
+                            stack_task_receiver_lower_prio, STK_SIZE_TASK_RECEIVER, 0);
+    (void)tos_task_create(&task_sender, "sender", entry_task_sender, NULL,
+                            5, stack_task_sender, STK_SIZE_TASK_SENDER, 0);
+    tos_knl_start();
+}
+

doc/code/2.3.8 priority message queue/main.c

+#include "tos.h"
+#include "mcu_init.h"
+
+#define STK_SIZE_TASK_RECEIVER      512
+#define STK_SIZE_TASK_SENDER        512
+
+#define MESSAGE_MAX     10
+
+k_stack_t stack_task_receiver[STK_SIZE_TASK_RECEIVER];
+k_stack_t stack_task_sender[STK_SIZE_TASK_SENDER];
+
+uint8_t msg_pool[MESSAGE_MAX * sizeof(void *)];
+
+k_task_t task_receiver;
+k_task_t task_sender;
+
+k_prio_msg_q_t prio_msg_q;
+
+extern void entry_task_receiver(void *arg);
+extern void entry_task_sender(void *arg);
+
+void entry_task_receiver(void *arg)
+{
+    k_err_t err;
+    void *msg_received;
+
+    while (K_TRUE) {
+        err = tos_prio_msg_q_pend(&prio_msg_q, &msg_received, TOS_TIME_FOREVER);
+        if (err == K_ERR_NONE) {
+            printf("receiver: msg incoming[%s]\n", (char *)msg_received);
+        }
+    }
+}
+
+void entry_task_sender(void *arg)
+{
+    char *msg_prio_0 = "msg with priority 0";
+    char *msg_prio_1 = "msg with priority 1";
+    char *msg_prio_2 = "msg with priority 2";
+
+    printf("sender: post a message with priority 2\n");
+    tos_prio_msg_q_post(&prio_msg_q, msg_prio_2, 2);
+
+    printf("sender: post a message with priority 1\n");
+    tos_prio_msg_q_post(&prio_msg_q, msg_prio_1, 1);
+
+    printf("sender: post a message with priority 0\n");
+    tos_prio_msg_q_post(&prio_msg_q, msg_prio_0, 0);
+}
+
+int main(void)
+{
+    board_init();
+    tos_knl_init();
+    tos_prio_msg_q_create(&prio_msg_q, msg_pool, MESSAGE_MAX);
+    (void)tos_task_create(&task_receiver, "receiver", entry_task_receiver, NULL,
+                            5, stack_task_receiver, STK_SIZE_TASK_RECEIVER, 0);
+    (void)tos_task_create(&task_sender, "sender", entry_task_sender, NULL,
+                            4, stack_task_sender, STK_SIZE_TASK_SENDER, 0);
+    tos_knl_start();
+}
+

doc/code/2.3.9 priority mail queue/main.c

+#include "tos.h"
+#include "mcu_init.h"
+
+#define STK_SIZE_TASK_RECEIVER      512
+#define STK_SIZE_TASK_SENDER        512
+
+#define MAIL_MAX    10
+
+k_stack_t stack_task_receiver[STK_SIZE_TASK_RECEIVER];
+k_stack_t stack_task_sender[STK_SIZE_TASK_SENDER];
+
+typedef struct mail_st {
+    char   *message;
+    int     payload;
+} mail_t;
+
+uint8_t mail_pool[MAIL_MAX * sizeof(mail_t)];
+
+k_task_t task_receiver;
+k_task_t task_sender;
+
+k_prio_mail_q_t prio_mail_q;
+
+extern void entry_task_receiver(void *arg);
+extern void entry_task_sender(void *arg);
+
+void entry_task_receiver(void *arg)
+{
+    k_err_t err;
+    mail_t mail;
+    size_t mail_size;
+
+    while (K_TRUE) {
+        err = tos_prio_mail_q_pend(&prio_mail_q, &mail, &mail_size, TOS_TIME_FOREVER);
+        if (err == K_ERR_NONE) {
+            TOS_ASSERT(mail_size == sizeof(mail_t));
+            printf("receiver: msg incoming[%s], payload[%d]\n", mail.message, mail.payload);
+        }
+    }
+}
+
+void entry_task_sender(void *arg)
+{
+    mail_t mail_0, mail_1, mail_2;
+
+    printf("sender: post a mail with priority 2\n");
+    mail_2.message = "priority 2";
+    mail_2.payload = 2;
+    tos_prio_mail_q_post(&prio_mail_q, &mail_2, sizeof(mail_t), 2);
+
+    printf("sender: post a mail with priority 1\n");
+    mail_1.message = "priority 1";
+    mail_1.payload = 1;
+    tos_prio_mail_q_post_all(&prio_mail_q, &mail_1, sizeof(mail_t), 1);
+
+    printf("sender: post a mail with priority 0\n");
+    mail_0.message = "priority 0";
+    mail_0.payload = 0;
+    tos_prio_mail_q_post(&prio_mail_q, &mail_0, sizeof(mail_t), 0);
+}
+
+int main(void)
+{
+    board_init();
+    tos_knl_init();
+    tos_prio_mail_q_create(&prio_mail_q, mail_pool, MAIL_MAX, sizeof(mail_t));
+    (void)tos_task_create(&task_receiver, "receiver", entry_task_receiver, NULL,
+                            6, stack_task_receiver, STK_SIZE_TASK_RECEIVER, 0);
+    (void)tos_task_create(&task_sender, "sender", entry_task_sender, NULL,
+                            5, stack_task_sender, STK_SIZE_TASK_SENDER, 0);
+    tos_knl_start();
+}
+

doc/code/2.8.1 msg_queue/main.c

-#include "tos.h"
-#include "mcu_init.h"
-
-#define STK_SIZE_TASK_DEMO      512 
-
-#define PRIO_TASK_DEMO          4
- 
-k_stack_t stack_task_demo[STK_SIZE_TASK_DEMO]; 
-
-k_task_t task_demo;
-
-k_msg_queue_t msg_queue;
-
-struct msg_st {
-    char *msg;
-    size_t size;
-} msgs[TOS_CFG_MSG_POOL_SIZE] = {
-    { "msg 0", 6 },
-    { "msg 1", 6 },
-    { "msg 2", 6 },
-};
-
-struct msg_st dummy_msg = { "dummy msg", 10 };
-
-extern void entry_task_demo(void *arg);
-
-void fifo_opt(void) {
-    k_err_t err;
-    int i = 0;
-    char *msg_received = K_NULL;
-    size_t msg_size = 0;
-
-    for (; i < TOS_CFG_MSG_POOL_SIZE; ++i) {
-        printf("msg put: %s\n", msgs[i].msg);
-        err = tos_msg_queue_put(&msg_queue, (void *)msgs[i].msg, msgs[i].size, TOS_OPT_MSG_PUT_FIFO);
-        if (err != K_ERR_NONE) {
-            printf("should never happen\n");
-        }
-    }
-
-    err = tos_msg_queue_put(&msg_queue, (void *)dummy_msg.msg, dummy_msg.size, TOS_OPT_MSG_PUT_FIFO);
-    if (err == K_ERR_MSG_QUEUE_FULL) {
-        printf("msg queue is full\n");
-    } else {
-        printf("should never happen\n");
-    }
-
-    for (i = 0; i < TOS_CFG_MSG_POOL_SIZE; ++i) {
-        err = tos_msg_queue_get(&msg_queue, (void **)&msg_received, &msg_size);
-        if (err == K_ERR_NONE) {
-            printf("msg received: %s\n", msg_received);
-            printf("msg size: %d\n", msg_size);
-        } else {
-            printf("should never happen\n");
-        }
-    }
-    err = tos_msg_queue_get(&msg_queue, (void **)&msg_received, &msg_size);
-    if (err == K_ERR_MSG_QUEUE_EMPTY) {
-        printf("msg queue is empty\n");
-    } else {
-        printf("should never happen\n");
-    }
-}
-
-void lifo_opt(void) {
-    k_err_t err;
-    int i = 0;
-    char *msg_received = K_NULL;
-    size_t msg_size = 0;
-
-    for (; i < TOS_CFG_MSG_POOL_SIZE; ++i) {
-        printf("msg put: %s\n", msgs[i].msg);
-        err = tos_msg_queue_put(&msg_queue, (void *)msgs[i].msg, msgs[i].size, TOS_OPT_MSG_PUT_LIFO);
-        if (err != K_ERR_NONE) {
-            printf("should never happen\n");
-        }
-    }
-    err = tos_msg_queue_put(&msg_queue, (void *)dummy_msg.msg, dummy_msg.size, TOS_OPT_MSG_PUT_LIFO);
-    if (err == K_ERR_MSG_QUEUE_FULL) {
-        printf("msg queue is full\n");
-    } else {
-        printf("should never happen\n");
-    }
-
-    for (i = 0; i < TOS_CFG_MSG_POOL_SIZE; ++i) {
-        err = tos_msg_queue_get(&msg_queue, (void **)&msg_received, &msg_size);
-        if (err == K_ERR_NONE) {
-            printf("msg received: %s\n", msg_received);
-            printf("msg size: %d\n", msg_size);
-        } else {
-            printf("should never happen\n");
-        }
-    }
-    err = tos_msg_queue_get(&msg_queue, (void **)&msg_received, &msg_size);
-    if (err == K_ERR_MSG_QUEUE_EMPTY) {
-        printf("msg queue is empty\n");
-    } else {
-        printf("should never happen\n");
-    }
-}
-
-void entry_task_demo(void *arg)
-{ 
-    tos_msg_queue_create(&msg_queue);
-
-    printf("max msg in pool: %d\n", TOS_CFG_MSG_POOL_SIZE);
-    printf("msg queue using TOS_OPT_MSG_PUT_FIFO\n");
-    fifo_opt();
-
-    printf("msg queue using TOS_OPT_MSG_PUT_LIFO\n");
-    lifo_opt();
-}
-
-int main(void)
-{
-    board_init();
-    tos_knl_init(); 
-    (void)tos_task_create(&task_demo, "demo1", entry_task_demo, NULL,
-                            PRIO_TASK_DEMO, stack_task_demo, STK_SIZE_TASK_DEMO,
-                            0); 
-    tos_knl_start();
-}
-

doc/code/2.8.1 ring queue/main.c

+#include "tos.h"
+#include "mcu_init.h"
+
+#define STK_SIZE_TASK_DEMO      512
+
+#define PRIO_TASK_DEMO          4
+
+k_stack_t stack_task_demo[STK_SIZE_TASK_DEMO];
+
+k_task_t task_demo;
+
+typedef struct item_st {
+    int a;
+    int b;
+    int c;
+} item_t;
+
+#define RING_QUEUE_ITEM_MAX        5
+uint8_t ring_q_buffer[RING_QUEUE_ITEM_MAX * sizeof(item_t)];
+
+k_ring_q_t rinq_q;
+
+void entry_task_demo(void *arg)
+{
+    k_err_t err;
+    int i = 0;
+    item_t item;
+    size_t item_size;
+
+    tos_ring_q_create(&rinq_q, ring_q_buffer, RING_QUEUE_ITEM_MAX, sizeof(item_t));
+    for (i = 0; i < RING_QUEUE_ITEM_MAX; ++i) {
+        printf("enqueue: %d  %d  %d\n", i, i, i);
+        item.a = i;
+        item.b = i;
+        item.c = i;
+        err = tos_ring_q_enqueue(&rinq_q, &item, sizeof(item_t));
+        if (err != K_ERR_NONE) {
+            printf("should never happen\n");
+        }
+    }
+
+    err = tos_ring_q_enqueue(&rinq_q, &item, sizeof(item_t));
+    if (err == K_ERR_RING_Q_FULL) {
+        printf("ring queue is full: %s\n", tos_ring_q_is_full(&rinq_q) ? "TRUE" : "FALSE");
+    } else {
+        printf("should never happen\n");
+    }
+
+    for (i = 0; i < RING_QUEUE_ITEM_MAX; ++i) {
+        err = tos_ring_q_dequeue(&rinq_q, &item, &item_size);
+        if (err == K_ERR_NONE) {
+            printf("dequeue: %d %d %d\n", item.a, item.b, item.c);
+        } else {
+            printf("should never happen\n");
+        }
+    }
+
+    err = tos_ring_q_dequeue(&rinq_q, &item, &item_size);
+    if (err == K_ERR_RING_Q_EMPTY) {
+        printf("ring queue is empty: %s\n", tos_ring_q_is_empty(&rinq_q) ? "TRUE" : "FALSE");
+    } else {
+        printf("should never happen\n");
+    }
+
+}
+
+int main(void)
+{
+    board_init();
+    tos_knl_init();
+    (void)tos_task_create(&task_demo, "demo", entry_task_demo, NULL,
+                            PRIO_TASK_DEMO, stack_task_demo, STK_SIZE_TASK_DEMO,
+                            0);
+    tos_knl_start();
+}
+

doc/code/2.8.2 fifo/main.c → doc/code/2.8.2 char fifo/main.c

@@ -31,7 +31,7 @@ void char_push(void)
     }
 
     err = tos_chr_fifo_push(&fifo, 'z');
-    if (err == K_ERR_FIFO_FULL) {
+    if (err == K_ERR_RING_Q_FULL) {
         printf("fifo is full: %s\n", tos_chr_fifo_is_full(&fifo) ? "TRUE" : "FALSE");
     } else {
         printf("should never happen\n");
@@ -46,7 +46,7 @@ void char_push(void)
         }
     }
     err = tos_chr_fifo_pop(&fifo, &data);
-    if (err == K_ERR_FIFO_EMPTY) {
+    if (err == K_ERR_RING_Q_EMPTY) {
         printf("fifo is empty: %s\n", tos_chr_fifo_is_empty(&fifo) ? "TRUE" : "FALSE");
     } else {
         printf("should never happen\n");
@@ -106,7 +106,7 @@ int main(void)
 {
     board_init();
     tos_knl_init();
-    (void)tos_task_create(&task_demo, "demo1", entry_task_demo, NULL,
+    (void)tos_task_create(&task_demo, "demo", entry_task_demo, NULL,
                             PRIO_TASK_DEMO, stack_task_demo, STK_SIZE_TASK_DEMO,
                             0);
     tos_knl_start();

doc/code/2.8.4 priority queue/main.c

+#include "tos.h"
+#include "mcu_init.h"
+
+#define STK_SIZE_TASK_DEMO      512
+
+#define PRIO_TASK_DEMO          4
+
+k_stack_t stack_task_demo[STK_SIZE_TASK_DEMO];
+
+k_task_t task_demo;
+
+typedef struct item_st {
+    int a;
+    int b;
+    int c;
+} item_t;
+
+#define PRIO_QUEUE_ITEM_MAX     5
+uint8_t ring_q_buffer[PRIO_QUEUE_ITEM_MAX * sizeof(item_t)];
+uint8_t mgr_pool[TOS_PRIO_Q_MGR_ARRAY_SIZE(PRIO_QUEUE_ITEM_MAX)];
+
+k_prio_q_t prio_q;
+
+void entry_task_demo(void *arg)
+{
+    k_err_t err;
+    int i = 0;
+    item_t item;
+    k_prio_t prio;
+    size_t item_size;
+
+    tos_prio_q_create(&prio_q, mgr_pool, ring_q_buffer, PRIO_QUEUE_ITEM_MAX, sizeof(item_t));
+
+    for (i = PRIO_QUEUE_ITEM_MAX; i > 0; --i) {
+        printf("enqueue: %d  %d  %d\n", i, i, i);
+        item.a = i;
+        item.b = i;
+        item.c = i;
+        err = tos_prio_q_enqueue(&prio_q, &item, sizeof(item_t), i);
+        if (err != K_ERR_NONE) {
+            printf("should never happen\n");
+        }
+    }
+
+    err = tos_prio_q_enqueue(&prio_q, &item, sizeof(item_t), i);
+    if (err == K_ERR_PRIO_Q_FULL) {
+        printf("priority queue is full: %s\n", tos_prio_q_is_full(&prio_q) ? "TRUE" : "FALSE");
+    } else {
+        printf("should never happen\n");
+    }
+
+    for (i = 0; i < PRIO_QUEUE_ITEM_MAX; ++i) {
+        err = tos_prio_q_dequeue(&prio_q, &item, &item_size, &prio);
+        if (err == K_ERR_NONE) {
+            printf("dequeue: %d %d %d, prio: %d\n", item.a, item.b, item.c, prio);
+        } else {
+            printf("should never happen\n");
+        }
+    }
+
+    err = tos_prio_q_dequeue(&prio_q, &item, &item_size, &prio);
+    if (err == K_ERR_PRIO_Q_EMPTY) {
+        printf("priority queue is empty: %s\n", tos_prio_q_is_empty(&prio_q) ? "TRUE" : "FALSE");
+    } else {
+        printf("should never happen\n");
+    }
+
+}
+
+int main(void)
+{
+    board_init();
+    tos_knl_init();
+    (void)tos_task_create(&task_demo, "demo", entry_task_demo, NULL,
+                            PRIO_TASK_DEMO, stack_task_demo, STK_SIZE_TASK_DEMO,
+                            0);
+    tos_knl_start();
+}

kernel/core/include/tos_completion.h

@@ -86,9 +86,7 @@ __API__ k_err_t tos_completion_pend_timed(k_completion_t *completion, k_tick_t t
  * @param[in]   timeout     how much time(in k_tick_t) we would like to wait.
  *
  * @return  errcode
- * @retval  #K_ERR_PEND_NOWAIT                we get nothing, and we don't wanna wait.
  * @retval  #K_ERR_PEND_SCHED_LOCKED          we can wait, but scheduler is locked.
- * @retval  #K_ERR_PEND_TIMEOUT               the time we wait is up, we get nothing.
  * @retval  #K_ERR_PEND_DESTROY               the completion we are pending is destroyed.
  * @retval  #K_ERR_NONE                       return successfully.
  */

net/at/include/tos_at.h

@@ -144,7 +144,7 @@ typedef struct at_agent_st {
  * @retval  -1              write failed(error).
  * @retval  none -1         the number of bytes written.
  */
-int tos_at_channel_write(int channel_id, uint8_t *buffer, size_t buffer_len);
+__API__ int tos_at_channel_write(int channel_id, uint8_t *buffer, size_t buffer_len);
 
 /**
  * @brief Read data from a channel.
@@ -161,7 +161,7 @@ int tos_at_channel_write(int channel_id, uint8_t *buffer, size_t buffer_len);
  * @retval  -1              read failed(error).
  * @retval  none -1         the number of bytes read.
  */
-int tos_at_channel_read_timed(int channel_id, uint8_t *buffer, size_t buffer_len, uint32_t timeout);
+__API__ int tos_at_channel_read_timed(int channel_id, uint8_t *buffer, size_t buffer_len, uint32_t timeout);
 
 /**
  * @brief Read data from a channel.
@@ -177,7 +177,7 @@ int tos_at_channel_read_timed(int channel_id, uint8_t *buffer, size_t buffer_len
  * @retval  -1              read failed(error).
  * @retval  none -1         the number of bytes read.
  */
-int tos_at_channel_read(int channel_id, uint8_t *buffer, size_t buffer_len);
+__API__ int tos_at_channel_read(int channel_id, uint8_t *buffer, size_t buffer_len);
 
 /**
  * @brief Allocate a channel.
@@ -193,7 +193,7 @@ int tos_at_channel_read(int channel_id, uint8_t *buffer, size_t buffer_len);
  * @retval  -1              allocate failed(error).
  * @retval  none -1         the id of the channel.
  */
-int tos_at_channel_alloc_id(int channel_id, const char *ip, const char *port);
+__API__ int tos_at_channel_alloc_id(int channel_id, const char *ip, const char *port);
 
 /**
  * @brief Allocate a channel.
@@ -208,7 +208,7 @@ int tos_at_channel_alloc_id(int channel_id, const char *ip, const char *port);
  * @retval  -1              allocate failed(error).
  * @retval  none -1         the id of the channel.
  */
-int tos_at_channel_alloc(const char *ip, const char *port);
+__API__ int tos_at_channel_alloc(const char *ip, const char *port);
 
 /**
  * @brief Free a channel.
@@ -222,7 +222,7 @@ int tos_at_channel_alloc(const char *ip, const char *port);
  * @retval  -1              free failed(error).
  * @retval  0               free successfully.
  */
-int tos_at_channel_free(int channel_id);
+__API__ int tos_at_channel_free(int channel_id);
 
 /**
  * @brief Set channel broken.
@@ -261,7 +261,7 @@ __API__ int tos_at_channel_is_working(int channel_id);
  * @retval  -1              initialize failed(error).
  * @retval  0               initialize successfully.
  */
-int tos_at_init(hal_uart_port_t uart_port, at_event_t *event_table, size_t event_table_size);
+__API__ int tos_at_init(hal_uart_port_t uart_port, at_event_t *event_table, size_t event_table_size);
 
 /**
  * @brief De-initialize the at framework.
@@ -270,7 +270,7 @@ int tos_at_init(hal_uart_port_t uart_port, at_event_t *event_table, size_t event
  *
  * @return  
None
  */
-void tos_at_deinit(void);
+__API__ void tos_at_deinit(void);
 
 /**
  * @brief Create a echo struct.
@@ -286,7 +286,7 @@ void tos_at_deinit(void);
  * @retval  -1              create failed(error).
  * @retval  0               create successfully.
  */
-int tos_at_echo_create(at_echo_t *echo, char *buffer, size_t buffer_size, char *echo_expect);
+__API__ int tos_at_echo_create(at_echo_t *echo, char *buffer, size_t buffer_size, char *echo_expect);
 
 /**
  * @brief Execute an at command.
@@ -301,7 +301,7 @@ int tos_at_echo_create(at_echo_t *echo, char *buffer, size_t buffer_size, char *
  * @retval  -1              execute failed(error).
  * @retval  0               execute successfully.
  */
-int tos_at_cmd_exec(at_echo_t *echo, uint32_t timeout, const char *cmd, ...);
+__API__ int tos_at_cmd_exec(at_echo_t *echo, uint32_t timeout, const char *cmd, ...);
 
 /**
  * @brief Execute an at command.
@@ -317,7 +317,7 @@ int tos_at_cmd_exec(at_echo_t *echo, uint32_t timeout, const char *cmd, ...);
  * @retval  -1              execute failed(error).
  * @retval  0               execute successfully.
  */
-int tos_at_cmd_exec_until(at_echo_t *echo, uint32_t timeout, const char *cmd, ...);
+__API__ int tos_at_cmd_exec_until(at_echo_t *echo, uint32_t timeout, const char *cmd, ...);
 
 /**
  * @brief Send raw data througth uart.
@@ -333,7 +333,7 @@ int tos_at_cmd_exec_until(at_echo_t *echo, uint32_t timeout, const char *cmd, ..
  * @retval  -1              execute failed(error).
  * @retval  0               execute successfully.
  */
-int tos_at_raw_data_send(at_echo_t *echo, uint32_t timeout, const uint8_t *buf, size_t size);
+__API__ int tos_at_raw_data_send(at_echo_t *echo, uint32_t timeout, const uint8_t *buf, size_t size);
 
 /**
  * @brief Send raw data througth uart.
@@ -350,7 +350,7 @@ int tos_at_raw_data_send(at_echo_t *echo, uint32_t timeout, const uint8_t *buf,
  * @retval  -1              execute failed(error).
  * @retval  0               execute successfully.
  */
-int tos_at_raw_data_send_until(at_echo_t *echo, uint32_t timeout, const uint8_t *buf, size_t size);
+__API__ int tos_at_raw_data_send_until(at_echo_t *echo, uint32_t timeout, const uint8_t *buf, size_t size);
 
 /**
  * @brief Write byte to the at uart.
@@ -362,7 +362,7 @@ int tos_at_raw_data_send_until(at_echo_t *echo, uint32_t timeout, const uint8_t
  *
  * @return  None
  */
-void tos_at_uart_write_byte(uint8_t data);
+__API__ void tos_at_uart_write_byte(uint8_t data);
 
 /**
  * @brief A global lock provided by at framework.
@@ -376,7 +376,7 @@ void tos_at_uart_write_byte(uint8_t data);
  * @retval  -1              pend failed(error).
  * @retval  0               pend successfully.
  */
-int tos_at_global_lock_pend(void);
+__API__ int tos_at_global_lock_pend(void);
 
 /**
  * @brief A global lock provided by at framework.
@@ -390,7 +390,7 @@ int tos_at_global_lock_pend(void);
  * @retval  -1              post failed(error).
  * @retval  0               post successfully.
  */
-int tos_at_global_lock_post(void);
+__API__ int tos_at_global_lock_post(void);
 
 /**
  * @brief Read data from the uart.
@@ -403,7 +403,7 @@ int tos_at_global_lock_post(void);
  *
  * @return  length of the data read from the uart.
  */
-int tos_at_uart_read(uint8_t *buffer, size_t buffer_len);
+__API__ int tos_at_uart_read(uint8_t *buffer, size_t buffer_len);
 
 /**
  * @brief Read data from the uart.
@@ -416,7 +416,7 @@ int tos_at_uart_read(uint8_t *buffer, size_t buffer_len);
  *
  * @return  length of the data read from the uart.
  */
-int tos_at_uart_readline(uint8_t *buffer, size_t buffer_len);
+__API__ int tos_at_uart_readline(uint8_t *buffer, size_t buffer_len);
 
 /**
  * @brief Read data from the uart.
@@ -429,7 +429,7 @@ int tos_at_uart_readline(uint8_t *buffer, size_t buffer_len);
  *
  * @return  length of the data read from the uart.
  */
-int tos_at_uart_drain(uint8_t *buffer, size_t buffer_len);
+__API__ int tos_at_uart_drain(uint8_t *buffer, size_t buffer_len);
 
 /**
  * @brief Get the remote ip of a channel.
@@ -441,7 +441,7 @@ int tos_at_uart_drain(uint8_t *buffer, size_t buffer_len);
  *
  * @return  remote ip of the channel.
  */
-const char *tos_at_agent_channel_ip_get(int channel_id);
+__API__ const char *tos_at_agent_channel_ip_get(int channel_id);
 
 /**
  * @brief Get the remote port of a channel.
@@ -453,7 +453,7 @@ const char *tos_at_agent_channel_ip_get(int channel_id);
  *
  * @return  remote port of the channel.
  */
-const char *tos_at_agent_channel_port_get(int channel_id);
+__API__ const char *tos_at_agent_channel_port_get(int channel_id);
 
 #endif /* __AT_AGENT_H_ */