!684 驱动开发指导文档的细节修改

Merge pull request !684 from tianyangpeng/master

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

@@ -127,7 +127,7 @@ GPIO模块适配的三个环节是配置属性文件，实例化驱动入口，
             match_attr = "hisilicon_hi35xx_pl061"; //【必要】必须和device_info.hcs中的deviceMatchAttr值一致
             groupNum = 12;       //【必要】GPIO组索引 需要根据设备情况填写
             bitNum = 8;          //【必要】每组GPIO管脚数 
-            regBase = 0x120d0000;//【必要】物理及地址
+            regBase = 0x120d0000;//【必要】物理基地址
             regStep = 0x1000;    //【必要】寄存器偏移步进
             irqStart = 48;       //【必要】开启中断
             irqShare = 0;        //【必要】共享中断

zh-cn/device-dev/driver/driver-platform-mipidsi-develop.md

@@ -112,7 +112,7 @@ MIPI-DSI模块适配的三个环节是配置属性文件，实例化驱动入口
 3.  完成驱动入口注册之后，最后一步就是以核心层MipiDsiCntlr对象的初始化为核心，包括厂商自定义结构体（传递参数和数据），实例化MipiDsiCntlr成员MipiDsiCntlrMethod（让用户可以通过接口来调用驱动底层函数），实现HdfDriverEntry成员函数（Bind，Init，Release）
 
 - 自定义结构体参考 
-    
+  
     > 从驱动的角度看，自定义结构体是参数和数据的载体，一般来说，config文件中的数值也会用来初始化结构体成员，但本例的mipidsi无器件属性文件，故基本成员结构与MipiDsiCntlr无太大差异。
 
     ```c
@@ -196,8 +196,8 @@ MIPI-DSI模块适配的三个环节是配置属性文件，实例化驱动入口
     
         g_mipiDsihandle[cntlr->devNo].cntlr = cntlr;//初始化MipiDsiHandle成员
         g_mipiDsihandle[cntlr->devNo].priv = NULL;  
-        cntlr->device = device;                     //使HdfDeviceObject与MmcCntlr可以相互转化的前提
-        device->service = &(cntlr->service);        //使HdfDeviceObject与MmcCntlr可以相互转化的前提
+        cntlr->device = device;                     //使HdfDeviceObject与MipiDsiHandle可以相互转化的前提
+        device->service = &(cntlr->service);        //使HdfDeviceObject与MipiDsiHandle可以相互转化的前提
         cntlr->priv = NULL;	
         ...
         return HDF_SUCCESS;

zh-cn/device-dev/driver/driver-platform-rtc-develop.md

@@ -59,7 +59,7 @@ RTC模块适配HDF框架的三个环节是配置属性文件，实例化驱动
 > 
 > |函数|入参|出参|返回值|功能|
 > |-|-|-|-|-|
-> |ReadTime             |**host**: 结构体指针,核心层RTC控制器 ; |**time**: 结构体指针,<br />传出的时间值; |HDF_STATUS相关状态| 读RTC时间信息[^2] |
+> |ReadTime             |**host**: 结构体指针,核心层RTC控制器 ; |**time**: 结构体指针,<br />传出的时间值; |HDF_STATUS相关状态| 读RTC时间信息 |
 > |WriteTime            |**host**: 结构体指针,核心层RTC控制器 ;<br />**time**: 结构体指针,时间传入值; |无 |HDF_STATUS相关状态| 写RTC时间信息（包括毫秒~年） |
 > |ReadAlarm            |**host**: 结构体指针,核心层RTC控制器 ;<br />**alarmIndex**: 枚举值，闹钟报警索引 ;|**time**: 结构体指针,<br />传出的时间值;|HDF_STATUS相关状态| 读RTC报警时间信息 |
 > |WriteAlarm           |**host**: 结构体指针,核心层RTC控制器 ;<br />**alarmIndex**: 枚举值，闹钟报警索引 ;<br />**time**: 结构体指针,时间传入值;|无|HDF_STATUS相关状态| 写RTC报警时间信息 |
@@ -76,7 +76,7 @@ RTC模块适配HDF框架的三个环节是配置属性文件，实例化驱动
 下方将以rtc_hi35xx.c为示例，展示需要厂商提供哪些内容来完整实现设备功能。
 
 1. 驱动开发首先需要实例化驱动入口，驱动入口必须为HdfDriverEntry（在 hdf_device_desc.h 中定义）类型的全局变量，且moduleName要和device_info.hcs中保持一致。HDF框架会将所有加载的驱动的HdfDriverEntry对象首地址汇总，形成一个类似数组的段地址空间，方便上层调用。
-    
+   
     一般在加载驱动时HDF会先调用Bind函数，再调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。
 
 - RTC驱动入口参考
@@ -94,7 +94,7 @@ RTC模块适配HDF框架的三个环节是配置属性文件，实例化驱动
     ```
 
 2. 完成驱动入口注册之后，下一步请在device_info.hcs文件中添加deviceNode信息，并在 rtc_config.hcs 中配置器件属性。deviceNode信息与驱动入口注册相关，器件属性值与核心层RtcHost成员的默认值或限制范围有密切关系。
