资料规范性检查

Signed-off-by: Nli-yan339 <liyan339@h-partners.com>

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

@@ -3,7 +3,7 @@
 
 ## 概述
 
-RTC（real-time clock）为操作系统中的实时时钟设备。在HDF框架中，RTC的接口适配模式采用独立服务模式，在这种模式下，每一个设备对象会独立发布一个设备服务来处理外部访问，设备管理器收到API的访问请求之后，通过提取该请求的参数，达到调用实际设备对象的相应内部方法的目的。独立服务模式可以直接借助HDFDeviceManager的服务管理能力，但需要为每个设备单独配置设备节点，增加内存占用。
+RTC（Real-time Clock）为操作系统中的实时时钟设备。在HDF框架中，RTC的接口适配模式采用独立服务模式，在这种模式下，每一个设备对象会独立发布一个设备服务来处理外部访问，设备管理器收到API的访问请求之后，通过提取该请求的参数，达到调用实际设备对象的相应内部方法的目的。独立服务模式可以直接借助HDFDeviceManager的服务管理能力，但需要为每个设备单独配置设备节点，增加内存占用。
 
   **图1** RTC独立服务模式结构图
 
@@ -50,23 +50,24 @@ struct RtcMethod {
 
 ## 开发步骤
 
-RTC模块适配HDF框架的三个环节是配置属性文件，实例化驱动入口，以及填充核心层接口函数。
+RTC模块适配HDF框架的三个必选环节是实例化驱动入口，配置属性文件，以及填充核心层接口函数。
 
-1. **实例化驱动入口：**
+1. 实例化驱动入口
    - 实例化HdfDriverEntry结构体成员。
    - 调用HDF_INIT将HdfDriverEntry实例化对象注册到HDF框架中。
 
-2. **配置属性文件：**
+2. 配置属性文件
    - 在device_info.hcs文件中添加deviceNode描述。
    - 【可选】添加rtc_config.hcs器件属性文件。
 
-3. **实例化RTC控制器对象：**
+3. 实例化RTC控制器对象
    - 初始化RtcHost成员。
    - 实例化RtcHost成员RtcMethod。
       > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**<br>
       > 实例化RtcHost成员RtcMethod，其定义和成员说明见[接口说明](#接口说明)。
 
-4. **驱动调试：**
+4. 驱动调试
+
    【可选】针对新增驱动程序，建议验证驱动基本功能，例如RTC控制状态，中断响应情况等。
 
 
@@ -74,7 +75,12 @@ RTC模块适配HDF框架的三个环节是配置属性文件，实例化驱动
 
 下方将以rtc_hi35xx.c为示例，展示需要厂商提供哪些内容来完整实现设备功能。
 
-1. 驱动开发首先需要实例化驱动入口，驱动入口必须为HdfDriverEntry（在 hdf_device_desc.h 中定义）类型的全局变量，且moduleName要和device_info.hcs中保持一致。HDF框架会将所有加载的驱动的HdfDriverEntry对象首地址汇总，形成一个类似数组的段地址空间，方便上层调用。
+1. 驱动开发首先需要实例化驱动入口。
+
+   驱动入口必须为HdfDriverEntry（在hdf_device_desc.h中定义）类型的全局变量，且moduleName要和device_info.hcs中保持一致。
+
+   HDF框架会将所有加载的驱动的HdfDriverEntry对象首地址汇总，形成一个类似数组的段地址空间，方便上层调用。
+
    一般在加载驱动时HDF会先调用Bind函数，再调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。
 
    RTC驱动入口参考：
@@ -85,15 +91,19 @@ RTC模块适配HDF框架的三个环节是配置属性文件，实例化驱动
      .Bind = HiRtcBind,               // 见Bind参考
      .Init = HiRtcInit,               // 见Init参考
      .Release = HiRtcRelease,         // 见Release参考
-     .moduleName = "HDF_PLATFORM_RTC",// 【必要】且与 HCS 里面的名字匹配
+     .moduleName = "HDF_PLATFORM_RTC",// 【必要】且与HCS里面的名字匹配
    };
    //调用HDF_INIT将驱动入口注册到HDF框架中
    HDF_INIT(g_rtcDriverEntry);
    ```
 
-2. 完成驱动入口注册之后，下一步请在device_info.hcs文件中添加deviceNode信息，并在 rtc_config.hcs 中配置器件属性。deviceNode信息与驱动入口注册相关，器件属性值与核心层RtcHost成员的默认值或限制范围有密切关系。
+2. 完成驱动入口注册之后，下一步请在device_info.hcs文件中添加deviceNode信息，并在rtc_config.hcs中配置器件属性。
+
+   deviceNode信息与驱动入口注册相关，器件属性值与核心层RtcHost成员的默认值或限制范围有密切关系。
+
    本例只有一个RTC控制器，如有多个器件信息，则需要在device_info文件增加deviceNode信息，以及在rtc_config文件中增加对应的器件属性。
-   - device_info.hcs 配置参考。
+
+   - device_info.hcs配置参考
    
        
      ```
@@ -102,12 +112,12 @@ RTC模块适配HDF框架的三个环节是配置属性文件，实例化驱动
          platform :: host {
            device_rtc :: device {
              device0 :: deviceNode {
-               policy = 1;                              // 2:用户态可见,1:内核态可见,0:不需要发布服务
-               priority = 30;                           // 值越小，优先级越高
+               policy = 1;                              // 2：用户态可见；1：内核态可见；0：不需要发布服务。
+               priority = 30;                           // 值越小，优先级越高。
                permission = 0644;                       // 驱动创建设备节点权限
-               moduleName = "HDF_PLATFORM_RTC";         // 【必要】用于指定驱动名称，需要与驱动Entry中的moduleName一致
-               serviceName = "HDF_PLATFORM_RTC";        // 【必要】驱动对外发布服务的名称，必须唯一
-               deviceMatchAttr = "hisilicon_hi35xx_rtc";// 【必要】需要与设备hcs文件中的 match_attr 匹配
+               moduleName = "HDF_PLATFORM_RTC";         // 【必要】用于指定驱动名称，需要与驱动Entry中的moduleName一致。
+               serviceName = "HDF_PLATFORM_RTC";        // 【必要】驱动对外发布服务的名称，必须唯一。
+               deviceMatchAttr = "hisilicon_hi35xx_rtc";// 【必要】需要与设备hcs文件中的match_attr匹配。
              }
            }
          }
@@ -115,7 +125,7 @@ RTC模块适配HDF框架的三个环节是配置属性文件，实例化驱动
      }
      ```
    
-   - rtc_config.hcs配置参考。
+   - rtc_config.hcs配置参考
    
        
      ```
