Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
未验证 提交 f4009826 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!2551 修改Regulator模块相关内源问题 

Merge pull request !2551 from liyan/master
上级 1929ed27 328ec875
隐藏空白更改
内联 并排
Showing with 224 addition and 260 deletion
zh-cn/device-dev/driver/driver-platform-regulator-des.md
浏览文件 @ f4009826
# REGULATOR<a name="1"></a> # Regulator
- [概述](#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设备的通用方法集合，包括：
- REGULATOR设备句柄获取和销毁。 - Regulator设备句柄获取和销毁。
- REGULATOR设备电压、电流的设置。 - Regulator设备电压、电流的设置。
- REGULATOR设备使能和关闭。 - Regulator设备使能和关闭。
- REGULATOR设备电压、电流和状态的获取。 - Regulator设备电压、电流和状态的获取。
### 基本概念<a name="section3"></a> ### 基本概念
- 校准器 - 校准器
...@@ -31,73 +21,73 @@ ...@@ -31,73 +21,73 @@
- Consumer - Consumer
由REGULATOR供电的设备统称为Consumer， 其可分为静态和动态两类： 由Regulator供电的设备统称为Consumer， 其可分为静态和动态两类：
* 静态：不需要改变电压电流，只需要开关电源，通常在bootloader、firmware、kernel board阶段被设置。 * 静态：不需要改变电压电流，只需要开关电源，通常在bootloader、firmware、kernel board阶段被设置。
* 动态：根据操作需求改变电压电流。 * 动态：根据操作需求改变电压电流。
- Power Management Ic - PMIC（Power Management IC）
电源管理芯片，内含多个电源甚至其他子系统。 电源管理芯片，内含多个电源甚至其他子系统。
### 运作机制<a name="section4"></a> ### 运作机制
在HDF框架中，REGULATOR模块接口适配模式采用统一服务模式，这需要一个设备服务来作为REGULATOR模块的管理器，统一处理外部访问，这会在配置文件中有所体现。统一服务模式适合于同类型设备对象较多的情况，如REGULATOR可能同时具备十几个控制器，采用独立服务模式需要配置更多的设备节点，且服务会占据内存资源。 在HDF框架中，Regulator模块接口适配模式采用统一服务模式，这需要一个设备服务来作为Regulator模块的管理器，统一处理外部访问，这会在配置文件中有所体现。统一服务模式适合于同类型设备对象较多的情况，如Regulator可能同时具备十几个控制器，采用独立服务模式需要配置更多的设备节点，且服务会占据内存资源。
REGULATOR模块各分层的作用为：接口层提供打开设备，写入数据，关闭设备接口的能力。核心层主要提供绑定设备、初始化设备以及释放设备的能力。适配层实现其他具体的功能。 Regulator模块各分层的作用为：接口层提供打开设备，写入数据，关闭设备接口的能力。核心层主要提供绑定设备、初始化设备以及释放设备的能力。适配层实现其他具体的功能。
![](../public_sys-resources/icon-note.gif) 说明：核心层可以调用接口层的函数，也可以通过钩子函数调用适配层函数，从而使得适配层间接的可以调用接口层函数，但是不可逆转接口层调用适配层函数。 ![](../public_sys-resources/icon-note.gif) 说明：核心层可以调用接口层的函数，也可以通过钩子函数调用适配层函数，从而使得适配层间接的可以调用接口层函数，但是不可逆转接口层调用适配层函数。
图 1 统一服务模式结构图 **图 1** 统一服务模式结构图
![image1](figures/统一服务模式结构图.png) ![image1](figures/统一服务模式结构图.png)
### 约束与限制<a name="section5"></a> ### 约束与限制
REGULATOR模块当前仅支持轻量和小型系统内核（LiteOS） 。 Regulator模块当前仅支持轻量和小型系统内核（LiteOS） 。
## 使用指导<a name="section6"></a> ## 使用指导
### 场景介绍<a name="section7"></a> ### 场景介绍
REGULATOR主要用于： Regulator主要用于：
1. 用于控制系统中某些设备的电压/电流供应。 1. 用于控制系统中某些设备的电压/电流供应。
2. 用于稳压电源的管理 。 2. 用于稳压电源的管理。
### 接口说明<a name="section8"></a> ### 接口说明
**表1** REGULATOR设备API功能介绍 **表1** Regulator设备API功能介绍
| 接口名 | 描述 | | 接口名 | 描述 |
| --------------------- | ------------------------- | | --------------------- | ------------------------- |
| RegulatorOpen | 获取REGULATOR设备驱动句柄 | | RegulatorOpen | 获取Regulator设备驱动句柄 |
| RegulatorClose | 销毁REGULATOR设备驱动句柄 | | RegulatorClose | 销毁Regulator设备驱动句柄 |
| RegulatorEnable | 使能REGULATOR | | RegulatorEnable | 使能Regulator |
| RegulatorDisable | 禁用REGULATOR | | RegulatorDisable | 禁用Regulator |
| RegulatorForceDisable | 强制禁用REGULATOR | | RegulatorForceDisable | 强制禁用Regulator |
| RegulatorSetVoltage | 设置REGULATOR输出电压 | | RegulatorSetVoltage | 设置Regulator输出电压 |
| RegulatorGetVoltage | 获取REGULATOR输出电压 | | RegulatorGetVoltage | 获取Regulator输出电压 |
| RegulatorSetCurrent | 设置REGULATOR输出电流 | | RegulatorSetCurrent | 设置Regulator输出电流 |
| RegulatorGetCurrent | 获取REGULATOR输出电流 | | RegulatorGetCurrent | 获取Regulator输出电流 |
| RegulatorGetStatus | 获取REGULATOR状态 | | RegulatorGetStatus | 获取Regulator状态 |
### 开发步骤<a name="section9"></a> ### 开发步骤
在操作系统启动过程中，驱动管理模块根据配置文件加载REGULATOR驱动，REGULATOR驱动会检测REGULATOR器件并初始化驱动。 在操作系统启动过程中，驱动管理模块根据配置文件加载Regulator驱动，Regulator驱动会检测Regulator器件并初始化驱动。
使用REGULATOR设备的一般流程如[图1](#fig1_REGULATOR_des)所示。 使用Regulator设备的一般流程如图2所示。
**图 1** REGULATOR设备使用流程图<a name="fig1_REGULATOR_des"></a> **图 2** Regulator设备使用流程图
![](figures/REGULATOR设备使用流程图.png) ![](figures/REGULATOR设备使用流程图.png)
#### 获取REGULATOR设备句柄 #### 获取Regulator设备句柄
在操作REGULATOR设备时，首先要调用RegulatorOpen获取REGULATOR设备句柄，该函数会返回指定设备名称的REGULATOR设备句柄。 在操作Regulator设备时，首先要调用RegulatorOpen获取Regulator设备句柄，该函数会返回指定设备名称的Regulator设备句柄。
``` ```
DevHandle RegulatorOpen(const char *name); DevHandle RegulatorOpen(const char *name);
...@@ -105,32 +95,30 @@ DevHandle RegulatorOpen(const char *name); ...@@ -105,32 +95,30 @@ DevHandle RegulatorOpen(const char *name);
**表2** RegulatorOpen参数和返回值描述 **表2** RegulatorOpen参数和返回值描述
<a name="table2"></a>
| 参数 | 参数描述 | | 参数 | 参数描述 |
| ---------- | ----------------------------- | | ---------- | ----------------------------- |
| name | REGULATOR设备名称 | | name | Regulator设备名称 |
| **返回值** | **返回值描述** | | **返回值** | **返回值描述** |
| handle | 获取成功返回REGULATOR设备句柄 | | handle | 获取成功返回Regulator设备句柄 |
| NULL | 获取失败 | | NULL | 获取失败 |
``` ```
/* REGULATOR设备名称 */ /* Regulator设备名称 */
const char *name = "regulator_virtual_1"; const char *name = "regulator_virtual_1";
DevHandle handle = NULL; DevHandle handle = NULL;
/* 获取REGULATOR设备句柄 */ /* 获取Regulator设备句柄 */
handle = RegulatorOpen(name); handle = RegulatorOpen(name);
if (handle == NULL) { if (handle == NULL) {
/* 错误处理 */ /* 错误处理 */
} }
``` ```
#### 销毁REGULATOR设备句柄 #### 销毁Regulator设备句柄
关闭REGULATOR设备，系统释放对应的资源。 关闭Regulator设备，系统释放对应的资源。
``` ```
void RegulatorClose(DevHandle handle); void RegulatorClose(DevHandle handle);
...@@ -138,31 +126,28 @@ void RegulatorClose(DevHandle handle); ...@@ -138,31 +126,28 @@ void RegulatorClose(DevHandle handle);
**表3** RegulatorClose参数描述 **表3** RegulatorClose参数描述
<a name="table3"></a>
| 参数 | 参数描述 | | 参数 | 参数描述 |
| ------ | ----------------- | | ------ | ----------------- |
| handle | REGULATOR设备句柄 | | handle | Regulator设备句柄 |
``` ```
/* 销毁REGULATOR设备句柄 */ /* 销毁Regulator设备句柄 */
RegulatorClose(handle); RegulatorClose(handle);
``` ```
#### 使能<a name="section3.4_REGULATOR_des"></a> #### 使能
启用REGULATOR设备。 启用Regulator设备。
``` ```
int32_t RegulatorEnable(DevHandle handle); int32_t RegulatorEnable(DevHandle handle);
``` ```
**表4** RegulatorEnable参数描述
<a name="table4"></a> **表4** RegulatorEnable参数描述
| 参数 | 参数描述 | | 参数 | 参数描述 |
| ---------- | ----------------- | | ---------- | ----------------- |
| handle | REGULATOR设备句柄 | | handle | Regulator设备句柄 |
| **返回值** | **返回值描述** | | **返回值** | **返回值描述** |
| 0 | 使能成功 | | 0 | 使能成功 |
| 负数 | 使能失败 | | 负数 | 使能失败 |
...@@ -172,16 +157,16 @@ int32_t RegulatorEnable(DevHandle handle); ...@@ -172,16 +157,16 @@ int32_t RegulatorEnable(DevHandle handle);
``` ```
int32_t ret; int32_t ret;
/*启用REGULATOR设备*/ /*启用Regulator设备*/
ret = RegulatorEnable(handle); ret = RegulatorEnable(handle);
if (ret != 0) { if (ret != 0) {
/*错误处理*/ /*错误处理*/
} }
``` ```
#### 禁用<a name="section3.5_REGULATOR_des"></a> #### 禁用
禁用REGULATOR设备。 禁用Regulator设备。如果Regulator设备状态为常开，或存在Regulator设备子节点未禁用，则禁用失败。
``` ```
int32_t RegulatorDisable(DevHandle handle); int32_t RegulatorDisable(DevHandle handle);
...@@ -191,7 +176,7 @@ int32_t RegulatorDisable(DevHandle handle); ...@@ -191,7 +176,7 @@ int32_t RegulatorDisable(DevHandle handle);
| 参数 | 参数描述 | | 参数 | 参数描述 |
| ---------- | ----------------- | | ---------- | ----------------- |
| handle | REGULATOR设备句柄 | | handle | Regulator设备句柄 |
| **返回值** | **返回值描述** | | **返回值** | **返回值描述** |
| 0 | 禁用成功 | | 0 | 禁用成功 |
| 负数 | 禁用失败 | | 负数 | 禁用失败 |
...@@ -199,28 +184,27 @@ int32_t RegulatorDisable(DevHandle handle); ...@@ -199,28 +184,27 @@ int32_t RegulatorDisable(DevHandle handle);
``` ```
int32_t ret; int32_t ret;
/*禁用REGULATOR设备，如果REGULATOR设备状态为常开，或存在REGULATOR设备子节点未禁用，则禁用失败*/ /*禁用Regulator设备*/
ret = RegulatorDisable(handle); ret = RegulatorDisable(handle);
if (ret != 0) { if (ret != 0) {
/*错误处理*/ /*错误处理*/
} }
``` ```
#### 强制禁用<a name="section3.6_REGULATOR_des"></a> #### 强制禁用
强制禁用REGULATOR设备。 强制禁用Regulator设备。无论Regulator设备的状态是常开还是子节点已使能，Regulator设备都会被禁用。
``` ```
int32_t RegulatorForceDisable(DevHandle handle); int32_t RegulatorForceDisable(DevHandle handle);
``` ```
**表5** RegulatorDisable参数描述 **表6** RegulatorForceDisable参数描述
<a name="table5_REGULATOR_des"></a>
| 参数 | 参数描述 | | 参数 | 参数描述 |
| ---------- | ----------------- | | ---------- | ----------------- |
| handle | REGULATOR设备句柄 | | handle | Regulator设备句柄 |
| **返回值** | **返回值描述** | | **返回值** | **返回值描述** |
| 0 | 禁用成功 | | 0 | 禁用成功 |
| 负数 | 禁用失败 | | 负数 | 禁用失败 |
...@@ -228,16 +212,16 @@ int32_t RegulatorForceDisable(DevHandle handle); ...@@ -228,16 +212,16 @@ int32_t RegulatorForceDisable(DevHandle handle);
``` ```
int32_t ret; int32_t ret;
/*强制禁用REGULATOR设备，无论REGULATOR设备的状态是常开还是子节点已使能，REGULATOR设备都会被禁用*/ /*强制禁用Regulator设备*/
ret = RegulatorForceDisable(handle); ret = RegulatorForceDisable(handle);
if (ret != 0) { if (ret != 0) {
/*错误处理*/ /*错误处理*/
} }
``` ```
#### 设置REGULATOR输出电压范围<a name="section3.7_REGULATOR_des"></a> #### 设置Regulator输出电压范围
设置REGULATOR电压输出电压范围。 设置Regulator电压输出电压范围。
``` ```
int32_t RegulatorSetVoltage(DevHandle handle, uint32_t minUv, uint32_t maxUv); int32_t RegulatorSetVoltage(DevHandle handle, uint32_t minUv, uint32_t maxUv);
...@@ -245,11 +229,9 @@ int32_t RegulatorSetVoltage(DevHandle handle, uint32_t minUv, uint32_t maxUv); ...@@ -245,11 +229,9 @@ int32_t RegulatorSetVoltage(DevHandle handle, uint32_t minUv, uint32_t maxUv);
**表7** RegulatorSetVoltage参数描述 **表7** RegulatorSetVoltage参数描述
<a name="table7_REGULATOR_des"></a>
| 参数 | 参数描述 | | 参数 | 参数描述 |
| ---------- | ----------------- | | ---------- | ----------------- |
| handle | REGULATOR设备句柄 | | handle | Regulator设备句柄 |
| minUv | 最小电压 | | minUv | 最小电压 |
| maxUv | 最大电压 | | maxUv | 最大电压 |
| **返回值** | **返回值描述** | | **返回值** | **返回值描述** |
...@@ -258,19 +240,19 @@ int32_t RegulatorSetVoltage(DevHandle handle, uint32_t minUv, uint32_t maxUv); ...@@ -258,19 +240,19 @@ int32_t RegulatorSetVoltage(DevHandle handle, uint32_t minUv, uint32_t maxUv);
``` ```
int32_t ret; int32_t ret;
int32_t minUv = 0; //最小电压为0Uv int32_t minUv = 0; //最小电压为0µV
int32_t maxUv = 20000; //最大电压为20000Uv int32_t maxUv = 20000; //最大电压为20000µV
/*设置REGULATOR电压输出电压范围*/ /*设置Regulator电压输出电压范围*/
ret = RegulatorSetVoltage(handle, minUv, maxUv); ret = RegulatorSetVoltage(handle, minUv, maxUv);
if (ret != 0) { if (ret != 0) {
/*错误处理*/ /*错误处理*/
} }
``` ```
#### 获取REGULATOR电压<a name="section3.8_REGULATOR_des"></a> #### 获取Regulator电压
获取REGULATOR电压。 获取Regulator电压。
``` ```
int32_t RegulatorGetVoltage(DevHandle handle, uint32_t *voltage); int32_t RegulatorGetVoltage(DevHandle handle, uint32_t *voltage);
...@@ -278,11 +260,10 @@ int32_t RegulatorGetVoltage(DevHandle handle, uint32_t *voltage); ...@@ -278,11 +260,10 @@ int32_t RegulatorGetVoltage(DevHandle handle, uint32_t *voltage);
**表8** RegulatorGetVoltage参数描述 **表8** RegulatorGetVoltage参数描述
<a name="table8_REGULATOR_des"></a>
| 参数 | 参数描述 | | 参数 | 参数描述 |
| ---------- | ----------------- | | ---------- | ----------------- |
| handle | REGULATOR设备句柄 | | handle | Regulator设备句柄 |
| *voltage | 参数指针 | | *voltage | 参数指针 |
| **返回值** | **返回值描述** | | **返回值** | **返回值描述** |
| 0 | 获取成功 | | 0 | 获取成功 |
...@@ -292,16 +273,16 @@ int32_t RegulatorGetVoltage(DevHandle handle, uint32_t *voltage); ...@@ -292,16 +273,16 @@ int32_t RegulatorGetVoltage(DevHandle handle, uint32_t *voltage);
int32_t ret; int32_t ret;
uint32_t voltage; uint32_t voltage;
/*获取REGULATOR电压*/ /*获取Regulator电压*/
ret = RegulatorGetVoltage(handle, &voltage); ret = RegulatorGetVoltage(handle, &voltage);
if (ret != 0) { if (ret != 0) {
/*错误处理*/ /*错误处理*/
} }
``` ```
#### 设置REGULATOR输出电流范围<a name="section3.9_REGULATOR_des"></a> #### 设置Regulator输出电流范围
设置REGULATOR输出电流范围。 设置Regulator输出电流范围。
``` ```
int32_t RegulatorSetCurrent(DevHandle handle, uint32_t minUa, uint32_t maxUa); int32_t RegulatorSetCurrent(DevHandle handle, uint32_t minUa, uint32_t maxUa);
...@@ -309,11 +290,9 @@ int32_t RegulatorSetCurrent(DevHandle handle, uint32_t minUa, uint32_t maxUa); ...@@ -309,11 +290,9 @@ int32_t RegulatorSetCurrent(DevHandle handle, uint32_t minUa, uint32_t maxUa);
**表9** RegulatorSetCurrent参数描述 **表9** RegulatorSetCurrent参数描述
<a name="table9_REGULATOR_des"></a>
| 参数 | 参数描述 | | 参数 | 参数描述 |
| ---------- | ----------------- | | ---------- | ----------------- |
| handle | REGULATOR设备句柄 | | handle | Regulator设备句柄 |
| minUa | 最小电流 | | minUa | 最小电流 |
| maxUa | 最大电流 | | maxUa | 最大电流 |
| **返回值** | **返回值描述** | | **返回值** | **返回值描述** |
...@@ -322,19 +301,19 @@ int32_t RegulatorSetCurrent(DevHandle handle, uint32_t minUa, uint32_t maxUa); ...@@ -322,19 +301,19 @@ int32_t RegulatorSetCurrent(DevHandle handle, uint32_t minUa, uint32_t maxUa);
``` ```
int32_t ret; int32_t ret;
int32_t minUa = 0; //最小电流为0Ua int32_t minUa = 0; //最小电流为0μA
int32_t maxUa = 200; //最大电流为200Ua int32_t maxUa = 200; //最大电流为200μA
/*设置REGULATOR输出电流范围*/ /*设置Regulator输出电流范围*/
ret = RegulatorSetCurrent(handle, minUa, maxUa); ret = RegulatorSetCurrent(handle, minUa, maxUa);
if (ret != 0) { if (ret != 0) {
/*错误处理*/ /*错误处理*/
} }
``` ```
#### 获取REGULATOR电流<a name="section3.10_REGULATOR_des"></a> #### 获取Regulator电流
获取REGULATOR电流。 获取Regulator电流。
``` ```
int32_t RegulatorGetCurrent(DevHandle handle, uint32_t *regCurrent); int32_t RegulatorGetCurrent(DevHandle handle, uint32_t *regCurrent);
...@@ -342,11 +321,9 @@ int32_t RegulatorGetCurrent(DevHandle handle, uint32_t *regCurrent); ...@@ -342,11 +321,9 @@ int32_t RegulatorGetCurrent(DevHandle handle, uint32_t *regCurrent);
**表10** RegulatorGetCurrent参数描述 **表10** RegulatorGetCurrent参数描述
<a name="table10_REGULATOR_des"></a>
| 参数 | 参数描述 | | 参数 | 参数描述 |
| ----------- | ----------------- | | ----------- | ----------------- |
| handle | REGULATOR设备句柄 | | handle | Regulator设备句柄 |
| *regCurrent | 参数指针 | | *regCurrent | 参数指针 |
| **返回值** | **返回值描述** | | **返回值** | **返回值描述** |
| 0 | 获取成功 | | 0 | 获取成功 |
...@@ -356,28 +333,26 @@ int32_t RegulatorGetCurrent(DevHandle handle, uint32_t *regCurrent); ...@@ -356,28 +333,26 @@ int32_t RegulatorGetCurrent(DevHandle handle, uint32_t *regCurrent);
int32_t ret; int32_t ret;
uint32_t regCurrent; uint32_t regCurrent;
/*获取REGULATOR电流*/ /*获取Regulator电流*/
ret = RegulatorGetCurrent(handle, &regCurrent); ret = RegulatorGetCurrent(handle, &regCurrent);
if (ret != 0) { if (ret != 0) {
/*错误处理*/ /*错误处理*/
} }
``` ```
#### 获取REGULATOR状态<a name="section3.11_REGULATOR_des"></a> #### 获取Regulator状态
获取REGULATOR状态。 获取Regulator状态。
``` ```
int32_t RegulatorGetStatus(DevHandle handle, uint32_t *status); int32_t RegulatorGetStatus(DevHandle handle, uint32_t *status);
``` ```
**表10** RegulatorGetCurrent参数描述 **表11** RegulatorGetStatus参数描述
<a name="table10_REGULATOR_des"></a>
| 参数 | 参数描述 | | 参数 | 参数描述 |
| ---------- | ----------------- | | ---------- | ----------------- |
| handle | REGULATOR设备句柄 | | handle | Regulator设备句柄 |
| *status | 参数指针 | | *status | 参数指针 |
| **返回值** | **返回值描述** | | **返回值** | **返回值描述** |
| 0 | 获取成功 | | 0 | 获取成功 |
...@@ -387,7 +362,7 @@ int32_t RegulatorGetStatus(DevHandle handle, uint32_t *status); ...@@ -387,7 +362,7 @@ int32_t RegulatorGetStatus(DevHandle handle, uint32_t *status);
int32_t ret; int32_t ret;
uint32_t status; uint32_t status;
/*获取REGULATOR状态*/ /*获取Regulator状态*/
ret = RegulatorGetStatus(handle, &status); ret = RegulatorGetStatus(handle, &status);
if (ret != 0) { if (ret != 0) {
/*错误处理*/ /*错误处理*/
...@@ -396,37 +371,37 @@ if (ret != 0) { ...@@ -396,37 +371,37 @@ if (ret != 0) {
## 使用实例<a name="section10"></a> ## 使用实例
REGULATOR设备完整的使用示例如下所示，首先获取REGULATOR设备句柄，然后使能，设置电压，获取电压、状态，禁用，最后销毁REGULATOR设备句柄。 Regulator设备完整的使用示例如下所示，首先获取Regulator设备句柄，然后使能，设置电压，获取电压、状态，禁用，最后销毁Regulator设备句柄。
``` ```
void RegulatorTestSample(void) void RegulatorTestSample(void)
{ {
int32_t ret; int32_t ret;
/* REGULATOR设备名称 */ /* Regulator设备名称 */
const char *name = "regulator_virtual_1"; const char *name = "regulator_virtual_1";
DevHandle handle = NULL; DevHandle handle = NULL;
/* 获取REGULATOR设备句柄 */ /* 获取Regulator设备句柄 */
handle = RegulatorOpen(name); handle = RegulatorOpen(name);
if (handle == NULL) { if (handle == NULL) {
HDF_LOGE("RegulatorOpen: failed!\n"); HDF_LOGE("RegulatorOpen: failed!\n");
return; return;
} }
/*启用REGULATOR设备*/ /*启用Regulator设备*/
ret = RegulatorEnable(handle); ret = RegulatorEnable(handle);
if (ret != 0) { if (ret != 0) {
HDF_LOGE("RegulatorEnable: failed, ret %d\n", ret); HDF_LOGE("RegulatorEnable: failed, ret %d\n", ret);
goto _ERR; goto _ERR;
} }
int32_t minUv = 0; //最小电压为0Uv int32_t minUv = 0; //最小电压为0µV
int32_t maxUv = 20000; //最大电压为20000Uv int32_t maxUv = 20000; //最大电压为20000µV
/*设置REGULATOR输出电压范围*/ /*设置Regulator输出电压范围*/
ret = RegulatorSetVoltage(handle, minUv, maxUv); ret = RegulatorSetVoltage(handle, minUv, maxUv);
if (ret != 0) { if (ret != 0) {
HDF_LOGE("RegulatorSetVoltage: failed, ret %d\n", ret); HDF_LOGE("RegulatorSetVoltage: failed, ret %d\n", ret);
...@@ -435,7 +410,7 @@ void RegulatorTestSample(void) ...@@ -435,7 +410,7 @@ void RegulatorTestSample(void)
uint32_t voltage; uint32_t voltage;
/*获取REGULATOR电压*/ /*获取Regulator电压*/
ret = RegulatorGetVoltage(handle, &voltage); ret = RegulatorGetVoltage(handle, &voltage);
if (ret != 0) { if (ret != 0) {
HDF_LOGE("RegulatorGetVoltage: failed, ret %d\n", ret); HDF_LOGE("RegulatorGetVoltage: failed, ret %d\n", ret);
...@@ -444,14 +419,14 @@ void RegulatorTestSample(void) ...@@ -444,14 +419,14 @@ void RegulatorTestSample(void)
uint32_t status; uint32_t status;
/*获取REGULATOR状态*/ /*获取Regulator状态*/
ret = RegulatorGetStatus(handle, &status); ret = RegulatorGetStatus(handle, &status);
if (ret != 0) { if (ret != 0) {
HDF_LOGE("RegulatorGetStatus: failed, ret %d\n", ret); HDF_LOGE("RegulatorGetStatus: failed, ret %d\n", ret);
goto _ERR; goto _ERR;
} }
/*禁用REGULATOR设备*/ /*禁用Regulator设备*/
ret = RegulatorDisable(handle); ret = RegulatorDisable(handle);
if (ret != 0) { if (ret != 0) {
HDF_LOGE("RegulatorDisable: failed, ret %d\n", ret); HDF_LOGE("RegulatorDisable: failed, ret %d\n", ret);
...@@ -459,7 +434,7 @@ void RegulatorTestSample(void) ...@@ -459,7 +434,7 @@ void RegulatorTestSample(void)
} }
_ERR: _ERR:
/* 销毁REGULATOR设备句柄 */ /* 销毁Regulator设备句柄 */
RegulatorClose(handle); RegulatorClose(handle);
} }
``` ```
zh-cn/device-dev/driver/driver-platform-regulator-develop.md
浏览文件 @ f4009826
# REGULATOR # Regulator
- [概述](#1)
- [功能简介](#2)
- [基本概念](#3)
- [运作机制](#4)
- [约束与限制](#5)
- [开发指导](#6)
- [场景介绍](#7)
- [接口说明](#8)
- [开发步骤](#9)
## 概述<a name="1"></a> ## 概述
### 功能简介<a name="2"></a> ### 功能简介
REGULATOR模块用于控制系统中某些设备的电压/电流供应。 Regulator模块用于控制系统中某些设备的电压/电流供应。
### 基本概念<a name="3"></a> ### 基本概念
REGULATOR模块用于控制系统中某些设备的电压/电流供应。在嵌入式系统（尤其是手机）中，控制耗电量很重要，直接影响到电池的续航时间。所以，如果系统中某一个模块暂时不需要使用，就可以通过REGULATOR关闭其电源供应；或者降低提供给该模块的电压、电流大小。 Regulator模块用于控制系统中某些设备的电压/电流供应。在嵌入式系统（尤其是手机）中，控制耗电量很重要，直接影响到电池的续航时间。所以，如果系统中某一个模块暂时不需要使用，就可以通过Regulator关闭其电源供应；或者降低提供给该模块的电压、电流大小。
### 运作机制<a name="4"></a> ### 运作机制
在HDF框架中，REGULATOR模块接口适配模式采用统一服务模式，这需要一个设备服务来作为REGULATOR模块的管理器，统一处理外部访问，这会在配置文件中有所体现。统一服务模式适合于同类型设备对象较多的情况，如REGULATOR可能同时具备十几个控制器，采用独立服务模式需要配置更多的设备节点，且服务会占据内存资源。 在HDF框架中，Regulator模块接口适配模式采用统一服务模式，这需要一个设备服务来作为Regulator模块的管理器，统一处理外部访问，这会在配置文件中有所体现。统一服务模式适合于同类型设备对象较多的情况，如Regulator可能同时具备十几个控制器，采用独立服务模式需要配置更多的设备节点，且服务会占据内存资源。
REGULATOR模块各分层的作用为：接口层提供打开设备，写入数据，关闭设备接口的能力。核心层主要提供绑定设备、初始化设备以及释放设备的能力。适配层实现其他具体的功能。 Regulator模块各分层的作用为：接口层提供打开设备，写入数据，关闭设备接口的能力。核心层主要提供绑定设备、初始化设备以及释放设备的能力。适配层实现其他具体的功能。
![](../public_sys-resources/icon-note.gif) 说明：核心层可以调用接口层的函数，也可以通过钩子函数调用适配层函数，从而使得适配层间接的可以调用接口层函数，但是不可逆转接口层调用适配层函数。 ![](../public_sys-resources/icon-note.gif) 说明：核心层可以调用接口层的函数，也可以通过钩子函数调用适配层函数，从而使得适配层间接的可以调用接口层函数，但是不可逆转接口层调用适配层函数。
图 1 统一服务模式结构图 **图 1** 统一服务模式结构图
![image1](figures/统一服务模式结构图.png) ![image1](figures/统一服务模式结构图.png)
### 约束与限制
Regulator模块当前仅支持轻量和小型系统内核（LiteOS）。
### 约束与限制<a name="5"></a> ## 开发指导
REGULATOR模块当前仅支持轻量和小型系统内核（LiteOS） 。 ### 场景介绍
## 开发指导<a name="6"></a> Regulator模块用于控制系统中某些设备的电压/电流供应。
### 场景介绍<a name="7"></a> ### 接口说明
REGULATOR模块用于控制系统中某些设备的电压/电流供应。 通过以下RegulatorMethod中的函数调用Regulator驱动对应的函数。
### 接口说明<a name="8"></a>
通过以下RegulatorMethod中的函数调用REGULATOR驱动对应的函数。
RegulatorMethod定义： RegulatorMethod定义：
...@@ -70,25 +59,24 @@ struct RegulatorMethod { ...@@ -70,25 +59,24 @@ struct RegulatorMethod {
**表 1** RegulatorMethod 结构体成员的回调函数功能说明 **表 1** RegulatorMethod 结构体成员的回调函数功能说明
<a name="table27410339187"></a>
| 成员函数 | 入参 | 返回值 | 功能 | | 成员函数 | 入参 | 返回值 | 功能 |
| ------------ | ------------------------------------------------------------ | ------------------ | ---------------- | | ------------ | ------------------------------------------------------------ | ------------------ | ---------------- |
| open | **node**：结构体指针，核心层regulator节点； | HDF_STATUS相关状态 | 打开设备 | | open | **node**：结构体指针，核心层Regulator节点； | HDF_STATUS相关状态 | 打开设备 |
| close | **node**：结构体指针，核心层regulator节点； | HDF_STATUS相关状态 | 关闭设备 | | close | **node**：结构体指针，核心层Regulator节点； | HDF_STATUS相关状态 | 关闭设备 |
| release | **node**：结构体指针，核心层regulator节点； | HDF_STATUS相关状态 | 释放设备句柄 | | release | **node**：结构体指针，核心层Regulator节点； | HDF_STATUS相关状态 | 释放设备句柄 |
| enable | **node**：结构体指针，核心层regulator节点； | HDF_STATUS相关状态 | 使能 | | enable | **node**：结构体指针，核心层Regulator节点； | HDF_STATUS相关状态 | 使能 |
| disable | **node**：结构体指针，核心层regulator节点； | HDF_STATUS相关状态 | 禁用 | | disable | **node**：结构体指针，核心层Regulator节点； | HDF_STATUS相关状态 | 禁用 |
| forceDisable | **node**：结构体指针，核心层regulator节点； | HDF_STATUS相关状态 | 强制禁用 | | forceDisable | **node**：结构体指针，核心层Regulator节点； | HDF_STATUS相关状态 | 强制禁用 |
| setVoltage | **node**：结构体指针，核心层regulator节点； **minUv**：uint32_t变量，最小电压； **maxUv**：uint32_t变量，最大电压； | HDF_STATUS相关状态 | 设置输出电压范围 | | setVoltage | **node**：结构体指针，核心层Regulator节点；<br>**minUv**：uint32_t变量，最小电压；<br>**maxUv**：uint32_t变量，最大电压； | HDF_STATUS相关状态 | 设置输出电压范围 |
| getVoltage | **node**：结构体指针，核心层regulator节点； **voltage**：uint32_t指针，传出电压值； | HDF_STATUS相关状态 | 获取电压 | | getVoltage | **node**：结构体指针，核心层Regulator节点；<br>**voltage**：uint32_t指针，传出电压值； | HDF_STATUS相关状态 | 获取电压 |
| setCurrent | **node**：结构体指针，核心层regulator节点； **minUa**：uint32_t变量，最小电流； **maxUa**：uint32_t变量，最大电流； | HDF_STATUS相关状态 | 设置输出电流范围 | | setCurrent | **node**：结构体指针，核心层Regulator节点；<br>**minUa**：uint32_t变量，最小电流；<br>**maxUa**：uint32_t变量，最大电流； | HDF_STATUS相关状态 | 设置输出电流范围 |
| getCurrent | **node**：结构体指针，核心层regulator节点； **regCurrent**：uint32_t指针，传出电流值； | HDF_STATUS相关状态 | 获取电流 | | getCurrent | **node**：结构体指针，核心层Regulator节点；<br>**regCurrent**：uint32_t指针，传出电流值； | HDF_STATUS相关状态 | 获取电流 |
| getStatus | **node**：结构体指针，核心层regulator节点； **status**：uint32_t指针，传出状态值； | HDF_STATUS相关状态 | 获取设备状态 | | getStatus | **node**：结构体指针，核心层Regulator节点；<br>**status**：uint32_t指针，传出状态值； | HDF_STATUS相关状态 | 获取设备状态 |
### 开发步骤<a name="9"></a> ### 开发步骤
REGULATOR模块适配包含以下四个步骤： Regulator模块适配包含以下四个步骤：
- 实例化驱动入口。 - 实例化驱动入口。
- 配置属性文件。 - 配置属性文件。
...@@ -118,18 +106,18 @@ REGULATOR模块适配包含以下四个步骤： ...@@ -118,18 +106,18 @@ REGULATOR模块适配包含以下四个步骤：
deviceNode信息与驱动入口注册相关，器件属性值与核心层RegulatorNode成员的默认值或限制范围有密切关系。 deviceNode信息与驱动入口注册相关，器件属性值与核心层RegulatorNode成员的默认值或限制范围有密切关系。
由于采用了统一服务模式，device_info.hcs文件中第一个设备节点必须为REGULATOR管理器，其各项参数必须如下设置： 由于采用了统一服务模式，device_info.hcs文件中第一个设备节点必须为Regulator管理器，其各项参数必须如下设置：
| 成员名 | 值 | | 成员名 | 值 |
| --------------- | ------------------------------------------------------------ | | --------------- | ------------------------------------------------------------ |
| policy | 具体配置为0，不发布服务 | | policy | 具体配置为0，不发布服务 |
| priority | 驱动启动优先级（0-200），值越大优先级越低,，优先级相同则不保证device的加载顺序。 | | priority | 驱动启动优先级（0-200），值越大优先级越低,，优先级相同则不保证device的加载顺序。 |
| permission | 驱动权限 | | permission | 驱动权限 |
| moduleName | 固定为 HDF_PLATFORM_REGULATOR_MANAGER | | moduleName | 固定为HDF_PLATFORM_REGULATOR_MANAGER |
| serviceName | 固定为HDF_PLATFORM_REGULATOR_MANAGER | | serviceName | 固定为HDF_PLATFORM_REGULATOR_MANAGER |
| deviceMatchAttr | 没有使用，可忽略 | | deviceMatchAttr | 没有使用，可忽略 |
从第二个节点开始配置具体REGULATOR控制器信息，此节点并不表示某一路REGULATOR控制器，而是代表一个资源性质设备，用于描述一类REGULATOR控制器的信息。本例只有一个REGULATOR设备，如有多个设备，则需要在device_info文件增加deviceNode信息，以及在regulator\_config文件中增加对应的器件属性。 从第二个节点开始配置具体Regulator控制器信息，此节点并不表示某一路Regulator控制器，而是代表一个资源性质设备，用于描述一类Regulator控制器的信息。本例只有一个Regulator设备，如有多个设备，则需要在device_info文件增加deviceNode信息，以及在regulator\_config文件中增加对应的器件属性。
- device_info.hcs 配置参考。 - device_info.hcs 配置参考。
...@@ -140,9 +128,9 @@ REGULATOR模块适配包含以下四个步骤： ...@@ -140,9 +128,9 @@ REGULATOR模块适配包含以下四个步骤：
hostName = "platform_host"; hostName = "platform_host";
priority = 50; priority = 50;
device_regulator :: device { device_regulator :: device {
device0 :: deviceNode { //为每一个REGULATOR控制器配置一个HDF设备节点，存在多个时添加，否则不用 device0 :: deviceNode { //为每一个Regulator控制器配置一个HDF设备节点，存在多个时添加，否则不用
policy = 1; // 2:用户态可见,1:内核态可见,0:不需要发布服务 policy = 1; // 2:用户态可见,1:内核态可见,0:不需要发布服务
priority = 50; // 驱动启动优先级 priority = 50; // 驱动启动优先级
permission = 0644; // 驱动创建设备节点权限 permission = 0644; // 驱动创建设备节点权限
/*【必要】用于指定驱动名称，需要与期望的驱动Entry中的moduleName一致；*/ /*【必要】用于指定驱动名称，需要与期望的驱动Entry中的moduleName一致；*/
moduleName = "HDF_PLATFORM_REGULATOR_MANAGER"; moduleName = "HDF_PLATFORM_REGULATOR_MANAGER";
...@@ -165,49 +153,49 @@ REGULATOR模块适配包含以下四个步骤： ...@@ -165,49 +153,49 @@ REGULATOR模块适配包含以下四个步骤：
- regulator\_config.hcs 配置参考。 - regulator\_config.hcs 配置参考。
``` ```
root { root {
platform { platform {
regulator_config { regulator_config {
match_attr = "linux_regulator_adapter"; match_attr = "linux_regulator_adapter";
template regulator_controller { //【必要】模板配置，继承该模板的节点如果使用模板中的默认值，则节点字段可以缺省 template regulator_controller { //【必要】模板配置，继承该模板的节点如果使用模板中的默认值，则节点字段可以缺省
device_num = 1; device_num = 1;
name = ""; name = "";
devName = "regulator_adapter_consumer01"; devName = "regulator_adapter_consumer01";
supplyName = ""; supplyName = "";
mode = 1; mode = 1;
minUv = 0; minUv = 0;
maxUv = 20000; maxUv = 20000;
minUa = 0; minUa = 0;
maxUa = 0; maxUa = 0;
} }
controller_0x130d0000 :: regulator_controller { controller_0x130d0000 :: regulator_controller {
device_num = 1; device_num = 1;
name = "regulator_adapter_1"; name = "regulator_adapter_1";
devName = "regulator_adapter_consumer01"; devName = "regulator_adapter_consumer01";
supplyName = "virtual-regulator-hdf-adapter"; supplyName = "virtual-regulator-hdf-adapter";
mode = 1; mode = 1;
minUv = 1000; minUv = 1000;
maxUv = 50000; maxUv = 50000;
minUa = 0; minUa = 0;
maxUa = 0; maxUa = 0;
} }
/*每个Regulator控制器对应一个controller节点，如存在多个Regulator控制器，请依次添加对应的controller节点。*/ /*每个Regulator控制器对应一个controller节点，如存在多个Regulator控制器，请依次添加对应的controller节点。*/
controller_0x130d0001 :: regulator_controller { controller_0x130d0001 :: regulator_controller {
device_num = 1; device_num = 1;
name = "regulator_adapter_2"; name = "regulator_adapter_2";
devName = "regulator_adapter_consumer01"; devName = "regulator_adapter_consumer01";
supplyName = "virtual2-regulator-hdf-adapter"; supplyName = "virtual2-regulator-hdf-adapter";
mode = 2; mode = 2;
minUv = 0; minUv = 0;
maxUv = 0; maxUv = 0;
minUa = 1000; minUa = 1000;
maxUa = 50000; maxUa = 50000;
} }
} }
} }
} }
``` ```
3. **实例化核心层接口函数：** 3. **实例化核心层接口函数：**
...@@ -256,7 +244,7 @@ REGULATOR模块适配包含以下四个步骤： ...@@ -256,7 +244,7 @@ REGULATOR模块适配包含以下四个步骤：
- 实例化RegulatorNode成员RegulatorMethod，其他成员在Init函数中初始化。 - 实例化RegulatorNode成员RegulatorMethod，其他成员在Init函数中初始化。
```c ```c
// regulator_virtual.c 中的示例：钩子函数的填充 // regulator_virtual.c 中的示例：钩子函数的填充
static struct RegulatorMethod g_method = { static struct RegulatorMethod g_method = {
.enable = VirtualRegulatorEnable, .enable = VirtualRegulatorEnable,
.disable = VirtualRegulatorDisable, .disable = VirtualRegulatorDisable,
...@@ -272,59 +260,60 @@ REGULATOR模块适配包含以下四个步骤： ...@@ -272,59 +260,60 @@ REGULATOR模块适配包含以下四个步骤：
- Init函数参考 - Init函数参考
入参： 入参：
HdfDeviceObject 是整个驱动对外暴露的接口参数，具备 HCS 配置文件的信息。 HdfDeviceObject 是整个驱动对外暴露的接口参数，具备 HCS 配置文件的信息。
返回值： 返回值：
HDF\_STATUS相关状态 （下表为部分展示，如需使用其他状态，可见//drivers/framework/include/utils/hdf\_base.h中HDF\_STATUS 定义）。 HDF\_STATUS相关状态（下表为部分展示，如需使用其他状态，可见//drivers/framework/include/utils/hdf\_base.h中HDF\_STATUS 定义）。
**表 2** HDF\_STATUS相关状态 **表 2** HDF\_STATUS相关状态
| 状态(值) | 问题描述 | | 状态(值) | 问题描述 |
| ---------------------- | -------------- | | ---------------------- | -------------- |
| HDF_ERR_INVALID_OBJECT | 控制器对象非法 | | HDF_ERR_INVALID_OBJECT | 控制器对象非法 |
| HDF_ERR_MALLOC_FAIL | 内存分配失败 | | HDF_ERR_MALLOC_FAIL | 内存分配失败 |
| HDF_ERR_INVALID_PARAM | 参数非法 | | HDF_ERR_INVALID_PARAM | 参数非法 |
| HDF_ERR_IO | I/O 错误 | | HDF_ERR_IO | I/O 错误 |
| HDF_SUCCESS | 初始化成功 | | HDF_SUCCESS | 初始化成功 |
| HDF_FAILURE | 初始化失败 | | HDF_FAILURE | 初始化失败 |
函数说明： 函数说明：
初始化自定义结构体和RegulatorNode成员，并通过调用核心层RegulatorNodeAdd函数挂载Regulator控制器。 初始化自定义结构体和RegulatorNode成员，并通过调用核心层RegulatorNodeAdd函数挂载Regulator控制器。
```c
static int32_t VirtualRegulatorInit(struct HdfDeviceObject *device) ```c
{ static int32_t VirtualRegulatorInit(struct HdfDeviceObject *device)
int32_t ret; {
const struct DeviceResourceNode *childNode = NULL; int32_t ret;
... const struct DeviceResourceNode *childNode = NULL;
DEV_RES_NODE_FOR_EACH_CHILD_NODE(device->property, childNode) { ...
ret = VirtualRegulatorParseAndInit(device, childNode);//【必要】实现见下 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) static int32_t VirtualRegulatorParseAndInit(struct HdfDeviceObject *device, const struct DeviceResourceNode *node)
{ {
int32_t ret; int32_t ret;
struct RegulatorNode *regNode = NULL; struct RegulatorNode *regNode = NULL;
(void)device; (void)device;
regNode = (struct RegulatorNode *)OsalMemCalloc(sizeof(*regNode));//加载HCS文件 regNode = (struct RegulatorNode *)OsalMemCalloc(sizeof(*regNode));//加载HCS文件
... ...
ret = VirtualRegulatorReadHcs(regNode, node);//读取HCS文件信息 ret = VirtualRegulatorReadHcs(regNode, node);//读取HCS文件信息
... ...
regNode->priv = (void *)node; //实例化节点 regNode->priv = (void *)node; //实例化节点
regNode->ops = &g_method; //实例化ops regNode->ops = &g_method; //实例化ops
ret = RegulatorNodeAdd(regNode); //挂载节点 ret = RegulatorNodeAdd(regNode); //挂载节点
... ...
} }
``` ```
- Release 函数参考 - Release 函数参考
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或