!3978 【OpenHarmony开源贡献者计划2022】Pin等相关格式及表达问题

Merge pull request !3978 from king_he/peripheral-2

zh-cn/device-dev/driver/driver-peripherals-external-des.md

@@ -3,25 +3,35 @@
 
 ## 概述
 
-WLAN是基于HDF（Hardware Driver Foundation）驱动框架开发的模块，该模块可实现跨操作系统迁移，自适应器件差异，模块化拼装编译等功能。各WLAN厂商驱动开发人员可根据WLAN模块提供的向下统一接口适配各自的驱动代码，实现如下能力：建立/关闭WLAN热点、扫描、关联WLAN热点等；对HDI层向上提供能力如下：设置MAC地址、设置发射功率、获取设备的MAC地址等。WLAN模块框架图如下：
+WLAN是基于HDF（Hardware Driver Foundation）驱动框架开发的模块，可实现跨操作系统迁移，自适应器件差异，模块化拼装编译等功能。各WLAN厂商驱动开发人员可根据WLAN模块提供的向下统一接口适配各自的驱动代码，实现如下能力：建立/关闭WLAN热点、扫描、关联WLAN热点等；对HDI层向上提供能力如下：设置MAC地址、设置发射功率、获取设备的MAC地址等。WLAN模块框架图如下：
 
   **图1** WLAN框架
 
   ![image](figures/WLAN框架.png "WLAN框架")
 
   **图2** WLAN Driver框架
+
   ![zh-cn_image_0000001300092359](figures/zh-cn_image_0000001300092359.png)
 
-1.WLAN Message：该部件为每个服务单独提供业务接口，每个服务也可依赖其他服务形成组合业务接口，此模块支持在用户态、内核态和MCU环境运行，实现组件间的充分解耦。
-2.WLAN Configuration Core：WLAN相关的配置文件进行解析。
-3.AP：AP为WLAN终端提供外部接入入口的设备。
-4.STA：STA为接入WLAN系统的终端。
-5.Mac80211：定义底层驱动相关的MAC层接口。
-6.Bus：该驱动模块向上提供统一的总线抽象接口。通过向下调用Platform层提供的SDIO接口和封装适配USB、PCIE接口，屏蔽不同内核的差异；通过对不同类型的总线操作进行统一封装，屏蔽不同芯片差异，能够对不同芯片厂商提供完备的总线驱动能力，不同厂商共用此模块接口，从而使厂商的开发更为便捷和统一。
-7.NetDevice：用于建立专属网络设备，屏蔽不同OS的差异，对WiFi驱动提供统一接口，提供统一的HDF NetDevice数据结构，及其统一管理、注册、去注册能力；对接轻设备及富设备上的Linux的网络设备层。
-8.NetBuf：该部件为WLAN驱动提供Linux或者LiteOS原生的网络数据缓冲的统一数据结构的封装以及对网络数据的操作接口的封装。
-9.FlowCtl：流控模块。
-10.HCC-CFG：WLAN相关参数配置其中包括板级配置、驱动配置、Module配置。
+1. WLAN Message：该部件为每个服务单独提供业务接口，每个服务也可依赖其他服务形成组合业务接口，此模块支持在用户态、内核态和MCU环境运行，实现组件间的充分解耦。
+
+2. WLAN Configuration Core：WLAN相关的配置文件进行解析。
+
+3. AP：AP为WLAN终端提供外部接入入口的设备。
+
+4. STA：STA为接入WLAN系统的终端。
+
+5. Mac80211：定义底层驱动相关的MAC层接口。
+
+6. Bus：该驱动模块向上提供统一的总线抽象接口。通过向下调用Platform层提供的SDIO接口和封装适配USB、PCIE接口，屏蔽不同内核的差异；通过对不同类型的总线操作进行统一封装，屏蔽不同芯片差异，能够对不同芯片厂商提供完备的总线驱动能力，不同厂商共用此模块接口，从而使厂商的开发更为便捷和统一。
+
+7. NetDevice：用于建立专属网络设备，屏蔽不同OS的差异，对WiFi驱动提供统一接口，提供统一的HDF NetDevice数据结构，及其统一管理、注册、去注册能力；对接轻设备及富设备上的Linux的网络设备层。
+
+8. NetBuf：该部件为WLAN驱动提供Linux或者LiteOS原生的网络数据缓冲的统一数据结构的封装以及对网络数据的操作接口的封装。
+
+9. FlowCtl：流控模块。
+
+10. HCC-CFG：WLAN相关参数配置其中包括板级配置、驱动配置、Module配置。
 
 ### WLAN驱动接口架构
 