@@ -140,10 +150,11 @@ RTC模块适配HDF框架的三个环节是配置属性文件，实例化驱动
      }
      ```
 
-3. 完成驱动入口注册之后，最后一步就是以核心层RtcHost对象的初始化为核心，包括厂商自定义结构体（传递参数和数据），实例化RtcHost成员RtcMethod（让用户可以通过接口来调用驱动底层函数），实现HdfDriverEntry成员函数（Bind，Init，Release）。
+3. 完成属性文件配置之后，下一步就是以核心层RtcHost对象的初始化为核心，包括厂商自定义结构体（传递参数和数据），实例化RtcHost成员RtcMethod（让用户可以通过接口来调用驱动底层函数），实现HdfDriverEntry成员函数（Bind、Init、Release）。
+
    - 自定义结构体参考。
 
-      从驱动的角度看，自定义结构体是参数和数据的载体，而且rtc_config.hcs文件中的数值会被HDF读入通过DeviceResourceIface来初始化结构体成员。
+      从驱动的角度看，自定义结构体是参数和数据的载体，而且rtc_config.hcs文件中的数值会被HDF读入并通过DeviceResourceIface来初始化结构体成员。
 
         
       ```
@@ -161,7 +172,7 @@ RTC模块适配HDF框架的三个环节是配置属性文件，实例化驱动
         struct OsalMutex   mutex;          // 互斥锁
       };
       