-    
+   
     **本例只有一个RTC控制器，如有多个器件信息，则需要在device_info文件增加deviceNode信息，以及在rtc_config文件中增加对应的器件属性**。
 
 - device_info.hcs 配置参考
@@ -108,7 +108,7 @@ RTC模块适配HDF框架的三个环节是配置属性文件，实例化驱动
               policy = 1;                              //2:用户态可见,1:内核态可见,0:不需要发布服务
               priority = 30;                           //优先级越大，值越小
               permission = 0644;                       //驱动创建设备节点权限
-              moduleName = "HDF_PLATFORM_RTC";         //【必要】驱动注册名字
+              moduleName = "HDF_PLATFORM_RTC";         //【必要】用于指定驱动名称，需要与驱动Entry中的moduleName一致；
               serviceName = "HDF_PLATFORM_RTC";        //【必要】驱动对外发布服务的名称，必须唯一
               deviceMatchAttr = "hisilicon_hi35xx_rtc";//【必要】需要与设备hcs文件中的 match_attr 匹配
             }
@@ -208,8 +208,9 @@ RTC模块适配HDF框架的三个环节是配置属性文件，实例化驱动
     > |HDF_ERR_IO           |I/O 错误|
     > |HDF_SUCCESS            |初始化成功|
     > |HDF_FAILURE           |初始化失败|
+    > 
     > **函数说明：**
-    > 链接HdfDeviceObject对象和RtcHost
+    > 关联HdfDeviceObject对象和RtcHost
     
     ```c 
     static int32_t HiRtcBind(struct HdfDeviceObject *device)

zh-cn/device-dev/driver/driver-platform-sdio-develop.md

@@ -228,10 +228,7 @@ SDIO模块适配HDF框架的三个环节是配置属性文件，实例化驱动
     > |HDF_ERR_IO           |I/O 错误|
     > |HDF_SUCCESS            |初始化成功|
     > |HDF_FAILURE           |初始化失败|
-    > 
-    > **函数说明：**
-    > 将 MmcCntlr 对象同 HdfDeviceObject 进行了关联 
-    > 
+    >  
     > **函数说明：**
     > 初始化自定义结构体对象，初始化SdioCntlr成员，调用核心层SdioCntlrAdd函数，以及其他厂商自定义初始化操作
     
@@ -295,7 +292,7 @@ SDIO模块适配HDF框架的三个环节是配置属性文件，实例化驱动
     > 无
     > 
     > **函数说明：**
-    > 释放内存和删除控制器，该函数需要在驱动入口结构体中赋值给 Release 接口， 当HDF框架调用Init函数初始化驱动失败时，可以调用 Release 释放驱动资源。所有强制转换获取相应对象的操作**前提**是在Bnit函数中具备对应赋值的操作。
+    > 释放内存和删除控制器，该函数需要在驱动入口结构体中赋值给 Release 接口， 当HDF框架调用Init函数初始化驱动失败时，可以调用 Release 释放驱动资源。所有强制转换获取相应对象的操作**前提**是在Bind函数中具备对应赋值的操作。
     
     ```c
     static void Hi35xxLinuxSdioRelease(struct HdfDeviceObject *obj)