@@ -33,7 +43,7 @@ WLAN模块有三部分对外开放的API接口，如下图所示：
 
 3. 提供给各厂商实现的能力接口。
 
-  **图2** WLAN模块开放能力分布图
+  **图3** WLAN模块开放能力分布图
 
   ![image](figures/WLAN模块开放能力分布图.png "WLAN模块开放能力分布图")
 
@@ -111,9 +121,9 @@ WLAN驱动模块对HDI层提供的能力接口，主要功能有：创建/销毁
 WLAN驱动基于HDF框架和PLATFORM框架开发，不区分OS和芯片平台，为不同厂商的WLAN模组提供统一的驱动模型，各WLAN模组厂商根据如下指导适配WLAN驱动框架。
 
 
-1. 通过wifi_config.hcs文件，配置硬件参数：module(不同feature)，芯片等。
+1. 通过wifi_config.hcs文件，配置硬件参数：module（不同feature）、芯片等。
 
-2. 解析配置文件， 生成全量配置的结构体对象。
+2. 解析配置文件，生成全量配置的结构体对象。
 
 3. Module初始化，创建Module。
 
@@ -124,7 +134,7 @@ WLAN驱动基于HDF框架和PLATFORM框架开发，不区分OS和芯片平台，
 6. 上层wpa业务挂接。
 
 
-> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
+> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**<br>
 > 以上驱动框架适配步骤一部分已经提供（详细见开发实例），待开发人员实现的部分有：1、根据硬件，修改配置参数；2、适配挂接chip；3、测试自验证。
 
 
