!6144 【OpenHarmony开源贡献者计划2022】update api documents.

Merge pull request !6144 from Mr_YX/master

!6144 【OpenHarmony开源贡献者计划2022】update api documents.
Merge pull request !6144 from Mr_YX/master
68396e7c · openharmony_ci · Gitee · c74ec1ed · 206c9555 · 68396e7c
3 changed file
--- a/zh-cn/device-dev/driver/driver-peripherals-vibrator-des.md
+++ b/zh-cn/device-dev/driver/driver-peripherals-vibrator-des.md
 # Vibrator
 ## 概述
 ### 功能简介
-为了快速开发传感器驱动，基于HDF（Hardware Driver Foundation）驱动框架开发了马达（Vibrator）驱动模型。马达驱动模型，屏蔽设备驱动与系统交互的实现，为硬件服务层提供统一稳定的驱动接口能力，为驱动开发者提供开放的接口和解析接口的能力。用于不同操作系统马达设备部件的部署指导和马达设备部件驱动的开发。马达驱动模型如图1所示：
+为了快速开发传感器驱动，基于HDF（Hardware Driver Foundation）驱动框架开发了马达（Vibrator）驱动模型。马达驱动模型，屏蔽设备驱动与系统交互的实现，为硬件服务层提供统一稳定的驱动接口能力，为驱动开发者提供开放的接口和解析接口的能力，用于不同操作系统马达设备部件的部署指导和马达设备部件驱动的开发。马达驱动模型如图1所示：
 **图 1** 马达驱动模型图
@@ -52,19 +51,19 @@
 ### 接口说明
-马达驱动模型支持静态HCS配置和动态参数两种振动效果配置能力。马达硬件服务调用StartOnce接口动态配置持续振动；调用Start接口启动静态配置的振动效果。马达驱动模型对HDI开放的API接口能力，如下所示。
+马达驱动模型支持静态HCS配置和动态参数两种振动效果配置能力。马达硬件服务调用StartOnce接口动态配置持续振动；调用Start接口启动静态配置的振动效果。马达驱动模型对HDI开放的API接口能力，如下表所示。
 **表 1** 马达驱动模型对外API接口能力介绍
 | 接口名                                  | 功能描述                                           |
-| -------------------------------------- | -------------------------------------------------------- |
+| -------------------------------------- | ------------------------------------------------ |
 | int32_t  StartOnce(uint32_t duration)  | 按照指定持续时间触发振动马达，duration为振动持续时长。   |
 | int32_t  Start(const char *effectType) | 按照指定预置效果启动马达，effectType表示预置的预置效果。 |
 | int32_t  Stop(enum VibratorMode mode)  | 按照指定的振动模式停止马达振动。                       |
 ### 开发步骤
-Vibrator驱动模型为上层马达硬件服务层提供稳定的马达控制能力接口，包括马达一次振动、马达效果配置震动、马达停止。基于HDF驱动框架开发的马达驱动模型，实现跨操作系统迁移、器件差异配置等功能。马达具体的开发步骤如下：
+Vibrator驱动模型为上层马达硬件服务层提供稳定的马达控制能力接口，包括马达一次振动、马达效果配置震动、马达停止。基于HDF驱动框架开发的马达驱动模型，实现跨操作系统迁移、器件差异配置等功能。具体的开发步骤如下：
 1. 基于HDF驱动框架，按照驱动Driver Entry程序，完成马达抽象驱动开发，主要由Bind、Init、Release、Dispatch函数接口实现，配置资源和HCS解析。
@@ -203,7 +202,7 @@ Vibrator驱动模型为上层马达硬件服务层提供稳定的马达控制能
   - 马达效果模型使用HCS作为配置描述源码，hcs配置文件字段详细介绍参考[配置管理](https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/driver/driver-hdf-manage.md)。