zh-cn/device-dev/driver/driver-platform-spi-develop.md

@@ -15,7 +15,7 @@ SPI是串行外设接口（Serial Peripheral Interface）的缩写，在HDF框
 
 ## 开发步骤 <a name="2"></a>
 
-SPI模块适配HDF框架的三个环节是配置属性文件，实例化驱动入口，以及填充核心层接口函数。
+SPI模块适配HDF框架的三个环节是配置属性文件，实例化驱动入口，以及实例化核心层接口函数。
 
 1. **实例化驱动入口：**   
     - 实例化HdfDriverEntry结构体成员。
@@ -61,7 +61,7 @@ SPI模块适配HDF框架的三个环节是配置属性文件，实例化驱动
 下方将以spi_hi35xx.c为示例，展示需要厂商提供哪些内容来完整实现设备功能。
 
 1. 驱动开发首先需要实例化驱动入口，驱动入口必须为HdfDriverEntry（在 hdf_device_desc.h 中定义）类型的全局变量，且moduleName要和device_info.hcs中保持一致。HDF框架会将所有加载的驱动的HdfDriverEntry对象首地址汇总，形成一个类似数组的段地址空间，方便上层调用。
-    
+   
     一般在加载驱动时HDF会先调用Bind函数，再调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。
 
 - SPI驱动入口参考
@@ -214,7 +214,7 @@ SPI模块适配HDF框架的三个环节是配置属性文件，实例化驱动
 - **【重要】** SpiCntlr成员回调函数结构体SpiCntlrMethod的实例化，其他成员在Init函数中初始化
 
     ```c 
-    // spi_hi35xx.c 中的示例：钩子函数的填充
+    // spi_hi35xx.c 中的示例：钩子函数的实例化
     struct SpiCntlrMethod g_method = {
         .Transfer = Pl022Transfer,
         .SetCfg = Pl022SetCfg,
@@ -247,7 +247,7 @@ SPI模块适配HDF框架的三个环节是配置属性文件，实例化驱动
     {
         struct SpiCntlr *cntlr = NULL;      //创建核心层 SpiCntlr 对象
         ...
-        cntlr = (struct SpiCntlr *)OsalMemCalloc(sizeof(*cntlr));//非配内存
+        cntlr = (struct SpiCntlr *)OsalMemCalloc(sizeof(*cntlr));//分配内存
         ...
         cntlr->device = device;             //使HdfDeviceObject与SpiCntlr可以相互转化的前提
         device->service = &(cntlr->service);//使HdfDeviceObject与SpiCntlr可以相互转化的前提
@@ -280,7 +280,6 @@ SPI模块适配HDF框架的三个环节是配置属性文件，实例化驱动
     > 初始化自定义结构体对象，初始化SpiCntlr成员。
     
     ```c 
