From 080b0963e9bd7718f1bd3a84b336255bb08abb2e Mon Sep 17 00:00:00 2001 From: zhangsiqi Date: Wed, 7 Dec 2022 17:02:07 +0800 Subject: [PATCH] sq docs commin Signed-off-by: zhangsiqi push --- zh-cn/device-dev/kernel/kernel-mini-appx-code.md | 2 +- .../kernel/kernel-mini-basic-ipc-event.md | 2 +- .../kernel/kernel-mini-basic-ipc-queue.md | 2 +- .../device-dev/kernel/kernel-small-apx-bitwise.md | 11 +++++++---- zh-cn/device-dev/kernel/kernel-small-apx-dll.md | 14 +++++++++----- .../device-dev/kernel/kernel-small-apx-library.md | 12 ++++++++++-- .../kernel/kernel-small-basic-trans-event.md | 13 +++++++------ .../kernel/kernel-small-basic-trans-mutex.md | 7 ++++--- .../kernel/kernel-small-basic-trans-queue.md | 5 +++-- .../kernel/kernel-small-basic-trans-semaphore.md | 3 ++- 10 files changed, 45 insertions(+), 26 deletions(-) diff --git a/zh-cn/device-dev/kernel/kernel-mini-appx-code.md b/zh-cn/device-dev/kernel/kernel-mini-appx-code.md index 3c92cc74ce..341817ed34 100644 --- a/zh-cn/device-dev/kernel/kernel-mini-appx-code.md +++ b/zh-cn/device-dev/kernel/kernel-mini-appx-code.md @@ -58,7 +58,7 @@ OsMuxInit ## 注释 -一般的，尽量通过清晰的软件架构，良好的符号命名来提高代码可读性；然后在需要的时候，才辅以注释说明。 +一般的，尽量通过清晰的软件架构，良好的符号命名来提高代码可读性；在需要的时候，辅以注释说明。 注释是为了帮助阅读者快速读懂代码，所以要从读者的角度出发，按需注释。 diff --git a/zh-cn/device-dev/kernel/kernel-mini-basic-ipc-event.md b/zh-cn/device-dev/kernel/kernel-mini-basic-ipc-event.md index ef398c9184..9a7c3c83e4 100644 --- a/zh-cn/device-dev/kernel/kernel-mini-basic-ipc-event.md +++ b/zh-cn/device-dev/kernel/kernel-mini-basic-ipc-event.md @@ -84,7 +84,7 @@ typedef struct tagEvent { > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** -> - 进行事件读写操作时，事件的第25位为保留位，不可以进行位设置。 +> - 进行事件读写操作时，事件的第25bit(`0x02U << 24`)为保留bit位，不可以进行位设置。 > > - 对同一事件反复写入，算作一次写入。 diff --git a/zh-cn/device-dev/kernel/kernel-mini-basic-ipc-queue.md b/zh-cn/device-dev/kernel/kernel-mini-basic-ipc-queue.md index f2e60ebd8b..1bafb4de87 100644 --- a/zh-cn/device-dev/kernel/kernel-mini-basic-ipc-queue.md +++ b/zh-cn/device-dev/kernel/kernel-mini-basic-ipc-queue.md @@ -7,7 +7,7 @@ 任务能够从队列里面读取消息，当队列中的消息为空时，挂起读取任务；当队列中有新消息时，挂起的读取任务被唤醒并处理新消息。任务也能够往队列里写入消息，当队列已经写满消息时，挂起写入任务；当队列中有空闲消息节点时，挂起的写入任务被唤醒并写入消息。 -可以通过调整读队列和写队列的超时时间来调整读写接口的阻塞模式，如果将读队列和写队列的超时时间设置为0，就不会挂起任务，接口会直接返回，这就是非阻塞模式。反之，如果将都队列和写队列的超时时间设置为大于0的时间，就会以阻塞模式运行。 +可以通过调整读队列和写队列的超时时间来调整读写接口的阻塞模式，如果将读队列和写队列的超时时间设置为0，就不会挂起任务，接口会直接返回，这就是非阻塞模式。反之，如果将读队列和写队列的超时时间设置为大于0的时间，就会以阻塞模式运行。 消息队列提供了异步处理机制，允许将一个消息放入队列，但不立即处理。同时队列还有缓冲消息的作用，可以使用队列实现任务异步通信，队列具有如下特性： diff --git a/zh-cn/device-dev/kernel/kernel-small-apx-bitwise.md b/zh-cn/device-dev/kernel/kernel-small-apx-bitwise.md index 68cc022a69..a94c73c188 100644 --- a/zh-cn/device-dev/kernel/kernel-small-apx-bitwise.md +++ b/zh-cn/device-dev/kernel/kernel-small-apx-bitwise.md @@ -14,9 +14,9 @@ | **功能分类** | **接口描述** | | -------- | -------- | -| 置1/清0标志位 | - LOS_BitmapSet:对状态字的某一标志位进行置1操作
- LOS_BitmapClr:对状态字的某一标志位进行清0操作 | -| 获取标志位为1的bit位 | - LOS_HighBitGet:获取状态字中为1的最高位
- LOS_LowBitGet:获取状态字中为1的最低位 | -| 连续bit位操作 | - LOS_BitmapSetNBits:对状态字的连续标志位进行置1操作
- LOS_BitmapClrNBits:对状态字的连续标志位进行清0操作
- LOS_BitmapFfz:获取从最低有效位开始的第一个0的bit位 | +| 置1/清0标志位 | - LOS_BitmapSet：对状态字的某一标志位进行置1操作
- LOS_BitmapClr：对状态字的某一标志位进行清0操作 | +| 获取标志位为1的bit位 | - LOS_HighBitGet：获取状态字中为1的最高位
- LOS_LowBitGet：获取状态字中为1的最低位 | +| 连续bit位操作 | - LOS_BitmapSetNBits：对状态字的连续标志位进行置1操作
- LOS_BitmapClrNBits：对状态字的连续标志位进行清0操作
- LOS_BitmapFfz：获取从最低有效位开始的第一个0的bit位 | ## 编程实例 @@ -34,7 +34,10 @@ 4. 获取标志位为1的最低bit位。 - +### 编程示例 + +本演示代码在./kernel/liteos_a/testsuites/kernel/src/osTest.c中编译验证，在TestTaskEntry中调用验证入口函数BitSample。 + ``` #include "los_bitmap.h" #include "los_printf.h" diff --git a/zh-cn/device-dev/kernel/kernel-small-apx-dll.md b/zh-cn/device-dev/kernel/kernel-small-apx-dll.md index d13c006214..782dd68968 100644 --- a/zh-cn/device-dev/kernel/kernel-small-apx-dll.md +++ b/zh-cn/device-dev/kernel/kernel-small-apx-dll.md @@ -17,10 +17,10 @@ | 增加节点 | - LOS_ListAdd：将指定节点插入到双向链表头端
- LOS_ListHeadInsert：将指定节点插入到双向链表头端，同LOS_ListAdd
- LOS_ListTailInsert：将指定节点插入到双向链表尾端 | | 增加链表 | - LOS_ListAddList：将指定链表的头端插入到双向链表头端
- LOS_ListHeadInsertList：将指定链表的头端插入到双向链表头端
- LOS_ListTailInsertList：将指定链表的尾端插入到双向链表头端 | | 删除节点 | - LOS_ListDelete：将指定节点从链表中删除
- LOS_ListDelInit：将指定节点从链表中删除，并使用该节点初始化链表 | -| 判断双向链表 | - LOS_ListEmpty：判断链表是否为空
- LOS_DL_LIST_IS_END：判断指定链表节点是否为链表尾端：LOS_DL_LIST_IS_ON_QUEUE：判断链表节点是否在双向链表里 | +| 判断双向链表 | - LOS_ListEmpty：判断链表是否为空
- LOS_DL_LIST_IS_END：判断指定链表节点是否为链表尾端
- LOS_DL_LIST_IS_ON_QUEUE：判断链表节点是否在双向链表里 | | 获取结构体信息 | - LOS_OFF_SET_OF：获取指定结构体内的成员相对于结构体起始地址的偏移量
- LOS_DL_LIST_ENTRY：获取双向链表中第一个链表节点所在的结构体地址，接口的第一个入参表示的是链表中的头节点，第二个入参是要获取的结构体名称，第三个入参是链表在该结构体中的名称
- LOS_ListPeekHeadType：获取双向链表中第一个链表节点所在的结构体地址，接口的第一个入参表示的是链表中的头节点，第二个入参是要获取的结构体名称，第三个入参是链表在该结构体中的名称。如果链表为空，返回NULL。
- LOS_ListRemoveHeadType：获取双向链表中第一个链表节点所在的结构体地址，并把第一个链表节点从链表中删除。接口的第一个入参表示的是链表中的头节点，第二个入参是要获取的结构体名称，第三个入参是链表在该结构体中的名称。如果链表为空，返回NULL。
- LOS_ListNextType：获取双向链表中指定链表节点的下一个节点所在的结构体地址。接口的第一个入参表示的是链表中的头节点，第二个入参是指定的链表节点，第三个入参是要获取的结构体名称，第四个入参是链表在该结构体中的名称。如果链表节点下一个为链表头结点为空，返回NULL。| -| 遍历双向链表 | - LOS_DL_LIST_FOR_EACH:遍历双向链表
- LOS_DL_LIST_FOR_EACH_SAFE:遍历双向链表，并存储当前节点的后继节点用于安全校验 | -| 遍历包含双向链表的结构体 | - LOS_DL_LIST_FOR_EACH_ENTRY:遍历指定双向链表，获取包含该链表节点的结构体地址
- LOS_DL_LIST_FOR_EACH_ENTRY_SAFE:遍历指定双向链表，获取包含该链表节点的结构体地址，并存储包含当前节点的后继节点的结构体地址 | +| 遍历双向链表 | - LOS_DL_LIST_FOR_EACH：遍历双向链表
- LOS_DL_LIST_FOR_EACH_SAFE：遍历双向链表，并存储当前节点的后继节点用于安全校验 | +| 遍历包含双向链表的结构体 | - LOS_DL_LIST_FOR_EACH_ENTRY：遍历指定双向链表，获取包含该链表节点的结构体地址
- LOS_DL_LIST_FOR_EACH_ENTRY_SAFE：遍历指定双向链表，获取包含该链表节点的结构体地址，并存储包含当前节点的后继节点的结构体地址 | ## 开发流程 @@ -48,10 +48,10 @@ > - 如果链表节点的内存是动态申请的，删除节点时，要注意释放内存。 - **编程实例** +## 编程实例 -**实例描述** +### 实例描述 本实例实现如下功能： @@ -64,7 +64,11 @@ 4. 测试操作是否成功。 +### 编程示例 +本演示代码在./kernel/liteos_a/testsuites/kernel/src/osTest.c中编译验证，在TestTaskEntry中调用验证入口函数ListSample + +示例代码如下： ``` #include "stdio.h" diff --git a/zh-cn/device-dev/kernel/kernel-small-apx-library.md b/zh-cn/device-dev/kernel/kernel-small-apx-library.md index 229046a8a1..0f06476a34 100644 --- a/zh-cn/device-dev/kernel/kernel-small-apx-library.md +++ b/zh-cn/device-dev/kernel/kernel-small-apx-library.md @@ -15,11 +15,19 @@ musl libc库支持POSIX标准，涉及的系统调用相关接口由OpenHarmony 标准库支持接口的详细情况请参考C库的API文档，其中也涵盖了与POSIX标准之间的差异说明。 -## 操作实例 +### 编程实例 + + +#### 实例描述 在本示例中，主线程创建了THREAD_NUM个子线程，每个子线程启动后等待被主线程唤醒，主线程成功唤醒所有子线程后，子线程继续执行直至生命周期结束，同时主线程通过pthread_join方法等待所有线程执行结束。 - +#### 编程示例 + +本演示代码在./kernel/liteos_a/testsuites/kernel/src/osTest.c中编译验证，在TestTaskEntry中调用验证入口函数testcase 或新建文件由主函数调用 + +示例代码如下： + ``` #include #include diff --git a/zh-cn/device-dev/kernel/kernel-small-basic-trans-event.md b/zh-cn/device-dev/kernel/kernel-small-basic-trans-event.md index 56737c6181..c5f5f696c3 100644 --- a/zh-cn/device-dev/kernel/kernel-small-basic-trans-event.md +++ b/zh-cn/device-dev/kernel/kernel-small-basic-trans-event.md @@ -15,7 +15,7 @@ OpenHarmony LiteOS-A的事件模块提供的事件，具有如下特点： - 任务通过创建事件控制块来触发事件或等待事件。 -- 事件间相互独立，内部实现为一个32位无符号整型，每一位标识一种事件类型。第25位不可用，因此最多可支持31种事件类型。 +- 事件间相互独立，内部实现为一个32位无符号整型，每一位标识一种事件类型。（0表示该时间类型未发生，1表示该事件类型已经发生，一共31种事件类型，第25bit位(`0x02U << 24`)系统保留） - 事件仅用于任务间的同步，不提供数据传输功能。 @@ -80,10 +80,10 @@ OpenHarmony LiteOS-A内核的事件模块提供下面几种功能。 | 功能分类 | 接口描述 | | -------- | -------- | | 初始化事件 | LOS_EventInit:初始化一个事件控制块 | -| 读/写事件 | - LOS_EventRead：读取指定事件类型，超时时间为相对时间：单位为Tick
- LOS_EventWrite:写指定的事件类型 | +| 读/写事件 | - LOS_EventRead：读取指定事件类型，超时时间为相对时间：单位为Tick
- LOS_EventWrite：写指定的事件类型 | | 清除事件 | LOS_EventClear:清除指定的事件类型 | -| 校验事件掩码 | - LOS_EventPoll:根据用户传入的事件ID、事件掩码及读取模式，返回用户传入的事件是否符合预期
- LOS_EventDestroy:销毁指定的事件控制块 | -| 销毁事件 | LOS_EventDestroy:销毁指定的事件控制块 | +| 校验事件掩码 | - LOS_EventPoll：根据用户传入的事件ID、事件掩码及读取模式，返回用户传入的事件是否符合预期
- LOS_EventDestroy:销毁指定的事件控制块 | +| 销毁事件 | LOS_EventDestroy：销毁指定的事件控制块 | ### 开发流程 @@ -103,7 +103,7 @@ OpenHarmony LiteOS-A内核的事件模块提供下面几种功能。 6. 事件控制块销毁 > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** -> - 进行事件读写操作时，事件的第25位为保留位，不可以进行位设置。 +> - 进行事件读写操作时，事件的第25bit(`0x02U << 24`)为保留bit位，不可以进行位设置。 > > - 对同一事件反复写入，算作一次写入。 @@ -128,9 +128,10 @@ OpenHarmony LiteOS-A内核的事件模块提供下面几种功能。 ### 编程示例 +本演示代码在./kernel/liteos_a/testsuites/kernel/src/osTest.c中编译验证，在TestTaskEntry中调用验证入口函数Example_EventEntry。 + 示例代码如下： - ``` #include "los_event.h" #include "los_task.h" diff --git a/zh-cn/device-dev/kernel/kernel-small-basic-trans-mutex.md b/zh-cn/device-dev/kernel/kernel-small-basic-trans-mutex.md index 8bebc6f1cb..cfa4fdba5e 100644 --- a/zh-cn/device-dev/kernel/kernel-small-basic-trans-mutex.md +++ b/zh-cn/device-dev/kernel/kernel-small-basic-trans-mutex.md @@ -87,7 +87,7 @@ ### 编程实例 -**实例描述** +#### 实例描述 本实例实现如下流程： @@ -99,10 +99,11 @@ 4. 100Tick休眠时间到达后，Example_MutexTask2被唤醒， 释放互斥锁，唤醒Example_MutexTask1。Example_MutexTask1成功获取到互斥锁后，释放，删除互斥锁。 -**示例代码** +#### 编程示例 -示例代码如下： +本演示代码在./kernel/liteos_a/testsuites/kernel/src/osTest.c中编译验证，在TestTaskEntry中调用验证入口函数Example_MutexEntry。 +示例代码如下： ``` #include diff --git a/zh-cn/device-dev/kernel/kernel-small-basic-trans-queue.md b/zh-cn/device-dev/kernel/kernel-small-basic-trans-queue.md index cdf3f64c4f..30003b1eb5 100644 --- a/zh-cn/device-dev/kernel/kernel-small-basic-trans-queue.md +++ b/zh-cn/device-dev/kernel/kernel-small-basic-trans-queue.md @@ -7,7 +7,7 @@ 任务能够从队列里面读取消息，当队列中的消息为空时，挂起读取任务；当队列中有新消息时，挂起的读取任务被唤醒并处理新消息。任务也能够往队列里写入消息，当队列已经写满消息时，挂起写入任务；当队列中有空闲消息节点时，挂起的写入任务被唤醒并写入消息。 -可以通过调整读队列和写队列的超时时间来调整读写接口的阻塞模式，如果将读队列和写队列的超时时间设置为0，就不会挂起任务，接口会直接返回，这就是非阻塞模式。反之，如果将都队列和写队列的超时时间设置为大于0的时间，就会以阻塞模式运行。 +可以通过调整读队列和写队列的超时时间来调整读写接口的阻塞模式，如果将读队列和写队列的超时时间设置为0，就不会挂起任务，接口会直接返回，这就是非阻塞模式。反之，如果将读队列和写队列的超时时间设置为大于0的时间，就会以阻塞模式运行。 消息队列提供了异步处理机制，允许将一个消息放入队列，但不立即处理。同时队列还有缓冲消息的作用，可以使用队列实现任务异步通信，队列具有如下特性： @@ -137,9 +137,10 @@ typedef struct { ### 编程示例 +本演示代码在./kernel/liteos_a/testsuites/kernel/src/osTest.c中编译验证，在TestTaskEntry中调用验证入口函数ExampleQueue。 + 示例代码如下： - ``` #include "los_task.h" #include "los_queue.h" diff --git a/zh-cn/device-dev/kernel/kernel-small-basic-trans-semaphore.md b/zh-cn/device-dev/kernel/kernel-small-basic-trans-semaphore.md index 2ab8ebb763..de95e53e7c 100644 --- a/zh-cn/device-dev/kernel/kernel-small-basic-trans-semaphore.md +++ b/zh-cn/device-dev/kernel/kernel-small-basic-trans-semaphore.md @@ -116,9 +116,10 @@ typedef struct { ### 编程示例 +本演示代码在./kernel/liteos_a/testsuites/kernel/src/osTest.c中编译验证，在TestTaskEntry中调用验证入口函数ExampleSem。 + 示例代码如下： - ``` #include "los_sem.h" #include "securec.h" -- GitLab