Skip to content

D
Docs

OpenHarmony / Docs
1 年多 前同步成功

通知 159
Star 292
Fork 28
D
Docs
提交 b51448e3 编写于 作者: Z zhangyalei
浏览文件
操作

regulator documentation update 

Signed-off-by: Nzhangyalei <zhangyalei7@huawei.com>
上级 052cecf7
隐藏空白更改
内联 并排
Showing with 420 addition and 418 deletion
zh-cn/device-dev/driver/driver-platform-regulator-des.md
浏览文件 @ b51448e3
# 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
```
zh-cn/device-dev/driver/driver-platform-regulator-develop.md
浏览文件 @ b51448e3
# REGULATOR<a name="title_REGULATORDevelop"></a>
# REGULATOR
- [概述](#section1_REGULATORDevelop)
- [接口说明](#section2_REGULATORDevelop)
- [开发步骤](#section3_REGULATORDevelop)
- [开发实例](#section4_REGULATORDevelop)
- [概述](#1)
- [功能简介](#2)
- [基本概念](#3)
- [运作机制](#4)
- [约束与限制](#5)
- [开发指导](#6)
- [场景介绍](#7)
- [接口说明](#8)
- [开发步骤](#9)
## 概述 <a name="section1_REGULATORDevelop"></a>
## 概述<a name="1"></a>
REGULATOR模块用于控制系统中某些设备的电压/电流供应。在HDF框架中，REGULATOR模块接口适配模式采用统一服务模式，这需要一个设备服务来作为REGULATOR模块的管理器，统一处理外部访问，这会在配置文件中有所体现。统一服务模式适合于同类型设备对象较多的情况，如REGULATOR可能同时具备十几个控制器，采用独立服务模式需要配置更多的设备节点，且服务会占据内存资源。
### 功能简介<a name="2"></a>
REGULATOR模块用于控制系统中某些设备的电压/电流供应。
### 基本概念<a name="3"></a>
REGULATOR模块用于控制系统中某些设备的电压/电流供应。在嵌入式系统（尤其是手机）中，控制耗电量很重要，直接影响到电池的续航时间。所以，如果系统中某一个模块暂时不需要使用，就可以通过REGULATOR关闭其电源供应；或者降低提供给该模块的电压、电流大小。
### 运作机制<a name="4"></a>
在HDF框架中，REGULATOR模块接口适配模式采用统一服务模式，这需要一个设备服务来作为REGULATOR模块的管理器，统一处理外部访问，这会在配置文件中有所体现。统一服务模式适合于同类型设备对象较多的情况，如REGULATOR可能同时具备十几个控制器，采用独立服务模式需要配置更多的设备节点，且服务会占据内存资源。
REGULATOR模块各分层的作用为：接口层提供打开设备，写入数据，关闭设备接口的能力。核心层主要提供绑定设备、初始化设备以及释放设备的能力。适配层实现其他具体的功能。
![](../public_sys-resources/icon-note.gif) 说明：核心层可以调用接口层的函数，也可以通过钩子函数调用适配层函数，从而使得适配层间接的可以调用接口层函数，但是不可逆转接口层调用适配层函数。
图 1 统一服务模式结构图
![image1](figures/统一服务模式结构图.png)
## 接口说明<a name="section2_REGULATORDevelop"></a>
RegulatorMethod 定义：
```c
### 约束与限制<a name="5"></a>
REGULATOR模块当前仅支持轻量和小型系统内核（LiteOS） 。
## 开发指导<a name="6"></a>
### 场景介绍<a name="7"></a>
REGULATOR模块用于控制系统中某些设备的电压/电流供应。
### 接口说明<a name="8"></a>
通过以下RegulatorMethod中的函数调用REGULATOR驱动对应的函数。
RegulatorMethod定义：
```
struct RegulatorMethod {
int32_t (*open)(struct RegulatorNode *node);
int32_t (*close)(struct RegulatorNode *node);
......@@ -32,78 +68,73 @@ struct RegulatorMethod {
};
```
**表 1** RegulatorMethod 成员的回调函数功能说明
**表 1** RegulatorMethod 结构体成员的回调函数功能说明
| 成员函数 | 入参 | 返回值 | 功能 |
| ------------ | ------------------------------------------- | ------ | ---- |
| open | **node**：结构体指针，核心层regulator节点； |HDF_STATUS相关状态|打开设备|
| close | **node**：结构体指针，核心层regulator节点； | HDF_STATUS相关状态 | 关闭设备 |
| release | **node**：结构体指针，核心层regulator节点； | HDF_STATUS相关状态 | 释放设备句柄 |
| enable | **node**：结构体指针，核心层regulator节点； | HDF_STATUS相关状态 | 使能 |
| disable | **node**：结构体指针，核心层regulator节点； | HDF_STATUS相关状态 | 禁用 |
| forceDisable | **node**：结构体指针，核心层regulator节点； | HDF_STATUS相关状态 | 强制禁用 |
| setVoltage | **node**：结构体指针，核心层regulator节点；<br>**minUv**：uint32_t变量，最小电压；<br>**maxUv**：uint32_t变量，最大电压； | HDF_STATUS相关状态 | 设置输出电压范围 |
| getVoltage | **node**：结构体指针，核心层regulator节点；<br>**voltage**：uint32_t指针，传出电压值； | HDF_STATUS相关状态 | 获取电压 |
| setCurrent | **node**：结构体指针，核心层regulator节点；<br>**minUa**：uint32_t变量，最小电流；<br>**maxUa**：uint32_t变量，最大电流； | HDF_STATUS相关状态 | 设置输出电流范围 |
| getCurrent | **node**：结构体指针，核心层regulator节点；<br>**regCurrent**：uint32_t指针，传出电流值； | HDF_STATUS相关状态 | 获取电流 |
| getStatus | **node**：结构体指针，核心层regulator节点；<br>**status**：uint32_t指针，传出状态值； | HDF_STATUS相关状态 | 获取设备状态 |
<a name="table27410339187"></a>
## 开发步骤 <a name="section3_REGULATORDevelop"></a>
REGULATOR模块适配的三个环节是实例化驱动入口、配置属性文件、以及实例化核心层接口函数。
1. **实例化驱动入口：**
- 实例化HdfDriverEntry结构体成员。
- 调用HDF_INIT将HdfDriverEntry实例化对象注册到HDF框架中。
2. **配置属性文件：**
| 成员函数 | 入参 | 返回值 | 功能 |
| ------------ | ------------------------------------------------------------ | ------------------ | ---------------- |
| open | **node**：结构体指针，核心层regulator节点； | HDF_STATUS相关状态 | 打开设备 |
| close | **node**：结构体指针，核心层regulator节点； | HDF_STATUS相关状态 | 关闭设备 |
| release | **node**：结构体指针，核心层regulator节点； | HDF_STATUS相关状态 | 释放设备句柄 |
| enable | **node**：结构体指针，核心层regulator节点； | HDF_STATUS相关状态 | 使能 |
| disable | **node**：结构体指针，核心层regulator节点； | HDF_STATUS相关状态 | 禁用 |
| forceDisable | **node**：结构体指针，核心层regulator节点； | HDF_STATUS相关状态 | 强制禁用 |
| setVoltage | **node**：结构体指针，核心层regulator节点； **minUv**：uint32_t变量，最小电压； **maxUv**：uint32_t变量，最大电压； | HDF_STATUS相关状态 | 设置输出电压范围 |
| getVoltage | **node**：结构体指针，核心层regulator节点； **voltage**：uint32_t指针，传出电压值； | HDF_STATUS相关状态 | 获取电压 |
| setCurrent | **node**：结构体指针，核心层regulator节点； **minUa**：uint32_t变量，最小电流； **maxUa**：uint32_t变量，最大电流； | HDF_STATUS相关状态 | 设置输出电流范围 |
| getCurrent | **node**：结构体指针，核心层regulator节点； **regCurrent**：uint32_t指针，传出电流值； | HDF_STATUS相关状态 | 获取电流 |
| getStatus | **node**：结构体指针，核心层regulator节点； **status**：uint32_t指针，传出状态值； | HDF_STATUS相关状态 | 获取设备状态 |
- 在device_info.hcs文件中添加deviceNode描述。
- 【可选】添加regulator_config.hcs器件属性文件。
### 开发步骤<a name="9"></a>
3. **实例化REGULATOR控制器对象：**
- 初始化RegulatorNode成员。
- 实例化RegulatorNode成员RegulatorMethod。
>![](../public_sys-resources/icon-note.gif) **说明：**
>实例化RegulatorNode成员RegulatorMethod，其定义和成员说明见[接口说明](#section2_REGULATORDevelop)。
4. **驱动调试：**
- 【可选】针对新增驱动程序，建议验证驱动基本功能，例如挂载后的信息反馈，数据传输的成功与否等。
REGULATOR模块适配包含以下四个步骤：
## 开发实例 <a name="section4_REGULATORDevelop"></a>
- 实例化驱动入口。
- 配置属性文件。
- 实例化核心层接口函数。
- 驱动调试。
下方将以regulator_virtual.c为示例，展示需要厂商提供哪些内容来完整实现设备功能。
1. **实例化驱动入口：**
1. 驱动开发首先需要实例化驱动入口，驱动入口必须为HdfDriverEntry（在 hdf\_device\_desc.h 中定义）类型的全局变量，且moduleName要和device\_info.hcs中保持一致。HDF框架会将所有加载的驱动的HdfDriverEntry对象首地址汇总，形成一个类似数组的段地址空间，方便上层调用。
驱动开发首先需要实例化驱动入口，驱动入口必须为HdfDriverEntry（在 hdf_device_desc.h 中定义）类型的全局变量，且moduleName要和device_info.hcs中保持一致。 HDF框架会汇总所有加载的驱动的HdfDriverEntry对象入口 ，形成一个类似数组的段地址空间，方便上层调用。
一般在加载驱动时HDF会先调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。
```
struct HdfDriverEntry g_regulatorDriverEntry = {
.moduleVersion = 1,
.moduleName = "virtual_regulator_driver",//【必要且与HCS文件中里面的moduleName匹配】
.Init = VirtualRegulatorInit,
.Release = VirtualRegulatorRelease,
};
//调用HDF_INIT将驱动入口注册到HDF框架中
HDF_INIT(g_regulatorDriverEntry);
```
2. **配置属性文件：**
一般在加载驱动时HDF会先调用Bind函数，再调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。
- 在vendor/hisilicon/hispark_taurus/hdf_config/device_info/device_info.hcs文件中添加deviceNode描述。
REGULATOR驱动入口参考
deviceNode信息与驱动入口注册相关，器件属性值与核心层RegulatorNode成员的默认值或限制范围有密切关系。
```c
struct HdfDriverEntry g_regulatorDriverEntry = {
.moduleVersion = 1,
.moduleName = "virtual_regulator_driver",//【必要且与HCS文件中里面的moduleName匹配】
.Init = VirtualRegulatorInit,
.Release = VirtualRegulatorRelease,
};
//调用HDF_INIT将驱动入口注册到HDF框架中
HDF_INIT(g_regulatorDriverEntry);
```
由于采用了统一服务模式，device_info.hcs文件中第一个设备节点必须为REGULATOR管理器，其各项参数必须如下设置：
2. 完成驱动入口注册之后，下一步请在device\_info.hcs文件中添加deviceNode信息，并在regulator\_config.hcs中配置器件属性。deviceNode信息与驱动入口注册相关，器件属性值与核心层RegulatorNode成员的默认值或限制范围有密切关系。
| 成员名 | 值 |
| --------------- | ------------------------------------------------------------ |
| policy | 具体配置为0，不发布服务 |
| priority | 驱动启动优先级（0-200），值越大优先级越低,，优先级相同则不保证device的加载顺序。 |
| permission | 驱动权限 |
| moduleName | 固定为 HDF_PLATFORM_REGULATOR_MANAGER |
| serviceName | 固定为HDF_PLATFORM_REGULATOR_MANAGER |
| deviceMatchAttr | 没有使用，可忽略 |
>![](W:\docs\zh-cn\device-dev\public_sys-resources\icon-note.gif) **说明：**
>如有更多个器件信息，则需要在device\_info文件增加deviceNode信息，以及在regulator\_config文件中增加对应的器件属性。
从第二个节点开始配置具体REGULATOR控制器信息，此节点并不表示某一路REGULATOR控制器，而是代表一个资源性质设备，用于描述一类REGULATOR控制器的信息。本例只有一个REGULATOR设备，如有多个设备，则需要在device_info文件增加deviceNode信息，以及在regulator\_config文件中增加对应的器件属性。
- device\_info.hcs 配置参考。
- device_info.hcs 配置参考。
```c
root {
```
root {
device_info {
platform :: host {
hostName = "platform_host";
......@@ -129,211 +160,196 @@ REGULATOR模块适配的三个环节是实例化驱动入口、配置属性文
}
}
}
}
```
- regulator\_config.hcs 配置参考。
```c
root {
platform {
regulator_config {
match_attr = "linux_regulator_adapter";
template regulator_controller { //【必要】模板配置，继承该模板的节点如果使用模板中的默认值，则节点字段可以缺省
device_num = 1;
name = "";
devName = "regulator_adapter_consumer01";
supplyName = "";
mode = 1;
minUv = 0;
maxUv = 20000;
minUa = 0;
maxUa = 0;
}
controller_0x130d0000 :: regulator_controller {
device_num = 1;
name = "regulator_adapter_1";
devName = "regulator_adapter_consumer01";
supplyName = "virtual-regulator-hdf-adapter";
mode = 1;
minUv = 1000;
maxUv = 50000;
minUa = 0;
maxUa = 0;
}
/*每个Regulator控制器对应一个controller节点，如存在多个Regulator控制器，请依次添加对应的controller节点。*/
controller_0x130d0001 :: regulator_controller {
device_num = 1;
name = "regulator_adapter_2";
devName = "regulator_adapter_consumer01";
supplyName = "virtual2-regulator-hdf-adapter";
mode = 2;
minUv = 0;
maxUv = 0;
minUa = 1000;
maxUa = 50000;
}
}
}
}
```
3. 完成驱动入口注册之后，最后一步就是对核心层RegulatorNode对象的初始化，包括厂商自定义结构体（传递参数和数据），实例化RegulatorNode成员RegulatorMethod（让用户可以通过接口来调用驱动底层函数），实现HdfDriverEntry成员函数（Bind，Init，Release）。
- 自定义结构体参考。
从驱动的角度看，RegulatorNode结构体是参数和数据的载体，HDF框架通过DeviceResourceIface将regulator\_config.hcs文件中的数值读入其中。
```c
// RegulatorNode是核心层控制器结构体，其中的成员在Init函数中会被赋值
struct RegulatorNode {
struct RegulatorDesc regulatorInfo;
struct DListHead node;
struct RegulatorMethod *ops;
void *priv;
struct OsalMutex lock;
};
struct RegulatorDesc {
const char *name; /* regulator 名称 */
const char *parentName; /* regulator 父节点名称 */
struct RegulatorConstraints constraints; /* regulator 约束信息 */
uint32_t minUv; /* 最小输出电压值 */
uint32_t maxUv; /* 最大输出电压值 */
uint32_t minUa; /* 最小输出电流值 */
uint32_t maxUa; /* 最大输出电流值 */
uint32_t status; /* regulator的状态，开或关 */
int useCount;
int consumerRegNums; /* regulator用户数量 */
RegulatorStatusChangecb cb; /* 当regulator状态改变时，可通过此变量通知 */
};
struct RegulatorConstraints {
uint8_t alwaysOn; /* regulator是否常开 */
uint8_t mode; /* 模式：电压或者电流 */
uint32_t minUv; /* 最小可设置输出电压 */
uint32_t maxUv; /* 最大可设置输出电压 */
uint32_t minUa; /* 最小可设置输出电流 */
uint32_t maxUa; /* 最大可设置输出电流 */
};
```
- 实例化RegulatorNode成员RegulatorMethod，其他成员在Init函数中初始化。
```c
// regulator_virtual.c 中的示例：钩子函数的填充
static struct RegulatorMethod g_method = {
.enable = VirtualRegulatorEnable,
.disable = VirtualRegulatorDisable,
.setVoltage = VirtualRegulatorSetVoltage,
.getVoltage = VirtualRegulatorGetVoltage,
.setCurrent = VirtualRegulatorSetCurrent,
.getCurrent = VirtualRegulatorGetCurrent,
.getStatus = VirtualRegulatorGetStatus,
};
```
- Init函数参考
入参：
HdfDeviceObject 是整个驱动对外暴露的接口参数，具备 HCS 配置文件的信息。
返回值：
HDF\_STATUS相关状态 （下表为部分展示，如需使用其他状态，可见//drivers/framework/include/utils/hdf\_base.h中HDF\_STATUS 定义）。
**表 2** HDF\_STATUS相关状态
<table><thead align="left"><tr id="row31521027164144"><th class="cellrowborder" valign="top" width="50%" id="mcps1.1.3.1.1"><p id="entry1990732428164144p0"><a name="entry1990732428164144p0"></a><a name="entry1990732428164144p0"></a>状态(值)</p>
</th>
<th class="cellrowborder" valign="top" width="50%" id="mcps1.1.3.1.2"><p id="entry2123581292164144p0"><a name="entry2123581292164144p0"></a><a name="entry2123581292164144p0"></a>问题描述</p>
</th>
</tr>
</thead>
<tbody><tr id="row1749271383164144"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.1.3.1.1 "><p id="entry202330388164144p0"><a name="entry202330388164144p0"></a><a name="entry202330388164144p0"></a>HDF_ERR_INVALID_OBJECT</p>
</td>
<td class="cellrowborder" valign="top" width="50%" headers="mcps1.1.3.1.2 "><p id="entry1717598064164144p0"><a name="entry1717598064164144p0"></a><a name="entry1717598064164144p0"></a>控制器对象非法</p>
</td>
</tr>
<tr id="row1715354988164144"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.1.3.1.1 "><p id="entry450625221164144p0"><a name="entry450625221164144p0"></a><a name="entry450625221164144p0"></a>HDF_ERR_MALLOC_FAIL</p>
</td>
<td class="cellrowborder" valign="top" width="50%" headers="mcps1.1.3.1.2 "><p id="entry361497788164144p0"><a name="entry361497788164144p0"></a><a name="entry361497788164144p0"></a>内存分配失败</p>
</td>
</tr>
<tr id="row1202091366164144"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.1.3.1.1 "><p id="entry370837906164144p0"><a name="entry370837906164144p0"></a><a name="entry370837906164144p0"></a>HDF_ERR_INVALID_PARAM</p>
</td>
<td class="cellrowborder" valign="top" width="50%" headers="mcps1.1.3.1.2 "><p id="entry353311523164144p0"><a name="entry353311523164144p0"></a><a name="entry353311523164144p0"></a>参数非法</p>
</td>
</tr>
<tr id="row602018308164144"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.1.3.1.1 "><p id="entry1984036607164144p0"><a name="entry1984036607164144p0"></a><a name="entry1984036607164144p0"></a>HDF_ERR_IO</p>
</td>
<td class="cellrowborder" valign="top" width="50%" headers="mcps1.1.3.1.2 "><p id="entry1221756048164144p0"><a name="entry1221756048164144p0"></a><a name="entry1221756048164144p0"></a>I/O 错误</p>
</td>
</tr>
<tr id="row47997479164144"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.1.3.1.1 "><p id="entry1220816374164144p0"><a name="entry1220816374164144p0"></a><a name="entry1220816374164144p0"></a>HDF_SUCCESS</p>
</td>
<td class="cellrowborder" valign="top" width="50%" headers="mcps1.1.3.1.2 "><p id="entry1903499126164144p0"><a name="entry1903499126164144p0"></a><a name="entry1903499126164144p0"></a>初始化成功</p>
</td>
</tr>
<tr id="row2031856197164144"><td class="cellrowborder" valign="top" width="50%" headers="mcps1.1.3.1.1 "><p id="entry463793674164144p0"><a name="entry463793674164144p0"></a><a name="entry463793674164144p0"></a>HDF_FAILURE</p>
</td>
<td class="cellrowborder" valign="top" width="50%" headers="mcps1.1.3.1.2 "><p id="entry516362874164144p0"><a name="entry516362874164144p0"></a><a name="entry516362874164144p0"></a>初始化失败</p>
</td>
</tr>
</tbody>
</table>
函数说明：
初始化自定义结构体和RegulatorNode成员，并通过调用核心层RegulatorNodeAdd函数挂载Regulator控制器。
```c
static int32_t VirtualRegulatorInit(struct HdfDeviceObject *device)
{
int32_t ret;
const struct DeviceResourceNode *childNode = NULL;
...
DEV_RES_NODE_FOR_EACH_CHILD_NODE(device->property, childNode) {
ret = VirtualRegulatorParseAndInit(device, childNode);//【必要】实现见下
...
}
...
}
static int32_t VirtualRegulatorParseAndInit(struct HdfDeviceObject *device, const struct DeviceResourceNode *node)
{
int32_t ret;
struct RegulatorNode *regNode = NULL;
(void)device;
regNode = (struct RegulatorNode *)OsalMemCalloc(sizeof(*regNode));//加载HCS文件
...
ret = VirtualRegulatorReadHcs(regNode, node);//读取HCS文件信息
...
regNode->priv = (void *)node; //实例化节点
regNode->ops = &g_method; //实例化ops
ret = RegulatorNodeAdd(regNode); //挂载节点
...
}
- Release 函数参考
}
```
- regulator\_config.hcs 配置参考。
```
root {
platform {
regulator_config {
match_attr = "linux_regulator_adapter";
template regulator_controller { //【必要】模板配置，继承该模板的节点如果使用模板中的默认值，则节点字段可以缺省
device_num = 1;
name = "";
devName = "regulator_adapter_consumer01";
supplyName = "";
mode = 1;
minUv = 0;
maxUv = 20000;
minUa = 0;
maxUa = 0;
}
controller_0x130d0000 :: regulator_controller {
device_num = 1;
name = "regulator_adapter_1";
devName = "regulator_adapter_consumer01";
supplyName = "virtual-regulator-hdf-adapter";
mode = 1;
minUv = 1000;
maxUv = 50000;
minUa = 0;
maxUa = 0;
}
/*每个Regulator控制器对应一个controller节点，如存在多个Regulator控制器，请依次添加对应的controller节点。*/
controller_0x130d0001 :: regulator_controller {
device_num = 1;
name = "regulator_adapter_2";
devName = "regulator_adapter_consumer01";
supplyName = "virtual2-regulator-hdf-adapter";
mode = 2;
minUv = 0;
maxUv = 0;
minUa = 1000;
maxUa = 50000;
}
}
}
}
```
3. **实例化核心层接口函数：**
- 完成驱动入口注册之后，最后一步就是对核心层RegulatorNode对象的初始化，包括厂商自定义结构体（传递参数和数据），实例化RegulatorNode成员RegulatorMethod（让用户可以通过接口来调用驱动底层函数），实现HdfDriverEntry成员函数（Bind，Init，Release）。
- 自定义结构体参考。
从驱动的角度看，RegulatorNode结构体是参数和数据的载体，HDF框架通过DeviceResourceIface将regulator\_config.hcs文件中的数值读入其中。
```
// RegulatorNode是核心层控制器结构体，其中的成员在Init函数中会被赋值
struct RegulatorNode {
struct RegulatorDesc regulatorInfo;
struct DListHead node;
struct RegulatorMethod *ops;
void *priv;
struct OsalMutex lock;
};
struct RegulatorDesc {
const char *name; /* regulator 名称 */
const char *parentName; /* regulator 父节点名称 */
struct RegulatorConstraints constraints; /* regulator 约束信息 */
uint32_t minUv; /* 最小输出电压值 */
uint32_t maxUv; /* 最大输出电压值 */
uint32_t minUa; /* 最小输出电流值 */
uint32_t maxUa; /* 最大输出电流值 */
uint32_t status; /* regulator的状态，开或关 */
int useCount;
int consumerRegNums; /* regulator用户数量 */
RegulatorStatusChangecb cb; /* 当regulator状态改变时，可通过此变量通知 */
};
struct RegulatorConstraints {
uint8_t alwaysOn; /* regulator是否常开 */
uint8_t mode; /* 模式：电压或者电流 */
uint32_t minUv; /* 最小可设置输出电压 */
uint32_t maxUv; /* 最大可设置输出电压 */
uint32_t minUa; /* 最小可设置输出电流 */
uint32_t maxUa; /* 最大可设置输出电流 */
};
```
- 实例化RegulatorNode成员RegulatorMethod，其他成员在Init函数中初始化。
```c
// regulator_virtual.c 中的示例：钩子函数的填充
static struct RegulatorMethod g_method = {
.enable = VirtualRegulatorEnable,
.disable = VirtualRegulatorDisable,
.setVoltage = VirtualRegulatorSetVoltage,
.getVoltage = VirtualRegulatorGetVoltage,
.setCurrent = VirtualRegulatorSetCurrent,
.getCurrent = VirtualRegulatorGetCurrent,
.getStatus = VirtualRegulatorGetStatus,
};
```
- Init函数参考
入参：
HdfDeviceObject是整个驱动对外暴露的接口参数，其包含了HCS配置文件中的相关配置信息。
HdfDeviceObject 是整个驱动对外暴露的接口参数，具备 HCS 配置文件的信息。
返回值：
无。
函数说明：
释放内存和删除控制器，该函数需要在驱动入口结构体中赋值给Release接口，当HDF框架调用Init函数初始化驱动失败时，可以调用Release释放驱动资源。
HDF\_STATUS相关状态 （下表为部分展示，如需使用其他状态，可见//drivers/framework/include/utils/hdf\_base.h中HDF\_STATUS 定义）。
**表 2** HDF\_STATUS相关状态
| 状态(值) | 问题描述 |
| ---------------------- | -------------- |
| HDF_ERR_INVALID_OBJECT | 控制器对象非法 |
| HDF_ERR_MALLOC_FAIL | 内存分配失败 |
| HDF_ERR_INVALID_PARAM | 参数非法 |
| HDF_ERR_IO | I/O 错误 |
| HDF_SUCCESS | 初始化成功 |
| HDF_FAILURE | 初始化失败 |
函数说明：
初始化自定义结构体和RegulatorNode成员，并通过调用核心层RegulatorNodeAdd函数挂载Regulator控制器。
```c
static int32_t VirtualRegulatorInit(struct HdfDeviceObject *device)
{
int32_t ret;
const struct DeviceResourceNode *childNode = NULL;
...
DEV_RES_NODE_FOR_EACH_CHILD_NODE(device->property, childNode) {
ret = VirtualRegulatorParseAndInit(device, childNode);//【必要】实现见下
...
}
...
}
static int32_t VirtualRegulatorParseAndInit(struct HdfDeviceObject *device, const struct DeviceResourceNode *node)
{
int32_t ret;
struct RegulatorNode *regNode = NULL;
(void)device;
regNode = (struct RegulatorNode *)OsalMemCalloc(sizeof(*regNode));//加载HCS文件
...
ret = VirtualRegulatorReadHcs(regNode, node);//读取HCS文件信息
...
regNode->priv = (void *)node; //实例化节点
regNode->ops = &g_method; //实例化ops
ret = RegulatorNodeAdd(regNode); //挂载节点
...
}
```
- Release 函数参考
入参：
HdfDeviceObject是整个驱动对外暴露的接口参数，其包含了HCS配置文件中的相关配置信息。
返回值：
无。
函数说明:
释放内存和删除控制器，该函数需要在驱动入口结构体中赋值给Release接口，当HDF框架调用Init函数 初始化驱动失败时，可以调用Release释放驱动资源。
```c
static void VirtualRegulatorRelease(struct HdfDeviceObject *device)
{
...
RegulatorNodeRemoveAll();//【必要】调用核心层函数，释放RegulatorNode的设备和服务
}
```
4. **驱动调试：**
【可选】针对新增驱动程序，建议验证驱动基本功能，例如挂载后的测试用例是否成功等。
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或