!1220 【轻量级 PR】：【同步】【驱动】GPIO接口介绍的注释、英文标点修改。

Merge pull request !1220 from liyan/N/A

!1220 【轻量级 PR】：【同步】【驱动】GPIO接口介绍的注释、英文标点修改。
Merge pull request !1220 from liyan/N/A
9a9f1a14 · openharmony_ci · Gitee · 67d15e35 · 2e01c86c · 9a9f1a14
显示空白变更内容
内联并排

Showing with 228 addition and 220 deletion

zh-cn/device-dev/driver/driver-platform-gpio-develop.md zh-cn/device-dev/driver/driver-platform-gpio-develop.md +228 -220

未找到文件。
--- a/zh-cn/device-dev/driver/driver-platform-gpio-develop.md
+++ b/zh-cn/device-dev/driver/driver-platform-gpio-develop.md
 # GPIO

 - [概述](#1)
- [开发步骤](#2)
- [开发实例](#3)
+- [接口说明](#2)
+- [开发步骤](#3)
+- [开发实例](#4)

 ## 概述 <a name="1"></a>

@@ -12,7 +13,40 @@ GPIO的接口适配模式采用无服务模式，用于不需要在用户态提
 图 1 无服务模式结构图
 ![image1](figure/无服务模式.png)

-## 开发步骤 <a name="2"></a>
+## 接口说明 <a name="2"></a>
+
+GpioMethod定义
+ 
+ ```c
+ struct GpioMethod {
+   int32_t (*request)(struct GpioCntlr *cntlr, uint16_t local);// 【预留】
+   int32_t (*release)(struct GpioCntlr *cntlr, uint16_t local);// 【预留】
+   int32_t (*write)(struct GpioCntlr *cntlr, uint16_t local, uint16_t val);
+   int32_t (*read)(struct GpioCntlr *cntlr, uint16_t local, uint16_t *val);
+   int32_t (*setDir)(struct GpioCntlr *cntlr, uint16_t local, uint16_t dir);
+   int32_t (*getDir)(struct GpioCntlr *cntlr, uint16_t local, uint16_t *dir);
+   int32_t (*toIrq)(struct GpioCntlr *cntlr, uint16_t local, uint16_t *irq);// 【预留】
+   int32_t (*setIrq)(struct GpioCntlr *cntlr, uint16_t local, uint16_t mode, GpioIrqFunc func, void *arg);
+   int32_t (*unsetIrq)(struct GpioCntlr *cntlr, uint16_t local);
+   int32_t (*enableIrq)(struct GpioCntlr *cntlr, uint16_t local);
+   int32_t (*disableIrq)(struct GpioCntlr *cntlr, uint16_t local);
+ };
+ ```
+ 
+表1 GpioMethod结构体成员的回调函数功能说明
+ 
+|函数成员|入参|出参|返回值|功能|
+|-|-|-|-|-|
+|write     |**cntlr**：结构体指针，核心层GPIO控制器；<br />**local**：uint16_t，GPIO端口标识号；<br />**val**：uint16_t，电平传入值； |无| HDF_STATUS相关状态 | GPIO引脚写入电平值       |
+|read      |**cntlr**：结构体指针，核心层GPIO控制器；<br />**local**：uint16_t，GPIO端口标识； |**val**：uint16_t 指针，<br />用于传出电平值；| HDF_STATUS相关状态 | GPIO引脚读取电平值       |
+|setDir    |**cntlr**：结构体指针，核心层GPIO控制器；<br />**local**：uint16_t，GPIO端口标识号；<br />**dir**：uint16_t，管脚方向传入值；|无| HDF_STATUS相关状态 | 设置GPIO引脚输入/输出方向 |
+|getDir    |**cntlr**：结构体指针，核心层GPIO控制器；<br />**local**：uint16_t，GPIO端口标识号；|**dir**：uint16_t 指针，<br />用于传出管脚方向值；| HDF_STATUS相关状态 | 读GPIO引脚输入/输出方向   |
+|setIrq    |**cntlr**：结构体指针，核心层GPIO控制器；<br />**local**：uint16_t，GPIO端口标识号；<br />**mode**：uint16_t，表示触发模式（边沿或电平）；<br />**func**：函数指针，中断服务程序；<br />**arg**：void指针，中断服务程序入参；|无| HDF_STATUS相关状态 |将GPIO引脚设置为中断模式  |
+|unsetIrq  |**cntlr**：结构体指针，核心层GPIO控制器；<br />**local**：uint16_t，GPIO端口标识号；|无| HDF_STATUS相关状态 |取消GPIO中断设置  |
+|enableIrq |**cntlr**：结构体指针，核心层GPIO控制器；<br />**local**：uint16_t，GPIO端口标识号；|无| HDF_STATUS相关状态 |使能GPIO管脚中断  |
+|disableIrq|**cntlr**：结构体指针，核心层GPIO控制器；<br />**local**：uint16_t，GPIO端口标识号；|无| HDF_STATUS相关状态 |禁止GPIO管脚中断  |
+
+## 开发步骤 <a name="3"></a>

 GPIO模块适配的三个环节是配置属性文件，实例化驱动入口，以及实例化核心层接口函数。GPIO控制器分组管理所有管脚，相关参数会在属性文件中有所体现；驱动入口和接口函数的实例化环节是厂商驱动接入HDF的核心环节。

@@ -28,55 +62,22 @@ GPIO模块适配的三个环节是配置属性文件，实例化驱动入口，
 3. **实例化GPIO控制器对象：**   
   
    - 初始化GpioCntlr成员。
-    - 实例化GpioCntlr成员GpioMethod，其定义和成员**说明**见下
+    - 实例化GpioCntlr成员GpioMethod。
+      >![](../public_sys-resources/icon-note.gif) **说明：** 
+      >实例化GpioCntlr成员GpioMethod，详见[接口说明](#2)。
    
 4. **驱动调试：**
    - 【可选】针对新增驱动程序，建议验证驱动基本功能，例如GPIO控制状态，中断响应情况等。

-> ![](../public_sys-resources/icon-note.gif) **说明：** 
-> 
-> GpioMethod定义
-> 
-> ```c
-> struct GpioMethod {
->   int32_t (*request)(struct GpioCntlr *cntlr, uint16_t local);// 【可选】
->   int32_t (*release)(struct GpioCntlr *cntlr, uint16_t local);// 【可选】
->   int32_t (*write)(struct GpioCntlr *cntlr, uint16_t local, uint16_t val);
->   int32_t (*read)(struct GpioCntlr *cntlr, uint16_t local, uint16_t *val);
->   int32_t (*setDir)(struct GpioCntlr *cntlr, uint16_t local, uint16_t dir);
->   int32_t (*getDir)(struct GpioCntlr *cntlr, uint16_t local, uint16_t *dir);
->   int32_t (*toIrq)(struct GpioCntlr *cntlr, uint16_t local, uint16_t *irq);// 【可选】
->   int32_t (*setIrq)(struct GpioCntlr *cntlr, uint16_t local, uint16_t mode, GpioIrqFunc func, void *arg);
->   int32_t (*unsetIrq)(struct GpioCntlr *cntlr, uint16_t local);
->   int32_t (*enableIrq)(struct GpioCntlr *cntlr, uint16_t local);
->   int32_t (*disableIrq)(struct GpioCntlr *cntlr, uint16_t local);
-> };
-> ```
-> 
-> 表1 GpioMethod结构体成员的回调函数功能说明
-> 
-> |函数成员|入参|出参|返回值|功能|
-> |-|-|-|-|-|
-> |write     |**cntlr**：结构体指针，核心层GPIO控制器;<br />**local**：uint16_t，GPIO端口标识号 ;<br />**val**：uint16_t，电平传入值; |无| HDF_STATUS相关状态 | GPIO引脚写入电平值       |
-> |read      |**cntlr**：结构体指针，核心层GPIO控制器;<br />**local**：uint16_t，GPIO端口标识;  |**val**：uint16_t 指针，<br />用于传出电平值 ;| HDF_STATUS相关状态 | GPIO引脚读取电平值       |
-> |setDir    |**cntlr**：结构体指针，核心层GPIO控制器;<br />**local**：uint16_t，GPIO端口标识号 ;<br />**dir**：uint16_t，管脚方向传入值; |无| HDF_STATUS相关状态 | 设置GPIO引脚输入/输出方向 |
-> |getDir    |**cntlr**：结构体指针，核心层GPIO控制器;<br />**local**：uint16_t，GPIO端口标识号 ; |**dir**：uint16_t 指针，<br />用于传出管脚方向值 ;| HDF_STATUS相关状态 | 读GPIO引脚输入/输出方向   |
-> |setIrq    |**cntlr**：结构体指针，核心层GPIO控制器;<br />**local**：uint16_t，GPIO端口标识号;<br />**mode**：uint16_t，表示触发模式（边沿或电平）;<br />**func**：函数指针，中断服务程序 ;<br />**arg**：void指针，中断服务程序入参;|无| HDF_STATUS相关状态 |将GPIO引脚设置为中断模式  |
-> |unsetIrq  |**cntlr**：结构体指针，核心层GPIO控制器;<br />**local**：uint16_t，GPIO端口标识号 ; |无| HDF_STATUS相关状态 |取消GPIO中断设置  |
-> |enableIrq |**cntlr**：结构体指针，核心层GPIO控制器;<br />**local**：uint16_t，GPIO端口标识号; |无| HDF_STATUS相关状态 |使能GPIO管脚中断  |
-> |disableIrq|**cntlr**：结构体指针，核心层GPIO控制器;<br />**local**：uint16_t，GPIO端口标识号; |无| HDF_STATUS相关状态 |禁止GPIO管脚中断  |
-
-
-
-
-## 开发实例 <a name="3"></a>
+
+## 开发实例 <a name="4"></a>
 下方将以gpio_hi35xx.c为示例，展示需要厂商提供哪些内容来完整实现设备功能。

 1. 驱动开发首先需要实例化驱动入口，驱动入口必须为HdfDriverEntry（在 hdf_device_desc.h 中定义）类型的全局变量，且moduleName要和device_info.hcs中保持一致。HDF框架会将所有加载的驱动的HdfDriverEntry对象首地址汇总，形成一个类似数组的段地址空间，方便上层调用。

    一般在加载驱动时HDF会先调用Bind函数，再调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。

- GPIO 驱动入口参考
+    GPIO 驱动入口参考：

    ```c 
    struct HdfDriverEntry g_gpioDriverEntry = {
@@ -92,9 +93,9 @@ GPIO模块适配的三个环节是配置属性文件，实例化驱动入口，

 2. 完成驱动入口注册之后，下一步请在device_info.hcs文件中添加deviceNode信息，并在 gpio_config.hcs 中配置器件属性。deviceNode信息与驱动入口注册相关，器件属性值与核心层GpioCntlr 成员的默认值或限制范围有密切关系。

-    **本例只有一个GPIO控制器，如有多个器件信息，则需要在device_info文件增加deviceNode信息，以及在gpio_config文件中增加对应的器件属性**。
+    本例只有一个GPIO控制器，如有多个器件信息，则需要在device_info文件增加deviceNode信息，以及在gpio_config文件中增加对应的器件属性。

- device_info.hcs 配置参考
+    - device_info.hcs 配置参考

      ```c
      root {
@@ -117,7 +118,7 @@ GPIO模块适配的三个环节是配置属性文件，实例化驱动入口，
      }
      ```

- gpio_config.hcs 配置参考
+    - gpio_config.hcs 配置参考

      ```c
      root {
@@ -139,10 +140,9 @@ GPIO模块适配的三个环节是配置属性文件，实例化驱动入口，

 3. 完成驱动入口注册之后，最后一步就是以核心层GpioCntlr对象的初始化为核心，包括厂商自定义结构体（传递参数和数据），实例化GpioCntlr成员GpioMethod（让用户可以通过接口来调用驱动底层函数），实现HdfDriverEntry成员函数（Bind，Init，Release）

+   - 自定义结构体参考
  
- 自定义结构体参考
-  
-    > 从驱动的角度看，自定义结构体是参数和数据的载体，而且gpio_config.hcs文件中的数值会被HDF读入通过DeviceResourceIface来初始化结构体成员，其中一些重要数值也会传递给核心层GpioCntlr对象，例如索引、管脚数等。
+     从驱动的角度看，自定义结构体是参数和数据的载体，而且gpio_config.hcs文件中的数值会被HDF读入通过DeviceResourceIface来初始化结构体成员，其中一些重要数值也会传递给核心层GpioCntlr对象，例如索引、管脚数等。

      ```c
      struct Pl061GpioCntlr {
@@ -178,7 +178,7 @@ GPIO模块适配的三个环节是配置属性文件，实例化驱动入口，
      };
      ```

- **【重要】** GpioCntlr成员回调函数结构体GpioMethod的实例化，其他成员在Init函数中初始化
+   - **【重要】** GpioCntlr成员回调函数结构体GpioMethod的实例化，其他成员在Init函数中初始化

      ```c 
      //GpioMethod结构体成员都是回调函数，厂商需要根据表1完成相应的函数功能。
@@ -198,25 +198,30 @@ GPIO模块适配的三个环节是配置属性文件，实例化驱动入口，
      ```


- **Init函数参考**
-
-    > **入参：** 
-    >  HdfDeviceObject这个是整个驱动对外暴露的接口参数，具备HCS配置文件的信息 
-    > 
-    > **返回值：**
-    > HDF_STATUS相关状态（下表为部分展示，如需使用其他状态，可见//drivers/framework/include/utils/hdf_base.h中HDF_STATUS 定义） 
-    > 
-    > |状态(值)|问题描述|
-    > |:-|:-:|
-    > |HDF_ERR_INVALID_OBJECT|控制器对象非法|
-    > |HDF_ERR_MALLOC_FAIL   |内存分配失败|
-    > |HDF_ERR_INVALID_PARAM |参数非法|
-    > |HDF_ERR_IO            |I/O 错误|
-    > |HDF_SUCCESS           |初始化成功|
-    > |HDF_FAILURE           |初始化失败|
-    > 
-    > **函数说明：**
-    > 初始化自定义结构体对象，初始化GpioCntlr成员，调用核心层GpioCntlrAdd函数，【可选】接入VFS
+   - **Init函数参考**
+
+     入参：
+ 
+     HdfDeviceObject这个是整个驱动对外暴露的接口参数，具备HCS配置文件的信息 
+     
+     返回值：
+
+     HDF_STATUS相关状态（下表为部分展示，如需使用其他状态，可见//drivers/framework/include/utils/hdf_base.h中HDF_STATUS 定义） 
+     
+
+     |状态(值)|问题描述|
+     |:-|:-:|
+     |HDF_ERR_INVALID_OBJECT|控制器对象非法|
+     |HDF_ERR_MALLOC_FAIL   |内存分配失败|
+     |HDF_ERR_INVALID_PARAM |参数非法|
+     |HDF_ERR_IO            |I/O 错误|
+     |HDF_SUCCESS           |初始化成功|
+     |HDF_FAILURE           |初始化失败|
+     
+   
+     函数说明：
+    
+     初始化自定义结构体对象，初始化GpioCntlr成员，调用核心层GpioCntlrAdd函数，【可选】接入VFS
    
      ```c 
      static int32_t Pl061GpioInit(struct HdfDeviceObject *device)
@@ -250,16 +255,19 @@ GPIO模块适配的三个环节是配置属性文件，实例化驱动入口，
      }
      ```

- **Release 函数参考**
+   - **Release 函数参考**
+
+     入参： 
+    
+     HdfDeviceObject是整个驱动对外暴露的接口参数，具备HCS配置文件的信息 
+     
+     返回值：
+    
+     无
+     
+     函数说明：

-    > **入参：** 
-    > HdfDeviceObject 是整个驱动对外暴露的接口参数，具备 HCS 配置文件的信息 
-    > 
-    > **返回值：**
-    > 无
-    > 
-    > **函数说明：**
-    > 释放内存和删除控制器，该函数需要在驱动入口结构体中赋值给 Release 接口， 当HDF框架调用Init函数初始化驱动失败时，可以调用 Release 释放驱动资源。所有强制转换获取相应对象的操作**前提**是在Init函数中具备对应赋值的操作。
+     释放内存和删除控制器，该函数需要在驱动入口结构体中赋值给Release接口， 当HDF框架调用Init函数初始化驱动失败时，可以调用Release释放驱动资源。所有强制转换获取相应对象的操作前提是在Init函数中具备对应赋值的操作。
    
      ```c
      static void Pl061GpioRelease(struct HdfDeviceObject *device)