-    //挂载init的
     static int32_t HdfSpiDeviceInit(struct HdfDeviceObject *device)
     {
     int32_t ret;
@@ -289,7 +288,7 @@ SPI模块适配HDF框架的三个环节是配置属性文件，实例化驱动
     cntlr = SpiCntlrFromDevice(device);//这里有HdfDeviceObject到SpiCntlr的强制转化，通过service成员，赋值见Bind函数
                                         //return (device == NULL) ? NULL : (struct SpiCntlr *)device->service;
     ...
-    ret = Pl022Init(cntlr, device);//【必要】填充厂商自定义操作对象，示例见下
+    ret = Pl022Init(cntlr, device);//【必要】实例化厂商自定义操作对象，示例见下
     ...
     ret = Pl022Probe(cntlr->priv);
     ...
@@ -303,10 +302,10 @@ SPI模块适配HDF框架的三个环节是配置属性文件，实例化驱动
     ...
     pl022 = (struct Pl022 *)OsalMemCalloc(sizeof(*pl022));//申请内存
     ...
-    ret = SpiGetBaseCfgFromHcs(pl022, device->property);  //填充busNum, numCs, speed, fifoSize, clkRate, 
+    ret = SpiGetBaseCfgFromHcs(pl022, device->property);  //初始化busNum, numCs, speed, fifoSize, clkRate, 
                                                             //mode, bitsPerWord, transferMode参数值
     ...
-    ret = SpiGetRegCfgFromHcs(pl022, device->property);   //填充regBase, phyBase, irqNum, regCrg, clkEnBit, 
+    ret = SpiGetRegCfgFromHcs(pl022, device->property);   //初始化regBase, phyBase, irqNum, regCrg, clkEnBit, 
                                                             //clkRstBit, regMiscCtrl, regMiscCtrl, miscCtrlCs, 
                                                             //miscCtrlCsShift参数值
     ...
@@ -327,7 +326,7 @@ SPI模块适配HDF框架的三个环节是配置属性文件，实例化驱动
     return 0;
     }
     ```
-
+    
 - **Release函数参考**
 
     > **入参：** 

zh-cn/device-dev/driver/driver-platform-uart-develop.md

@@ -15,7 +15,7 @@ UART是通用异步收发传输器（Universal Asynchronous Receiver/Transmitter
 
 ## 开发步骤 <a name="2"></a>
 
-uart模块适配HDF框架的三个环节是配置属性文件，实例化驱动入口，以及填充核心层接口函数。
+uart模块适配HDF框架的三个环节是配置属性文件，实例化驱动入口，以及实例化核心层接口函数。
 
 1. **实例化驱动入口：**   
     - 实例化HdfDriverEntry结构体成员。
@@ -73,7 +73,7 @@ uart模块适配HDF框架的三个环节是配置属性文件，实例化驱动
 下方将以uart_hi35xx.c为示例，展示需要厂商提供哪些内容来完整实现设备功能。
 
 1. 驱动开发首先需要实例化驱动入口，驱动入口必须为HdfDriverEntry（在 hdf_device_desc.h 中定义）类型的全局变量，且moduleName要和device_info.hcs中保持一致。HDF框架会将所有加载的驱动的HdfDriverEntry对象首地址汇总，形成一个类似数组的段地址空间，方便上层调用。
-    
+   
     一般在加载驱动时HDF会先调用Bind函数，再调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。
 
 - UART驱动入口参考
@@ -206,14 +206,14 @@ uart模块适配HDF框架的三个环节是配置属性文件，实例化驱动
         uint32_t num;
         OsalAtomic atom;
         void *priv;                         //一般存储厂商自定义结构体首地址，方便后者被调用
-        struct UartHostMethod *method;      //核心层钩子函数，厂商需要实现其成员函数功能并填充
+        struct UartHostMethod *method;      //核心层钩子函数，厂商需要实现其成员函数功能并实例化
     };
     ```
 
 - **【重要】** UartHost成员回调函数结构体UartHostMethod的实例化，其他成员在Bind函数中初始化
 
     ```c
-    // uart_hi35xx.c 中的示例：钩子函数的填充
+    // uart_hi35xx.c 中的示例：钩子函数的实例化
     struct UartHostMethod g_uartHostMethod = {
       .Init = Hi35xxInit,
       .Deinit = Hi35xxDeinit,
@@ -286,7 +286,6 @@ uart模块适配HDF框架的三个环节是配置属性文件，实例化驱动
     > 初始化自定义结构体对象，初始化UartHost成员，调用核心层UartAddDev函数，接入VFS
     
     ```c 