-     ```
+     ```hcs
     /* 马达数据配置模板（vibrator_config.hcs） */
     root {
         vibratorConfig {
@@ -367,6 +366,3 @@ Vibrator驱动模型为上层马达硬件服务层提供稳定的马达控制能
         return HDF_SUCCESS;
     }
     ```
\ No newline at end of file
--- a/zh-cn/device-dev/driver/driver-platform-dac-des.md
+++ b/zh-cn/device-dev/driver/driver-platform-dac-des.md
 # DAC
 ## 概述
 ### 功能简介
@@ -11,7 +10,6 @@ DAC接口定义了完成DAC传输的通用方法集合，包括：
 - DAC设备管理：打开或关闭DAC设备。
 - DAC设置目标值：设置DAC设备需要将数字信号转成模拟信号的目标值。
 ### 基本概念
 DAC模块支持数模转换的开发，它主要用于：
@@ -25,7 +23,7 @@ DAC模块支持数模转换的开发，它主要用于：
 - 转换精度
-  精度是指输入端加有最大数值时，DAC的实际输出值和理论计算值之差，DAC转换器的转换精度与DAC转换器的集成芯片结构和接口电路配置有关。理想情况下，DAC的转换精度越小越好，因此为了获得更高精度的DAC转换结果，首先要保证选择的DAC转换器具备足够高的分辨率。其次，接口电路的器件或电源存在误差时，会造成DAC转换的误差，当这些误差超过一定程度时，会导致DAC转换错误。
+  精度是指输入端加有最大数值时，DAC的实际输出值和理论计算值之差，DAC转换器的转换精度与DAC转换器的集成芯片结构和接口电路配置有关。理想情况下，DAC的转换精度越小越好，因此为了获得更高精度的DAC转换结果，首先要保证选择的DAC转换器具备足够高的分辨率。其次，接口电路的器件或电源存在误差时，会造成DAC转换的误差，若这些误差超过一定程度，就会导致DAC转换错误。
 - 转换速度
@@ -37,11 +35,11 @@ DAC模块支持数模转换的开发，它主要用于：
 ### 运作机制
-在HDF框架中，同类型设备对象较多时（可能同时存在十几个同类型配置器），如果采用独立服务模式则需要配置更多的设备节点，且相关服务会占据更多的内存资源。相反，采用统一服务模式可以使用一个设备服务作为管理器，统一处理所有同类型对象的外部访问（这会在配置文件中有所体现）,实现便捷管理和节约资源的目的。DAC模块接口适配模式采用统一服务模式，如图1所示。 
+在HDF框架中，同类型设备对象较多时（可能同时存在十几个同类型配置器），如果采用独立服务模式，则需要配置更多的设备节点，且相关服务会占据更多的内存资源。相反，采用统一服务模式可以使用一个设备服务作为管理器，统一处理所有同类型对象的外部访问（这会在配置文件中有所体现）,实现便捷管理和节约资源的目的。DAC模块接口适配模式采用统一服务模式，如图1所示。 
-DAC模块各分层的作用为：接口层提供打开设备，写入数据，关闭设备的接口。核心层主要提供绑定设备、初始化设备以及释放设备的能力。适配层实现其他具体的功能。
+DAC模块各分层的作用为：接口层提供打开设备、写入数据和关闭设备的接口。核心层主要提供绑定设备、初始化设备以及释放设备的能力。适配层实现其它具体的功能。
-![](../public_sys-resources/icon-note.gif) 说明：<br>核心层可以调用接口层的函数，核心层通过钩子函数调用适配层函数，从而适配层间接的可以调用接口层函数，但是不可逆转接口层调用适配层函数。
+![](../public_sys-resources/icon-note.gif) 说明：<br>核心层可以调用接口层的函数，核心层通过钩子函数调用适配层函数，从而适配层可以间接的调用接口层函数，但是不可逆转接口层调用适配层函数。
 **图 1**  DAC统一服务模式
@@ -49,13 +47,13 @@ DAC模块各分层的作用为：接口层提供打开设备，写入数据，
 ### 约束与限制
- DAC模块当前仅支持轻量和小型系统内核（LiteOS）。
+DAC模块当前仅支持轻量和小型系统内核（LiteOS）。
 ## 使用指导
 ### 场景介绍
- DAC模块的主要工作是以电流、电压或电荷的形式将数字信号转换为模拟信号，主要应用于音频设备中。日常所见的音响、耳机等，均使用DAC模块作为数模转换的通道。
+DAC模块的主要工作是以电流、电压或电荷的形式将数字信号转换为模拟信号，主要应用于音频设备中。日常所见的音响、耳机等，均使用DAC模块作为数模转换的通道。
 ### 接口说明
@@ -64,10 +62,10 @@ DAC模块提供的主要接口如下所示，更多关于接口的介绍请参
 **表 1**  DAC驱动API接口功能介绍
 | 接口名                                                              | 描述          |
-| :------------------------------------------------------------| :------------ |
+| ------------------------------------------------------------------ | ------------ |
-| DevHandle DacOpen(uint32_t number)                           | 打开DAC设备  |
+| DevHandle DacOpen(uint32_t number)                                 | 打开DAC设备。  |
-| void DacClose(DevHandle handle)                              | 关闭DAC设备  |
+| void DacClose(DevHandle handle)                                    | 关闭DAC设备。  |
-| int32_t DacWrite(DevHandle handle, uint32_t channel, uint32_t val) | 设置DA目标值 |
+| int32_t DacWrite(DevHandle handle, uint32_t channel, uint32_t val) | 设置DA目标值。 |
 ### 开发步骤
@@ -80,24 +78,22 @@ DAC模块提供的主要接口如下所示，更多关于接口的介绍请参
 在进行DA转换之前，首先要调用DacOpen打开DAC设备，打开函数如下所示：
-```
+```c++
 DevHandle DacOpen(uint32_t number);
 ```
 **表 2**  DacOpen参数和返回值描述
 | 参数       | 参数描述          |
-| ---------- | ----------------- |
+| --------- | ---------------- |
-| number     | DAC设备号         |
+| number    | DAC设备号。        |
 | **返回值** | **返回值描述**     |
-| NULL       | 打开DAC设备失败   |
+| NULL      | 打开DAC设备失败。  |
-| 设备句柄   | 打开的DAC设备句柄 |
+| 设备句柄   | 打开的DAC设备句柄。 |
 假设系统中存在2个DAC设备，编号从0到1，现在打开1号设备。
-```
+```c++
 DevHandle dacHandle = NULL;  /* DAC设备句柄 /
 /* 打开DAC设备 */
@@ -110,23 +106,22 @@ if (dacHandle == NULL) {
 #### 设置DA目标值
-```
+```c++
 int32_t DacWrite(DevHandle handle, uint32_t channel, uint32_t val);
 ```
 **表 3**  DacWrite参数和返回值描述
 | 参数       | 参数描述      |
-| ---------- | -------------- |
+| --------- | ------------ |
-| handle     | DAC设备句柄    |
+| handle    | DAC设备句柄。  |
-| channel    | DAC设备通道号  |
+| channel   | DAC设备通道号。|
-| val        | 设置DA的值     |
+| val       | 设置DA的值。   |
 | **返回值** | **返回值描述** |
-| 0          | 写入成功       |
+| 0         | 写入成功。     |
-| 负数       | 写入失败       |
+| 负数       | 写入失败。     |
-```
+```c++
 /* 通过DAC_CHANNEL_NUM设备通道写入目标val值 */ 
    ret = DacWrite(dacHandle, DAC_CHANNEL_NUM, val);
    if (ret != HDF_SUCCESS) {
@@ -139,24 +134,21 @@ int32_t DacWrite(DevHandle handle, uint32_t channel, uint32_t val);
 #### 关闭DAC设备
 DAC通信完成之后，需要关闭DAC设备，关闭函数如下所示：
-```
+```c++
 void DacClose(DevHandle handle);
 ```
 **表 4**  DacClose参数和返回值描述
 | 参数       | 参数描述      |
-| ---------- | -------------- |
+| --------- | ------------ |
-| handle     | DAC设备句柄    |
+| handle    | DAC设备句柄。  |
 | **返回值** | **返回值描述** |
 | void      | 无           |
 关闭DAC设备示例：
-```
+```c++
 DacClose(dacHandle); /* 关闭DAC设备 */
 ```
@@ -170,7 +162,7 @@ DAC设备的具体使用方式可以参考如下示例代码，示例代码步
 运行结果：根据输入的val通过打印日志得到输出的结果。
-```
+```c++
 #include "dac_if.h"          /* DAC标准接口头文件 */
 #include "hdf_log.h"         /* 标准日志打印头文件 */

--- a/zh-cn/device-dev/driver/driver-platform-dac-develop.md
+++ b/zh-cn/device-dev/driver/driver-platform-dac-develop.md
@@ -19,7 +19,7 @@ DAC模块支持数模转换的开发。它主要用于：
 - 转换精度
-  精度是指输入端加有最大数值时，DAC的实际输出值和理论计算值之差，DAC转换器的转换精度与DAC转换器的集成芯片结构和接口电路配置有关。理想情况下，DAC的转换精度越小越好，因此为了获得更高精度的DAC转换结果，首先要保证选择的DAC转换器具备足够高的分辨率。其次，要保证接口电路的器件或电源误差最小或者不存在误差，否则会造成DAC转换的误差，当这些误差超过一定程度时，会导致DAC转换错误。
+  精度是指输入端加有最大数值时，DAC的实际输出值和理论计算值之差，DAC转换器的转换精度与DAC转换器的集成芯片结构和接口电路配置有关。理想情况下，DAC的转换精度越小越好，因此为了获得更高精度的DAC转换结果，首先要保证选择的DAC转换器具备足够高的分辨率。其次，要保证接口电路的器件或电源误差最小或者不存在误差，否则会造成DAC转换的误差，若这些误差超过一定程度，就会导致DAC转换错误。
 - 转换速度
@@ -31,9 +31,9 @@ DAC模块支持数模转换的开发。它主要用于：
 ### 运作机制
-在HDF框架中，同类型设备对象较多时（可能同时存在十几个同类型配置器），若采用独立服务模式则需要配置更多的设备节点，且相关服务会占据更多的内存资源。相反，采用统一服务模式可以使用一个设备服务作为管理器，统一处理所有同类型对象的外部访问（这会在配置文件中有所体现）,实现便捷管理和节约资源的目的。DAC模块接口适配模式采用统一服务模式（如图1所示）。 
+在HDF框架中，同类型设备对象较多时（可能同时存在十几个同类型配置器），若采用独立服务模式，则需要配置更多的设备节点，且相关服务会占据更多的内存资源。相反，采用统一服务模式可以使用一个设备服务作为管理器，统一处理所有同类型对象的外部访问（这会在配置文件中有所体现）,实现便捷管理和节约资源的目的。DAC模块接口适配模式采用统一服务模式（如图1所示）。 
-DAC模块各分层的作用为：接口层提供打开设备，写入数据，关闭设备接口的能力。核心层主要提供绑定设备、初始化设备以及释放设备的能力。适配层实现其他具体的功能。
+DAC模块各分层的作用为：接口层提供打开设备、写入数据和关闭设备接口的能力。核心层主要提供绑定设备、初始化设备以及释放设备的能力。适配层实现其他具体的功能。
 ![](../public_sys-resources/icon-note.gif) 说明：<br>核心层可以调用接口层的函数，也可以通过钩子函数调用适配层函数，从而使得适配层间接的可以调用接口层函数，但是不可逆转接口层调用适配层函数。
@@ -41,18 +41,15 @@ DAC模块各分层的作用为：接口层提供打开设备，写入数据，
 ![](figures/统一服务模式结构图.png "DAC统一服务模式")
 ### 约束与限制
- DAC模块当前仅支持轻量和小型系统内核（LiteOS）。
+DAC模块当前仅支持轻量和小型系统内核（LiteOS）。
 ## 开发指导
 ### 场景介绍
-DAC模块主要在设备中数模转换，音频输出，电机控制等设备使用，设置将DAC模块传入的数字信号转换为输出模拟信号时需要用到DAC数模转换驱动。
+DAC模块主要在设备中数模转换、音频输出和电机控制等设备使用，设置将DAC模块传入的数字信号转换为输出模拟信号时需要用到DAC数模转换驱动。
 ### 接口说明
@@ -60,7 +57,7 @@ DAC模块主要在设备中数模转换，音频输出，电机控制等设备
 DacMethod定义：
-```
+```c++
 struct DacMethod {
    // 写入数据的钩子函数
    int32_t (*write)(struct DacDevice *device, uint32_t channel, uint32_t val);
@@ -73,32 +70,32 @@ struct DacMethod {
 **表 1**  DacMethod结构体成员的回调函数功能说明
 | 函数成员 | 入参                                                         | 出参 | 返回值             | 功能           |
 | -------- | ------------------------------------------------------------ | ---- | ------------------ | -------------- |
 | write    | device：结构体指针，核心层DAC控制器<br>channel：uint32_t，传入的通道号<br>val：uint32_t，要传入的数据 | 无   | HDF_STATUS相关状态 | 写入DA的目标值 |
 | start    | device：结构体指针，核心层DAC控制器                        | 无   | HDF_STATUS相关状态 | 开启DAC设备    |
 | stop     | device：结构体指针，核心层DAC控制器                        | 无   | HDF_STATUS相关状态 | 关闭DAC设备    |
 ### 开发步骤
 DAC模块适配包含以下四个步骤：
- 实例化驱动入口。
+1. 实例化驱动入口。
- 配置属性文件。
+2. 配置属性文件。
- 实例化核心层接口函数。
+3. 实例化核心层接口函数。
- 驱动调试。
+4. 驱动调试。
+### 开发实例
+下方将展示厂商需要提供哪些内容来完整实现设备功能。
 1.  实例化驱动入口：
-    驱动开发首先需要实例化驱动入口，驱动入口必须为HdfDriverEntry（在 hdf_device_desc.h 中定义）类型的全局变量，且moduleName要和device_info.hcs中保持一致。 HDF框架会汇总所有加载的驱动的HdfDriverEntry对象入口 ，形成一个类似数组的段地址空间，方便上层调用。
+    驱动开发首先需要实例化驱动入口，驱动入口必须为HdfDriverEntry（在hdf_device_desc.h中定义）类型的全局变量，且moduleName要和device_info.hcs中保持一致。HDF框架会汇总所有加载的驱动的HdfDriverEntry对象入口，形成一个类似数组的段地址空间，方便上层调用。
    一般在加载驱动时HDF会先调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。
-    ```
+    ```c++
    static struct HdfDriverEntry g_dacDriverEntry = {
        .moduleVersion = 1,
        .Init = VirtualDacInit,
@@ -117,19 +114,19 @@ DAC模块适配包含以下四个步骤：
     由于采用了统一服务模式，device_info.hcs文件中第一个设备节点必须为DAC管理器，其各项参数必须如下设置：
     | 成员名           | 值                                                                  |
-     | --------------- | ------------------------------------------------------------ |
+     | --------------- | ------------------------------------------------------------------- |
-     | policy          | 具体配置为0，不发布服务|
+     | policy          | 具体配置为0，不发布服务                                                |
     | priority        | 驱动启动优先级（0-200），值越大优先级越低，优先级相同则不保证device的加载顺序。|
-     | permission      | 驱动权限|
+     | permission      | 驱动权限                                                             |
-     | moduleName      | 固定为HDF_PLATFORM_DAC_MANAGER|
+     | moduleName      | 固定为HDF_PLATFORM_DAC_MANAGER                                       |
-     | serviceName     | 固定为HDF_PLATFORM_DAC_MANAGER|
+     | serviceName     | 固定为HDF_PLATFORM_DAC_MANAGER                                       |
-     | deviceMatchAttr | 没有使用，可忽略|
+     | deviceMatchAttr | 没有使用，可忽略                                                       |
     从第二个节点开始配置具体DAC控制器信息，此节点并不表示某一路DAC控制器，而是代表一个资源性质设备，用于描述一类DAC控制器的信息。本例只有一个DAC设备，如有多个设备，则需要在device_info文件增加deviceNode信息，以及在dac_config文件中增加对应的器件属性。
        device_info.hcs配置参考。
-        ```
+        ```hcs
        root {
            device_dac :: device {
                // device0是DAC管理器
@@ -156,7 +153,7 @@ DAC模块适配包含以下四个步骤：
    - 添加dac_test_config.hcs器件属性文件 
    在vendor/vendor_hisilicon/hispark_taurus/hdf_config/hdf_test/xxx_test_config.hcs目录下新增文件用于驱动配置参数，（例如：vendor/vendor_hisilicon/hispark_taurus/hdf_config/hdf_test/dac_test_config.hcs）其中配置参数如下：
-        ```
+        ```hcs
        root {
            platform {
            dac_config {
@@ -181,7 +178,7 @@ DAC模块适配包含以下四个步骤：
        在VirtualDacParseAndInit函数中对DacDevice成员进行初始化操作。
-        ```
+        ```c++
        // 虚拟驱动自定义结构体
        struct VirtualDacDevice {
        // DAC设备结构体
@@ -243,13 +240,11 @@ DAC模块适配包含以下四个步骤：
       }
       ```
    - 自定义结构体参考。
      通过自定义结构体定义DAC数模转换必要的参数，在定义结构体时需要根据设备的功能参数来实现自定义结构体，从驱动的角度看，自定义结构体是参数和数据的载体，dac_config.hcs文件中传递的参数和数据会被HDF驱动模块的DacTestReadConfig函数读入，通过DeviceResourceIface来初始化结构体成员，其中一些重要数值也会传递给核心层DacDevice对象，例如设备号、总线号等。
-      ```
+      ```c++
      struct VirtualDacDevice {
          struct DacDevice device; //【必要】是核心层控制对象，具体描述见下面
          uint32_t deviceNum;      //【必要】设备号
@@ -270,10 +265,9 @@ DAC模块适配包含以下四个步骤：
    - 实例化DacDevice成员DacMethod。
        VirtualDacWrite、VirtualDacStop、VirtualDacStart函数会在dac_virtual.c文件中进行模块功能的实例化。
-        ```
+        ```c++
        static const struct DacMethod g_method = {
            .write = VirtualDacWrite, // DAC设备写入值
            .stop = VirtualDacStop, // 停止DAC设备
@@ -284,7 +278,6 @@ DAC模块适配包含以下四个步骤：
        ![](../public_sys-resources/icon-note.gif) **说明：**<br>
         DacDevice成员DacMethod的定义和成员说明见[接口说明](#接口说明)。
    - Init函数参考
        入参：
@@ -293,22 +286,22 @@ DAC模块适配包含以下四个步骤：
        返回值：
-        HDF_STATUS相关状态（下表为部分展示，如需使用其他状态，可见//drivers/framework/include/utils/hdf_base.h中HDF_STATUS 定义）。
+        HDF_STATUS相关状态（下表为部分展示，如需使用其他状态，可见//drivers/framework/include/utils/hdf_base.h中HDF_STATUS定义）。
        | 状态(值)                | 问题描述       |
-        | ---------------------- | -------------- |
+        | ---------------------- | ------------- |
-        | HDF_ERR_INVALID_OBJECT | 控制器对象非法 |
+        | HDF_ERR_INVALID_OBJECT | 控制器对象非法。 |
-        | HDF_ERR_INVALID_PARAM  | 参数非法       |
+        | HDF_ERR_INVALID_PARAM  | 参数非法。      |
-        | HDF_ERR_MALLOC_FAIL    | 内存分配失败   |
+        | HDF_ERR_MALLOC_FAIL    | 内存分配失败。   |
-        | HDF_ERR_IO             | I/O 错误       |
+        | HDF_ERR_IO             | I/O 错误。     |
-        | HDF_SUCCESS            | 传输成功       |
+        | HDF_SUCCESS            | 传输成功。      |
-        | HDF_FAILURE            | 传输失败       |
+        | HDF_FAILURE            | 传输失败。      |
        函数说明：
      初始化自定义结构体对象，初始化DacDevice成员，并调用核心层DacDeviceAdd函数。
-      ```
+      ```c++
      static int32_t VirtualDacParseAndInit(struct HdfDeviceObject *device, const struct DeviceResourceNode *node)
      {
          // 定义返回值参数
@@ -400,7 +393,7 @@ DAC模块适配包含以下四个步骤：
          释放内存和删除控制器，该函数需要在驱动入口结构体中赋值给Release接口，当HDF框架调用Init函数初始化驱动失败时，可以调用Release释放驱动资源。所有强制转换获取相应对象的操作前提是在Init函数中具备对应赋值的操作。
-        ```
+        ```c++
        static void VirtualDacRemoveByNode(const struct DeviceResourceNode *node)
        {
            // 定义返回值参数
@@ -464,5 +457,3 @@ DAC模块适配包含以下四个步骤：
 4. 驱动调试：
   【可选】针对新增驱动程序，建议验证驱动基本功能，例如挂载后的测试用例是否成功等。
\ No newline at end of file