!2223 regulator documentation update

Merge pull request !2223 from 张亚雷/master

!2223 regulator documentation update
Merge pull request !2223 from 张亚雷/master
ffe15d9a · openharmony_ci · Gitee · 12d972bb · b51448e3 · ffe15d9a
2 changed file
--- a/zh-cn/device-dev/driver/driver-platform-regulator-des.md
+++ b/zh-cn/device-dev/driver/driver-platform-regulator-des.md
-# REGULATOR<a name="title_REGULATOR_des"></a>
-
-   [概述](#section1_REGULATOR_des)
-   [接口说明](#section2_REGULATOR_des)
-   [使用指导](#section3_REGULATOR_des)
-    -   [使用流程](#section3.1_REGULATOR_des)
-    -   [获取REGULATOR设备句柄](#section3.2_REGULATOR_des)
-    -   [销毁REGULATOR设备句柄](#section3.3_REGULATOR_des)
-    -   [使能](#section3.4_REGULATOR_des)
-    -   [禁用](#section3.5_REGULATOR_des)
-    -   [强制禁用](#section3.6_REGULATOR_des)
-    -   [设置REGULATOR电压输出电压范围](#section3.7_REGULATOR_des)
-    -   [获取REGULATOR设备电压](#section3.8_REGULATOR_des)
-    -   [设置REGULATOR设备输出电流范围](#section3.9_REGULATOR_des)
-    -   [获取REGULATOR设备电流](#section3.10_REGULATOR_des)
-    -   [获取REGULATOR设备状态](#section3.11_REGULATOR_des)
-   [使用实例](#section4_REGULATOR_des)
-
-## 概述<a name="section1_REGULATOR_des"></a>
-
- REGULATOR模块用于控制系统中某些设备的电压/电流供应。在嵌入式系统（尤其是手机）中，控制耗电量很重要，直接影响到电池的续航时间。所以，如果系统中某一个模块暂时不需要使用，就可以通过regulator关闭其电源供应；或者降低提供给该模块的电压、电流大小。
-
- REGULATOR接口定义了操作REGULATOR设备的通用方法集合，包括：
-  - REGULATOR设备句柄获取和销毁。
-  - REGULATOR设备电压、电流的设置。
-  - REGULATOR设备使能和关闭。
-  - REGULATOR设备电压、电流和状态的获取
-
-## 接口说明<a name="section2_REGULATOR_des"></a>
+# REGULATOR<a name="1"></a>
+
+-   [概述](#section1)
+    -   [功能简介](#section2)
+    -   [基本概念](#section3) 
+    -   [运作机制](#section4) 
+    -   [约束与限制](#section5)
+-   [使用指导](#section6)
+    -   [场景介绍](#section7)
+    -   [接口说明](#section8) 
+    -   [开发步骤](#section9)
+    -   [使用实例](#section10)
+
+## 概述<a name="section1"></a>
+
+### 功能简介<a name="section2"></a>
+
+-   REGULATOR模块用于控制系统中某些设备的电压/电流供应。在嵌入式系统（尤其是手机）中，控制耗电量很重要，直接影响到电池的续航时间。所以，如果系统中某一个模块暂时不需要使用，就可以通过REGULATOR关闭其电源供应；或者降低提供给该模块的电压、电流大小。
+-   REGULATOR接口定义了操作REGULATOR设备的通用方法集合，包括：
+    - REGULATOR设备句柄获取和销毁。
+    - REGULATOR设备电压、电流的设置。
+    - REGULATOR设备使能和关闭。
+    - REGULATOR设备电压、电流和状态的获取。
+
+
+### 基本概念<a name="section3"></a> 
+
+-  校准器 
+
+   当输入电压和输出负载发生变化时可以通过软件调整，使其能够提供稳定的输出电压。 
+
+- Consumer
+
+   由REGULATOR供电的设备统称为Consumer， 其可分为静态和动态两类：
+
+   * 静态：不需要改变电压电流，只需要开关电源，通常在bootloader、firmware、kernel board阶段被设置。
+   * 动态：根据操作需求改变电压电流。
+
+- Power Management Ic
+
+   电源管理芯片，内含多个电源甚至其他子系统。 
+
+
+### 运作机制<a name="section4"></a>
+
+在HDF框架中，REGULATOR模块接口适配模式采用统一服务模式，这需要一个设备服务来作为REGULATOR模块的管理器，统一处理外部访问，这会在配置文件中有所体现。统一服务模式适合于同类型设备对象较多的情况，如REGULATOR可能同时具备十几个控制器，采用独立服务模式需要配置更多的设备节点，且服务会占据内存资源。
+
+REGULATOR模块各分层的作用为：接口层提供打开设备，写入数据，关闭设备接口的能力。核心层主要提供绑定设备、初始化设备以及释放设备的能力。适配层实现其他具体的功能。
+
+![](../public_sys-resources/icon-note.gif) 说明：核心层可以调用接口层的函数，也可以通过钩子函数调用适配层函数，从而使得适配层间接的可以调用接口层函数，但是不可逆转接口层调用适配层函数。
+
+图 1 统一服务模式结构图
+
+![image1](figures/统一服务模式结构图.png)
+
+### 约束与限制<a name="section5"></a>
+
+ REGULATOR模块当前仅支持轻量和小型系统内核（LiteOS） 。
+
+## 使用指导<a name="section6"></a>
+
+### 场景介绍<a name="section7"></a>
+
+ REGULATOR主要用于：
+
+1. 用于控制系统中某些设备的电压/电流供应。
+2. 用于稳压电源的管理 。
+
+### 接口说明<a name="section8"></a>

 **表1**  REGULATOR设备API功能介绍

-<a name="table1_REGULATOR_des"></a>
-
-<table border="0" cellpadding="0" cellspacing="0" width="600" style="border-collapse:
- collapse;table-layout:fixed;width:855pt">
- <colgroup><col width="183" style="mso-width-source:userset;mso-width-alt:5856;width:137pt">
- <col width="159" style="mso-width-source:userset;mso-width-alt:5088;width:119pt">
- <col width="213" style="mso-width-source:userset;mso-width-alt:6816;width:160pt">
- </colgroup><tbody><tr height="19" style="height:14.25pt">
-  <td height="19" width="183" style="height:14.25pt;width:137pt">功能分类</td>
-  <td width="159" style="width:119pt">接口名</td>
-  <td width="213" style="width:160pt">描述</td>
- </tr>
- <tr height="19" style="height:14.25pt">
-  <td rowspan="2" height="38" class="xl65" style="height:28.5pt">REGULATOR句柄操作</td>
-  <td>RegulatorOpen</td>
-  <td>获取REGULATOR设备驱动句柄</td>
- </tr>
- <tr height="19" style="height:14.25pt">
-  <td height="19" style="height:14.25pt">RegulatorClose</td>
-  <td>销毁REGULATOR设备驱动句柄</td>
- </tr>
- <tr height="19" style="height:14.25pt">
-  <td rowspan="3" height="57" class="xl65" style="height:42.75pt">使能/禁用REGULATOR</td>
-  <td>RegulatorEnable</td>
-  <td>使能REGULATOR</td>
- </tr>
- <tr height="19" style="height:14.25pt">
-  <td height="19" style="height:14.25pt">RegulatorDisable</td>
-  <td>禁用REGULATOR</td>
- </tr>
- <tr height="19" style="height:14.25pt">
-  <td height="19" style="height:14.25pt">RegulatorForceDisable</td>
-  <td>强制禁用REGULATOR</td>
- </tr>
- <tr height="19" style="height:14.25pt">
-  <td rowspan="2" height="38" class="xl65" style="height:28.5pt">设置/获取REGULATOR输出电压</td>
-  <td>RegulatorSetVoltage</td>
-  <td>设置REGULATOR输出电压</td>
- </tr>
- <tr height="19" style="height:14.25pt">
-  <td height="19" style="height:14.25pt">RegulatorGetVoltage</td>
-  <td>获取REGULATOR输出电压</td>
- </tr>
- <tr height="19" style="height:14.25pt">
-  <td rowspan="2" height="38" class="xl65" style="height:28.5pt">设置/获取REGULATOR输出电流</td>
-  <td>RegulatorSetCurrent</td>
-  <td>设置REGULATOR输出电流</td>
- </tr>
- <tr height="19" style="height:14.25pt">
-  <td height="19" style="height:14.25pt">RegulatorGetCurrent</td>
-  <td>获取REGULATOR输出电流</td>
- </tr>
- <tr height="19" style="height:14.25pt">
-  <td height="19" class="xl66" style="height:14.25pt">获取REGULATOR状态</td>
-  <td>RegulatorGetStatus</td>
-  <td>获取REGULATOR状态</td>
- </tr>
- <!--[if supportMisalignedColumns]-->
- <tr height="0" style="display:none">
-  <td width="183" style="width:137pt"></td>
-  <td width="159" style="width:119pt"></td>
-  <td width="213" style="width:160pt"></td>
- </tr>
- <!--[endif]-->
-</tbody></table>
-
->![](../public_sys-resources/icon-note.gif) **说明：** 
->REGULATOR当前仅限内核态使用，不支持在用户态使用。
-
-## 使用指导<a name="section3_REGULATOR_des"></a>
-
-### 使用流程<a name="section3.1_REGULATOR_des"></a>
+| 接口名                | 描述                      |
+| --------------------- | ------------------------- |
+| RegulatorOpen         | 获取REGULATOR设备驱动句柄 |
+| RegulatorClose        | 销毁REGULATOR设备驱动句柄 |
+| RegulatorEnable       | 使能REGULATOR             |
+| RegulatorDisable      | 禁用REGULATOR             |
+| RegulatorForceDisable | 强制禁用REGULATOR         |
+| RegulatorSetVoltage   | 设置REGULATOR输出电压     |
+| RegulatorGetVoltage   | 获取REGULATOR输出电压     |
+| RegulatorSetCurrent   | 设置REGULATOR输出电流     |
+| RegulatorGetCurrent   | 获取REGULATOR输出电流     |
+| RegulatorGetStatus    | 获取REGULATOR状态         |
+
+
+
+### 开发步骤<a name="section9"></a>

 在操作系统启动过程中，驱动管理模块根据配置文件加载REGULATOR驱动，REGULATOR驱动会检测REGULATOR器件并初始化驱动。

@@ -109,20 +93,19 @@

 **图 1**  REGULATOR设备使用流程图<a name="fig1_REGULATOR_des"></a>  

-
 ![](figures/REGULATOR设备使用流程图.png)

-### 获取REGULATOR设备句柄<a name="section3.2_REGULATOR_des"></a>
+#### 获取REGULATOR设备句柄

 在操作REGULATOR设备时，首先要调用RegulatorOpen获取REGULATOR设备句柄，该函数会返回指定设备名称的REGULATOR设备句柄。

-```c
+```
 DevHandle RegulatorOpen(const char *name);
 ```

 **表2**  RegulatorOpen参数和返回值描述

-<a name="table2_REGULATOR_des"></a>
+<a name="table2"></a>

 | 参数       | 参数描述                      |
 | ---------- | ----------------------------- |
@@ -132,7 +115,8 @@ DevHandle RegulatorOpen(const char *name);
 | NULL       | 获取失败                      |


-```c
+
+```
 /* REGULATOR设备名称 */
 const char *name = "regulator_virtual_1";
 DevHandle handle = NULL;
@@ -144,39 +128,37 @@ if (handle  == NULL) {
 }
 ```

-### 销毁REGULATOR设备句柄<a name="section3.3_REGULATOR_des"></a>
+#### 销毁REGULATOR设备句柄

 关闭REGULATOR设备，系统释放对应的资源。

-```c
+```
 void RegulatorClose(DevHandle handle);
 ```

 **表3**  RegulatorClose参数描述

-<a name="table3_REGULATOR_des"></a>
+<a name="table3"></a>

 | 参数   | 参数描述          |
 | ------ | ----------------- |
 | handle | REGULATOR设备句柄 |

-
-```c
+```
 /* 销毁REGULATOR设备句柄 */
 RegulatorClose(handle);
 ```

-### 使能<a name="section3.4_REGULATOR_des"></a>
+#### 使能<a name="section3.4_REGULATOR_des"></a>

 启用REGULATOR设备。

-```c
+```
 int32_t RegulatorEnable(DevHandle handle);
 ```
-
 **表4** RegulatorEnable参数描述

-<a name="table4_REGULATOR_des"></a>
+<a name="table4"></a>

 | 参数       | 参数描述          |
 | ---------- | ----------------- |
@@ -185,7 +167,9 @@ int32_t RegulatorEnable(DevHandle handle);
 | 0          | 使能成功          |
 | 负数       | 使能失败          |

-```c
+
+
+```
 int32_t ret;

 /*启用REGULATOR设备*/
@@ -195,18 +179,16 @@ if (ret != 0) {
 }
 ```

-### 禁用<a name="section3.5_REGULATOR_des"></a>
+#### 禁用<a name="section3.5_REGULATOR_des"></a>

 禁用REGULATOR设备。

-```c
+```
 int32_t RegulatorDisable(DevHandle handle);
 ```

 **表5** RegulatorDisable参数描述

-<a name="table5_REGULATOR_des"></a>
-
 | 参数       | 参数描述          |
 | ---------- | ----------------- |
 | handle     | REGULATOR设备句柄 |
@@ -214,7 +196,7 @@ int32_t RegulatorDisable(DevHandle handle);
 | 0          | 禁用成功          |
 | 负数       | 禁用失败          |

-```c
+```
 int32_t ret;

 /*禁用REGULATOR设备，如果REGULATOR设备状态为常开，或存在REGULATOR设备子节点未禁用，则禁用失败*/
@@ -224,26 +206,26 @@ if (ret != 0) {
 }
 ```

-### 强制禁用<a name="section3.6_REGULATOR_des"></a>
+#### 强制禁用<a name="section3.6_REGULATOR_des"></a>

 强制禁用REGULATOR设备。

-```c
+```
 int32_t RegulatorForceDisable(DevHandle handle);
 ```

-**表6** RegulatorForceDisable参数描述
+**表5** RegulatorDisable参数描述

-<a name="table6_REGULATOR_des"></a>
+<a name="table5_REGULATOR_des"></a>

 | 参数       | 参数描述          |
 | ---------- | ----------------- |
 | handle     | REGULATOR设备句柄 |
 | **返回值** | **返回值描述**    |
-| 0          | 强制禁用成功      |
-| 负数       | 强制禁用失败      |
+| 0          | 禁用成功          |
+| 负数       | 禁用失败          |

-```c
+```
 int32_t ret;

 /*强制禁用REGULATOR设备，无论REGULATOR设备的状态是常开还是子节点已使能，REGULATOR设备都会被禁用*/
@@ -252,11 +234,12 @@ if (ret != 0) {
 	/*错误处理*/
 }
 ```
-### 设置REGULATOR输出电压范围<a name="section3.7_REGULATOR_des"></a>
+
+#### 设置REGULATOR输出电压范围<a name="section3.7_REGULATOR_des"></a>

 设置REGULATOR电压输出电压范围。

-```c
+```
 int32_t RegulatorSetVoltage(DevHandle handle, uint32_t minUv, uint32_t maxUv);
 ```

@@ -273,7 +256,7 @@ int32_t RegulatorSetVoltage(DevHandle handle, uint32_t minUv, uint32_t maxUv);
 | 0          | 设置成功          |
 | 负数       | 设置失败          |

-```c
+```
 int32_t ret;
 int32_t minUv = 0;		//最小电压为0Uv
 int32_t maxUv = 20000;  //最大电压为20000Uv
@@ -284,11 +267,12 @@ if (ret != 0) {
 	/*错误处理*/
 }
 ```
-### 获取REGULATOR电压<a name="section3.8_REGULATOR_des"></a>
+
+#### 获取REGULATOR电压<a name="section3.8_REGULATOR_des"></a>

 获取REGULATOR电压。

-```c
+```
 int32_t RegulatorGetVoltage(DevHandle handle, uint32_t *voltage);
 ```

@@ -304,7 +288,7 @@ int32_t RegulatorGetVoltage(DevHandle handle, uint32_t *voltage);
 | 0          | 获取成功          |
 | 负数       | 获取失败          |

-```c
+```
 int32_t ret;
 uint32_t voltage;

@@ -315,12 +299,11 @@ if (ret != 0) {
 }
 ```

-
-### 设置REGULATOR输出电流范围<a name="section3.9_REGULATOR_des"></a>
+#### 设置REGULATOR输出电流范围<a name="section3.9_REGULATOR_des"></a>

 设置REGULATOR输出电流范围。

-```c
+```
 int32_t RegulatorSetCurrent(DevHandle handle, uint32_t minUa, uint32_t maxUa);
 ```

@@ -337,10 +320,10 @@ int32_t RegulatorSetCurrent(DevHandle handle, uint32_t minUa, uint32_t maxUa);
 | 0          | 设置成功          |
 | 负数       | 设置失败          |

-```c
+```
 int32_t ret;
 int32_t minUa = 0;		//最小电流为0Ua
-int32_t maxUa = 200;  //最大电流为200Ua
+int32_t maxUa = 200;    //最大电流为200Ua

 /*设置REGULATOR输出电流范围*/
 ret = RegulatorSetCurrent(handle, minUa, maxUa);
@@ -349,11 +332,11 @@ if (ret != 0) {
 }
 ```

-### 获取REGULATOR电流<a name="section3.10_REGULATOR_des"></a>
+#### 获取REGULATOR电流<a name="section3.10_REGULATOR_des"></a>

 获取REGULATOR电流。

-```c
+```
 int32_t RegulatorGetCurrent(DevHandle handle, uint32_t *regCurrent);
 ```

@@ -369,7 +352,7 @@ int32_t RegulatorGetCurrent(DevHandle handle, uint32_t *regCurrent);
 | 0           | 获取成功          |
 | 负数        | 获取失败          |

-```c
+```
 int32_t ret;
 uint32_t regCurrent;

@@ -379,17 +362,18 @@ if (ret != 0) {
 	/*错误处理*/
 }
 ```
-### 获取REGULATOR状态<a name="section3.11_REGULATOR_des"></a>
+
+#### 获取REGULATOR状态<a name="section3.11_REGULATOR_des"></a>

 获取REGULATOR状态。

-```c
+```
 int32_t RegulatorGetStatus(DevHandle handle, uint32_t *status);
 ```

-**表11** RegulatorGetStatus参数描述
+**表10** RegulatorGetCurrent参数描述

-<a name="table11_REGULATOR_des"></a>
+<a name="table10_REGULATOR_des"></a>

 | 参数       | 参数描述          |
 | ---------- | ----------------- |
@@ -399,7 +383,7 @@ int32_t RegulatorGetStatus(DevHandle handle, uint32_t *status);
 | 0          | 获取成功          |
 | 负数       | 获取失败          |

-```c
+```
 int32_t ret;
 uint32_t status;

@@ -410,11 +394,13 @@ if (ret != 0) {
 }
 ```

-## 使用实例<a name="section4_REGULATOR_des"></a>
+
+
+## 使用实例<a name="section10"></a>

 REGULATOR设备完整的使用示例如下所示，首先获取REGULATOR设备句柄，然后使能，设置电压，获取电压、状态，禁用，最后销毁REGULATOR设备句柄。

-```c
+```
 void RegulatorTestSample(void)
 {
    int32_t ret;
@@ -476,4 +462,4 @@ _ERR:
    /* 销毁REGULATOR设备句柄 */
    RegulatorClose(handle); 
 }
-```
\ No newline at end of file
+```
--- a/zh-cn/device-dev/driver/driver-platform-regulator-develop.md
+++ b/zh-cn/device-dev/driver/driver-platform-regulator-develop.md