-    //挂载init的
     int32_t HdfUartDeviceInit(struct HdfDeviceObject *device)
     {
         int32_t ret;
@@ -308,7 +307,7 @@ uart模块适配HDF框架的三个环节是配置属性文件，实例化驱动
         struct UartDriverData *udd = NULL;
         struct UartPl011Port *port = NULL;
         ...
-        // 【必要相关功能】步骤【1】~【7】主要实现对 udd 对象的填充赋值，然后赋值给核心层UartHost对象上
+        // 【必要相关功能】步骤【1】~【7】主要实现对 udd 对象的实例化赋值，然后赋值给核心层UartHost对象上
         udd = (struct UartDriverData *)OsalMemCalloc(sizeof(*udd));//【1】
         ...
         port = (struct UartPl011Port *)OsalMemCalloc(sizeof(struct UartPl011Port));//【2】
@@ -343,7 +342,7 @@ uart模块适配HDF框架的三个环节是配置属性文件，实例化驱动
         return 0;
         }
     ```
-
+    
 - **Release函数参考**
 
     > **入参：** 

zh-cn/device-dev/driver/driver-platform-watchdog-develop.md

@@ -6,7 +6,7 @@
 
 ## 概述 <a name="1"></a>
 
-看门狗（watchdog），又叫看门狗计时器（watchdog timer），是一种硬件的计时设备，在HDF框架中，watchdog接口适配模式采用独立服务模式，在这种模式下，每一个设备对象会独立发布一个设备服务来处理外部访问，设备管理器收到API的访问请求之后，通过提取该请求的参数，达到调用实际设备对象的相应内部方法的目的。
+看门狗（Watchdog），又叫看门狗计时器（Watchdog timer），是一种硬件的计时设备，在HDF框架中，Watchdog接口适配模式采用独立服务模式，在这种模式下，每一个设备对象会独立发布一个设备服务来处理外部访问，设备管理器收到API的访问请求之后，通过提取该请求的参数，达到调用实际设备对象的相应内部方法的目的。
 
 独立服务模式可以直接借助HDFDeviceManager的服务管理能力，但需要为每个设备单独配置设备节点，增加内存占用。
 
@@ -15,7 +15,7 @@
 
 ## 开发步骤 <a name="2"></a>
 
-watchdog模块适配HDF框架的三个环节是配置属性文件，实例化驱动入口，以及填充核心层接口函数。
+Watchdog模块适配HDF框架的三个环节是配置属性文件，实例化驱动入口，以及填充核心层接口函数。
 
 1. **实例化驱动入口：**   
     - 实例化HdfDriverEntry结构体成员。
@@ -45,7 +45,7 @@ watchdog模块适配HDF框架的三个环节是配置属性文件，实例化驱
 >   int32_t (*start)(struct WatchdogCntlr *wdt);
 >   int32_t (*stop)(struct WatchdogCntlr *wdt);
 >   int32_t (*feed)(struct WatchdogCntlr *wdt);
->   int32_t (*getPriv)(struct WatchdogCntlr *wdt); //【可选】如果WatchdogCntlr 中的priv成员存在，则按需填充 
+>   int32_t (*getPriv)(struct WatchdogCntlr *wdt); //【可选】如果WatchdogCntlr 中的priv成员存在，则按需进行实例化
 >   void (*releasePriv)(struct WatchdogCntlr *wdt);//【可选】
 > };
 > ```
@@ -66,10 +66,10 @@ watchdog模块适配HDF框架的三个环节是配置属性文件，实例化驱
 下方将以watchdog_hi35xx.c为示例，展示需要厂商提供哪些内容来完整实现设备功能。
 
 1. 驱动开发首先需要实例化驱动入口，驱动入口必须为HdfDriverEntry（在 hdf_device_desc.h 中定义）类型的全局变量，且moduleName要和device_info.hcs中保持一致。HDF框架会将所有加载的驱动的HdfDriverEntry对象首地址汇总，形成一个类似数组的段地址空间，方便上层调用。