@@ -142,7 +152,7 @@ hisi :& deviceList {
         powers {
             power0 {
                 powerSeqDelay = 0;  /* 电源序列延时 */
-                powerType = 1;      /* 电源类型：0--总是打开;1--GPIO */
+                powerType = 1;      /* 电源类型：0--总是打开；1--GPIO */
                 gpioId = 1;         /* GPIO管脚号 */
                 activeLevel=1;      /* 有效电平：0--低；1--高 */
             }
@@ -184,7 +194,7 @@ root {
 }
 ```
 
-  2、适配挂接WLAN芯片的初始化和去初始化、WLAN芯片驱动的初始化和去初始化
+  2、适配挂接WLAN芯片的初始化和去初始化、WLAN芯片驱动的初始化和去初始化。
 
 ```
 /* WLAN初始化挂接流程 */
@@ -400,7 +410,7 @@ int32_t Hi3881Deinit(struct HdfChipDriver *chipDriver, struct NetDevice *netDevi
 }
 ```
 
-  3、在芯片侧初始化过程中调用netdev的init和add接口进行初始化netdev，并挂接netdev的一些函数指针
+  3、在芯片侧初始化过程中调用netdev的init和add接口进行初始化netdev，并挂接netdev的一些函数指针。
 
 ```
 hi_s32 wal_init_drv_wlan_netdev(nl80211_iftype_uint8 type, wal_phy_mode mode, hi_char* ifname, hi_u32* len)
@@ -408,7 +418,7 @@ hi_s32 wal_init_drv_wlan_netdev(nl80211_iftype_uint8 type, wal_phy_mode mode, hi
     oal_net_device_stru *netdev          = HI_NULL;
 
     ......
-    /* 初始化网络设备，获取对应的实例。*/
+    /* 初始化网络设备，获取对应的实例 */
     netdev = NetDeviceInit(ifname, *len, LITE_OS);
     oal_wireless_dev *wdev = (oal_wireless_dev *)oal_mem_alloc(OAL_MEM_POOL_ID_LOCAL, sizeof(oal_wireless_dev));
     ret = wal_init_netif(type, netdev, wdev);
@@ -417,7 +427,7 @@ hi_s32 wal_init_drv_wlan_netdev(nl80211_iftype_uint8 type, wal_phy_mode mode, hi
 
     return HI_SUCCESS;
 }
-/* 挂接netdev的一些函数指针,详细挂接函数{@link NetDeviceInterFace} */
+/* 挂接netdev的一些函数指针，详细挂接函数{@link NetDeviceInterFace} */
 oal_net_device_ops_stru g_wal_net_dev_ops =
 {
     .getStats          = wal_netdev_get_stats,

zh-cn/device-dev/driver/driver-peripherals-face_auth-des.md

@@ -206,7 +206,7 @@ Face_auth驱动的主要工作是为上层用户认证框架和Face_auth服务
        .Release = HdfFaceAuthInterfaceDriverRelease,
    };
    
-   // 调用HDF_INIT将驱动入口注册到HDF框架中，在加载驱动时HDF框架会先调用Bind函数,再调用Init函数加载该驱动，当Init调用异常时，HDF框架会调用Release释放驱动资源并退出
+   // 调用HDF_INIT将驱动入口注册到HDF框架中。在加载驱动时HDF框架会先调用Bind函数，再调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出
    HDF_INIT(g_faceAuthInterfaceDriverEntry);
    ```
 

zh-cn/device-dev/driver/driver-peripherals-lcd-des.md

@@ -175,7 +175,7 @@ LCD器件驱动示例如下：
 #define VERTICAL_SYNC_WIDTH       2
 #define FRAME_RATE                60
 
-/* Panel Info结构体结构体 */
+/* PanelInfo结构体结构体 */
 struct PanelInfo {
     uint32_t width;
     uint32_t height;

zh-cn/device-dev/driver/driver-peripherals-light-des.md

-# LIGHT
+# Light
 
 
 ## 概述
 
 ### 功能简介
 
-​        Light驱动模型为上层Light硬件服务层提供稳定的灯控制能力接口，包括获取灯类型、配置点灯模式、配置灯闪烁效果、点灯、熄灯等。基于HDF（Hardware Driver Foundation）驱动框架开发的Light驱动模型，实现跨操作系统迁移，器件差异配置等功能。实现Light驱动“一次开发，多系统部署”的目标。Light驱动模型如图1示：
+Light驱动模型为上层Light硬件服务层提供稳定的灯控制能力接口，包括获取灯类型、配置点灯模式、配置灯闪烁效果、点灯、熄灯等。基于HDF（Hardware Driver Foundation）驱动框架开发的Light驱动模型，实现跨操作系统迁移，器件差异配置等功能。实现Light驱动“一次开发，多系统部署”的目标。Light驱动模型如图1示：
 
 **图 1**  Light驱动模型图
 
@@ -21,8 +21,8 @@
 
 Light驱动模型以标准系统Hi3516DV300为例，介绍整个驱动加载及运行流程：
 
-1. 从device info HCS 的Light Host里读取Light设备管理配置信息。
-2. 从light_config HCS读取Light数据配置信息。
+1. 从device_info.hcs配置文件的Light Host里读取Light设备管理配置信息。
+2. 从light_config.hcs配置文件读取Light数据配置信息。
 3. 解析Light设备管理配置信息，并关联对应设备驱动。
 4. 客户端下发Light Stub控制到服务端。
 5. 服务端调用Light Stub控制。
@@ -36,7 +36,7 @@ Light驱动模型以标准系统Hi3516DV300为例，介绍整个驱动加载及
 
 ### 接口说明
 
-Light驱动模型支持获取系统中所有灯的信息，动态配置闪烁模式和闪烁时间的能力。Light硬件服务调用GetLightInfo获取Light设备的基本信息；调用TurnOnLight接口启动配置的闪烁效果。Light驱动模型对外开放的API接口能力，参考表1。
+Light驱动模型支持获取系统中所有灯的信息，动态配置闪烁模式和闪烁时间的能力。Light Hardware服务调用GetLightInfo获取Light设备的基本信息；调用TurnOnLight接口启动配置的闪烁效果。Light驱动模型对外开放的API接口能力，参考表1。
 
 **表1**  Light驱动模型对外API接口能力介绍
 
@@ -47,10 +47,10 @@ Light驱动模型支持获取系统中所有灯的信息，动态配置闪烁模
 | int32_t (*TurnOffLight)(uint32_t type)                       | 根据指定的灯类型关闭灯列表中可用的灯。                       |
 
 ### 开发步骤
-1. 基于HDF驱动框架，按照驱动Driver Entry程序，完成Light抽象驱动开发（主要由Bind、Init、Release、Dispatch函数接口实现），资源配置及HCS解析。完成Light驱动的设备信息配置。
+1. 基于HDF驱动框架，按照驱动Driver Entry程序，完成Light抽象驱动开发（主要由Bind、Init、Release、Dispatch函数接口实现），资源配置及HCS配置文件解析。完成Light驱动的设备信息配置。
 
    - 调用HDF_INIT将驱动入口注册到HDF框架中。在加载驱动时HDF框架会先调用Bind函数，再调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。
-     Light驱动模型使用HCS作为配置描述源码，HCS配置字段详细介绍请参考[配置管理](https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/driver/driver-hdf-manage.md)。
+     Light驱动模型使用HCS配置文件作为配置描述源码。HCS配置字段详细介绍请参考[配置管理](https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/driver/driver-hdf-manage.md)。
      其Driver Entry入口函数定义如下:
 
      ```c
@@ -153,15 +153,15 @@ Light驱动模型支持获取系统中所有灯的信息，动态配置闪烁模
      }
      ```
 
-   - Light设备管理模块负责系统中Light器件接口发布，在系统启动过程中，HDF框架机制通过灯Host里设备HCS配置信息，加载设备管理驱动。
+   - Light设备管理模块负责系统中Light器件接口发布。在系统启动过程中，HDF框架机制通过Light Host里设备HCS配置信息，加载设备管理驱动。
 
      ```
-     /* 灯设备HCS配置 */
+     /* Light设备HCS配置 */
      device_light :: device {
          device0 :: deviceNode {
-             policy = 2; // 驱动服务发布的策略（0：不提供服务，1：对内核态发布服务，2：对内核态和用户态都发布服务）
+             policy = 2; // 驱动服务发布的策略（0：不提供服务，1：对内核态发布服务；2：对内核态和用户态都发布服务）
              priority = 100; // Light驱动启动优先级（0-200），值越大优先级越低，建议配置为100，优先级相同则不保证device的加载顺序
-             preload = 0; // 驱动按需加载字段，0表示加载，2表示不加载
+             preload = 0; // 驱动按需加载字段，0：加载；2：不加载
              permission = 0664;  // 驱动创建设备节点权限
              moduleName = "HDF_LIGHT"; // Light驱动名称，该字段的值必须和驱动入口结构的moduleName值一致
              serviceName = "hdf_light"; // Light驱动对外发布服务的名称，必须唯一
@@ -176,11 +176,11 @@ Light驱动模型支持获取系统中所有灯的信息，动态配置闪烁模
    static int32_t ParseLightInfo(const struct DeviceResourceNode *node)
    {
        .....
-       /* 从HCS获取支持灯的类型个数 */
+       /* 从HCS配置获取支持灯的类型个数 */
        drvData->lightNum = parser->GetElemNum(light, "lightType");
        ....
        for (i = 0; i < drvData->lightNum; ++i) {
-       /* 获取类型 */
+       /* 获取灯的类型 */
        ret = parser->GetUint32ArrayElem(light, "lightType", i, &temp, 0);
        CHECK_LIGHT_PARSER_RESULT_RETURN_VALUE(ret, "lightType");
        }
@@ -210,7 +210,7 @@ Light驱动模型支持获取系统中所有灯的信息，动态配置闪烁模
    static int32_t GetAllLightInfo(struct HdfSBuf *data, struct HdfSBuf *reply)
    {
        .....
-       /* 获取Light类型个数 */
+       /* 获取灯的类型个数 */
        if (!HdfSbufWriteUint32(reply, drvData->lightNum)) {
            HDF_LOGE("%s: write sbuf failed", __func__);
            return HDF_FAILURE;
@@ -253,7 +253,7 @@ Light驱动模型支持获取系统中所有灯的信息，动态配置闪烁模
        /* 闪烁模式 */
        if (buf->flashEffect.flashMode == LIGHT_FLASH_TIMED) {
            drvData->info[lightType]->lightState = LIGHT_STATE_START;
-           /* 用户设置的闪烁时间小于系统支持的最短时间，采用系统配置的时间(HCS配置) */
+           /* 用户设置的闪烁时间小于系统支持的最短时间，采用系统配置的时间（HCS配置） */
            drvData->info[lightType]->onTime = buf->flashEffect.onTime < drvData->info[lightType]->onTime ?
            drvData->info[lightType]->onTime : buf->flashEffect.onTime;
            drvData->info[lightType]->offTime = buf->flashEffect.offTime < drvData->info[lightType]->offTime ?
@@ -298,7 +298,7 @@ Light驱动模型支持获取系统中所有灯的信息，动态配置闪烁模
 驱动开发完成后，在灯单元测试里面开发自测试用例，验证驱动基本功能。测试环境采用开发者自测试平台。
 
 ```c++
-/* 用例执行前，初始化灯接口实例 */
+/* 用例执行前，初始化Light接口实例 */
 void HdfLightTest::SetUpTestCase()
 {
     g_lightDev = NewLightInterfaceInstance();
@@ -320,7 +320,7 @@ void HdfLightTest::TearDownTestCase()
     }
 }
 
-/* 测试灯获取类型 */
+/* 获取测试灯类型 */
 HWTEST_F(HdfLightTest, GetLightList001, TestSize.Level1)
 {
     struct LightInfo *info = nullptr;

zh-cn/device-dev/driver/driver-peripherals-pinauth-des.md

@@ -6,7 +6,7 @@
 
 口令认证是端侧设备不可或缺的一部分，为设备提供一种用户认证能力，可应用于设备解锁、支付、应用登录等身份认证场景。用户注册口令后，口令认证模块就可为设备提供密码解锁的功能，保证设备的安全使用。口令识别的整体架构如图1。
 
-基于HDF（Hardware Driver Foundation）驱动框架开发的pin_auth驱动，pin_auth驱动模型屏蔽硬件差异，为上层用户IAM子系统基础框架和口令认证SA提供稳定的口令认证基础能力，包括口令认证执行器列表查询、执行器信息查询、指定模板防暴信息查询、用户认证和执行器间的模板信息对账，以及口令的录入、认证、删除。
+基于HDF（Hardware Driver Foundation）驱动框架开发的Pin_auth驱动，Pin_auth驱动模型屏蔽硬件差异，为上层用户IAM子系统基础框架和口令认证SA提供稳定的口令认证基础能力，包括口令认证执行器列表查询、执行器信息查询、指定模板防暴信息查询、用户认证和执行器间的模板信息对账，以及口令的录入、认证、删除。
 
 **图1** 口令认证架构图
 
@@ -76,13 +76,13 @@ Pin_auth驱动的主要工作是为上层用户认证框架和Pin_auth服务提
 | GetExecutorList(std::vector<sptr<IExecutor>>& executorList)  | 获取执行器列表。                                             |
 | GetExecutorInfo(ExecutorInfo& info)                          | 获取执行器信息。                                             |
 | GetTemplateInfo(uint64_t templateId, TemplateInfo& info)     | 获取指定templateId的模板信息。                               |
-| OnRegisterFinish(const std::vector<uint64_t>& templateIdList,<br/>        const std::vector<uint8_t>& frameworkPublicKey,<br/>        const std::vector<uint8_t>&  extraInfo) | 执行器注册成功后，获取用户认证框架的公钥信息；获取用户认证框架的template 列表用于对账。 |
+| OnRegisterFinish(const std::vector<uint64_t>& templateIdList,<br/>const std::vector<uint8_t>& frameworkPublicKey,<br/>const std::vector<uint8_t>&  extraInfo) | 执行器注册成功后，获取用户认证框架的公钥信息；获取用户认证框架的template 列表用于对账。 |
 | OnSetData(uint64_t scheduleId, uint64_t authSubType, <br/>const std::vector<uint8_t> &data) | 用于回调传pin码认证的子类型和脱敏数据。                      |
-| Enroll(uint64_t scheduleId, const std::vector<uint8_t>& extraInfo,<br/>const sptr<IExecutorCallback>& callbackObj) | pin码录入操作。                                              |
-| Authenticate(uint64_t scheduleId, uint64_t templateId, const std::vector<uint8_t>& extraInfo, const sptr<IExecutorCallback>& callbackObj) | pin码认证操作。                                              |
+| Enroll(uint64_t scheduleId, const std::vector<uint8_t>& extraInfo,<br/>const sptr<IExecutorCallback>& callbackObj) | 录入pin码。                                              |
+| Authenticate(uint64_t scheduleId, uint64_t templateId, const std::vector<uint8_t>& extraInfo, const sptr<IExecutorCallback>& callbackObj) | pin码认证。                                              |
 | Delete(uint64_t templateId)                                  | 删除pin码模板。                                              |
 | Cancel(uint64_t scheduleId)                                  | 通过scheduleId取消指定操作。                                 |
-| SendCommand(int32_t commandId, const std::vector<uint8_t>& extraInfo,<br/>const sptr<IExecutorCallback>& callbackObj) | pin码预留接口。                                              |
+| SendCommand(int32_t commandId, const std::vector<uint8_t>& extraInfo,<br/>const sptr<IExecutorCallback>& callbackObj) | 预留接口。                                              |
 
 **表2** 回调函数介绍
 
@@ -262,7 +262,7 @@ Pin_auth驱动的主要工作是为上层用户认证框架和Pin_auth服务提
        ScheduleMap scheduleMap_;
    };
    
-   // 获取执行器列表实现，创建执行器 （仅作示例）
+   // 获取执行器列表实现，创建执行器（仅作示例）
    int32_t PinAuthInterfaceService::GetExecutorList(std::vector<sptr<IExecutor>> &executorList)
    {
        IAM_LOGI("start");
@@ -340,7 +340,7 @@ Pin_auth驱动的主要工作是为上层用户认证框架和Pin_auth服务提
        return HDF_SUCCESS;
    }
    
-   // 实现执行器注册成功后，获取用户认证框架的公钥信息、获取用户认证框架的template 列表接口,将公钥信息保持，template 列表用于和本地的template做对账
+   // 实现执行器注册成功后，获取用户认证框架的公钥信息、获取用户认证框架的template 列表接口,将公钥信息保持，template列表用于和本地的template做对账
    int32_t ExecutorImpl::OnRegisterFinish(const std::vector<uint64_t> &templateIdList,
        const std::vector<uint8_t> &frameworkPublicKey, const std::vector<uint8_t> &extraInfo)
    {
@@ -395,7 +395,7 @@ Pin_auth驱动的主要工作是为上层用户认证框架和Pin_auth服务提
        return HDF_SUCCESS;
    }
    
-   //实现回调数据获取的接口
+   // 实现回调数据获取的接口
    int32_t ExecutorImpl::OnSetData(uint64_t scheduleId, uint64_t authSubType, const std::vector<uint8_t> &data)
    {
        IAM_LOGI("start");