-      // RtcHost是核心层控制器结构体，其中的成员在Init函数中会被赋值
+      // RtcHost是核心层控制器结构体，其中的成员在Init函数中会被赋值。
       struct RtcHost {
           struct IDeviceIoService service;
           struct HdfDeviceObject *device;
@@ -219,11 +230,11 @@ RTC模块适配HDF框架的三个环节是配置属性文件，实例化驱动
       static int32_t HiRtcBind(struct HdfDeviceObject *device)
       {
         struct RtcHost *host = NULL;  
-        host = RtcHostCreate(device);    // 实际是申请内存并挂接device: host->device = device;
+        host = RtcHostCreate(device);    // 实际是申请内存并挂接device: host->device = device
                                          // 使HdfDeviceObject与RtcHost可以相互转化的前提
         ...
         device->service = &host->service;// 使HdfDeviceObject与RtcHost可以相互转化的前提
-                                         // 方便后续通过调用RtcHostFromDevice 实现全局性质的host
+                                         // 方便后续通过调用RtcHostFromDevice实现全局性质的host
         return HDF_SUCCESS;
       }
       ```
@@ -252,19 +263,19 @@ RTC模块适配HDF框架的三个环节是配置属性文件，实例化驱动
         host = RtcHostFromDevice(device);// 这里是HdfDeviceObject到RtcHost的强制转化
         rtcInfo = OsalMemCalloc(sizeof(*rtcInfo));
         ...
-        // HiRtcConfigData 会从设备配置树中读取属性填充rtcInfo 的supportAnaCtrl, supportLock, spiBaseAddr, regAddrLength, irq
-        // 为HiRtcSwInit和HiRtcSwInit提供参数，当函数HiRtcSwInit和HiRtcSwInit内部执行失败后进行内存释放等操作
+        // HiRtcConfigData会从设备配置树中读取属性填充rtcInfo的supportAnaCtrl、supportLock、spiBaseAddr、regAddrLength、irq，
+        // 为HiRtcSwInit和HiRtcSwInit提供参数，当函数HiRtcSwInit和HiRtcSwInit内部执行失败后进行内存释放等操作。
         if (HiRtcConfigData(rtcInfo, device->property) != 0) {
           ...
         }
         if (HiRtcSwInit(rtcInfo) != 0) {// 地址映射以及中断注册相关
           ...
         }
-        if (HiRtcHwInit(rtcInfo) != 0) {// 初始化anaCtrl 和 lockAddr 相关内容
+        if (HiRtcHwInit(rtcInfo) != 0) {// 初始化anaCtrl和lockAddr相关内容
           ...
         }
       
-        host->method = &g_method;//RtcMethod的实例化对象的挂载
+        host->method = &g_method;// RtcMethod的实例化对象的挂载
         host->data = rtcInfo;    // 使RtcConfigInfo与RtcHost可以相互转化的前提
         HDF_LOGI("Hdf dev service:%s init success!", HdfDeviceGetServiceName(device));
         return HDF_SUCCESS;
@@ -282,7 +293,10 @@ RTC模块适配HDF框架的三个环节是配置属性文件，实例化驱动
 
       函数说明：
 
-      释放内存和删除控制器，该函数需要在驱动入口结构体中赋值给Release接口，当HDF框架调用Init函数初始化驱动失败时，可以调用Release释放驱动资源。所有强制转换获取相应对象的操作前提是在Init或Bind函数中具备对应赋值的操作。
+      释放内存和删除控制器，该函数需要在驱动入口结构体中赋值给Release接口，当HDF框架调用Init函数初始化驱动失败时，可以调用Release释放驱动资源。
+
+      > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**<br>
+      > 所有强制转换获取相应对象的操作前提是在Init或Bind函数中具备对应赋值的操作。
 
         
       ```