-    
+   
     一般在加载驱动时HDF会先调用Bind函数，再调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。
 
-- watchdog驱动入口参考
+- Watchdog驱动入口参考
 
     ```c
     struct HdfDriverEntry g_watchdogDriverEntry = {
@@ -83,7 +83,7 @@ watchdog模块适配HDF框架的三个环节是配置属性文件，实例化驱
     ```
 
 2. 完成驱动入口注册之后，下一步请在device_info.hcs文件中添加deviceNode信息，并在 watchdog_config.hcs 中配置器件属性。deviceNode信息与驱动入口注册相关，器件属性值与核心层WatchdogCntlr 成员的默认值或限制范围有密切关系。
-    
+   
     **本例只有一个Watchdog控制器，如有多个器件信息，则需要在device_info文件增加deviceNode信息，以及在watchdog_config文件中增加对应的器件属性**。
 
 - device_info.hcs 配置参考
@@ -145,8 +145,8 @@ watchdog模块适配HDF框架的三个环节是配置属性文件，实例化驱
     };
     //WatchdogCntlr是核心层控制器结构体，其中的成员在Init函数中会被赋值
     struct WatchdogCntlr {
-      struct IDeviceIoService service;//驱动服务，【无需挂载】
-      struct HdfDeviceObject *device; //驱动设备，需要挂载 bind 函数的入参：struct HdfDeviceObject *device
+      struct IDeviceIoService service;//驱动服务
+      struct HdfDeviceObject *device; //驱动设备
       OsalSpinlock lock;              //在HDF核心层调用时从系统代码实现了一个自旋锁的机制，挂载的变量需要是相同的变量，不建议挂载
       struct WatchdogMethod *ops;     //接口回调函数
       int16_t wdtId;                  //WDG设备的识别id
@@ -207,7 +207,7 @@ watchdog模块适配HDF框架的三个环节是配置属性文件，实例化驱
     ...
     //最重要的是这个挂载的过程
     hwdt->wdt.priv = (void *)device->property;//【可选】此处填充的是设备属性，但后续没有调用 priv 成员，
-                                                // 如果需要用到 priv 成员，需要实现对应的钩子函数填充 WatchdogMethod 
+                                                // 如果需要用到 priv 成员，需要实现对应的钩子函数实例化WatchdogMethod 
                                                 // 结构体的 getPriv 和 releasePriv 成员函数
     hwdt->wdt.ops = &g_method;                //【必要】WatchdogMethod的实例化对象的挂载
     hwdt->wdt.device = device;                //【必要】使HdfDeviceObject与WatchdogcCntlr可以相互转化的前提
@@ -238,13 +238,13 @@ watchdog模块适配HDF框架的三个环节是配置属性文件，实例化驱
     struct WatchdogCntlr *wdt = NULL;
     struct Hi35xxWatchdog *hwdt = NULL;
     ...
-    wdt = WatchdogCntlrFromDevice(device);//这里有HdfDeviceObject到MmcCntlr的强制转化，通过service成员(第一个成员)，赋值见Bind函数
+    wdt = WatchdogCntlrFromDevice(device);//这里有HdfDeviceObject到WatchdogCntlr的强制转化，通过service成员(第一个成员)，赋值见Bind函数
                                             //return (device == NULL) ? NULL : (struct WatchdogCntlr *)device->service;
     if (wdt == NULL) {
         return;
     }
     WatchdogCntlrRemove(wdt);				//核心层函数，实际执行wdt->device->service = NULL以及cntlr->lock的释放
-    hwdt = (struct Hi35xxWatchdog *)wdt;  //这里有MmcCntlr到HimciHost的强制转化
+    hwdt = (struct Hi35xxWatchdog *)wdt;  //这里有WatchdogCntlr到HimciHost的强制转化
     if (hwdt->regBase != NULL) {			//地址反映射
         OsalIoUnmap((void *)hwdt->regBase);
         hwdt->regBase = NULL;