• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Regulator
2
3
4## 概述
5
6### 功能简介
7
8Regulator模块用于控制系统中某些设备的电压/电流供应。在嵌入式系统（尤其是手机）中，控制耗电量很重要，直接影响到电池的续航时间。所以，如果系统中某一个模块暂时不需要使用，就可以通过Regulator关闭其电源供应；或者降低提供给该模块的电压、电流大小。
9Regulator接口定义了操作Regulator设备的通用方法集合，包括：
10- Regulator设备句柄获取和销毁。
11- Regulator设备电压、电流的设置。
12- Regulator设备使能和关闭。
13- Regulator设备电压、电流和状态的获取。
14
15
16### 基本概念
17
18-  校准器
19
20   当输入电压和输出负载发生变化时可以通过软件调整，使其能够提供稳定的输出电压。
21
22- Consumer
23
24   由Regulator供电的设备统称为Consumer， 其可分为静态和动态两类：
25
26   * 静态：不需要改变电压电流，只需要开关电源，通常在bootloader、firmware、kernel board阶段被设置。
27   * 动态：根据操作需求改变电压电流。
28
29- PMIC（Power Management IC）
30
31   电源管理芯片，内含多个电源甚至其他子系统。
32
33### 运作机制
34
35在HDF框架中，Regulator模块接口适配模式采用统一服务模式（如图1），这需要一个设备服务来作为Regulator模块的管理器，统一处理外部访问，这会在配置文件中有所体现。统一服务模式适合于同类型设备对象较多的情况，如Regulator可能同时具备十几个控制器，采用独立服务模式需要配置更多的设备节点，且服务会占据内存资源。相反，采用统一服务模式可以使用一个设备服务作为管理器，统一处理所有同类型对象的外部访问，实现便捷管理和节约资源的目的。
36
37Regulator模块各分层的作用为：
38
39- 接口层：提供打开设备，操作Regulator，关闭设备的能力。
40- 核心层：主要负责服务绑定、初始化以及释放管理器，并提供添加、删除以及获取Regulator设备的能力。
41- 适配层：由驱动适配者实现与硬件相关的具体功能，如设备的初始化等。
42
43**图 1** Regulator统一服务模式结构图<a name="fig1"></a>
44
45![image1](figures/统一服务模式结构图.png)
46
47### 约束与限制
48
49Regulator模块API当前仅支持内核态调用。
50
51## 使用指导
52
53### 场景介绍
54
55Regulator主要用于：
56
571. 用于控制系统中某些设备的电压/电流供应。
582. 用于稳压电源的管理。
59
60### 接口说明
61
62Regulator模块提供的主要接口如表1所示，具体API详见//drivers/hdf_core/framework/include/platform/regulator_if.h。
63
64**表1**  Regulator设备API接口说明
65
66| 接口名 | 接口描述 |
67| --------------------- | ------------------------- |
68| DevHandle RegulatorOpen(const char \*name) | 获取Regulator设备驱动句柄 |
69| void RegulatorClose(DevHandle handle) | 销毁Regulator设备驱动句柄 |
70| int32_t RegulatorEnable(DevHandle handle) | 使能Regulator |
71| int32_t RegulatorDisable(DevHandle handle) | 禁用Regulator |
72| int32_t RegulatorForceDisable(DevHandle handle) | 强制禁用Regulator |
73| int32_t RegulatorSetVoltage(DevHandle handle, uint32_t minUv, uint32_t maxUv) | 设置Regulator输出电压 |
74| int32_t RegulatorGetVoltage(DevHandle handle, uint32_t \*voltage) | 获取Regulator输出电压 |
75| int32_t RegulatorSetCurrent(DevHandle handle, uint32_t minUa, uint32_t maxUa) | 设置Regulator输出电流 |
76| int32_t RegulatorGetCurrent(DevHandle handle, uint32_t \*regCurrent) | 获取Regulator输出电流 |
77| int32_t RegulatorGetStatus(DevHandle handle, uint32_t \*status) | 获取Regulator状态 |
78
79### 开发步骤
80
81使用Regulator设备的一般流程如图2所示。
82
83**图 2**  Regulator设备使用流程图
84
85![](figures/REGULATOR设备使用流程图.png)
86
87#### 获取Regulator设备句柄
88
89在操作Regulator设备时，首先要调用RegulatorOpen获取Regulator设备句柄，该函数会返回指定设备名称的Regulator设备句柄。
90
91```c
92DevHandle RegulatorOpen(const char *name);
93```
94
95**表2**  RegulatorOpen参数和返回值描述
96
97| 参数 | 参数描述 |
98| ---------- | ----------------------------- |
99| name | Regulator设备名称 |
100| **返回值** | **返回值描述** |
101| handle | 获取成功返回Regulator设备句柄 |
102| NULL | 获取失败 |
103
104
105
106```c
107/* Regulator设备名称 */
108const char *name = "regulator_virtual_1";
109DevHandle handle = NULL;
110
111/* 获取Regulator设备句柄 */
112handle = RegulatorOpen(name);
113if (handle  == NULL) {
114    /* 错误处理 */
115}
116```
117
118#### 销毁Regulator设备句柄
119
120关闭Regulator设备，系统释放对应的资源。
121
122```c
123void RegulatorClose(DevHandle handle);
124```
125
126**表3**  RegulatorClose参数描述
127
128| 参数 | 参数描述 |
129| ------ | ----------------- |
130| handle | Regulator设备句柄 |
131
132```c
133/* 销毁Regulator设备句柄 */
134RegulatorClose(handle);
135```
136
137#### 使能
138
139启用Regulator设备。
140
141```c
142int32_t RegulatorEnable(DevHandle handle);
143```
144
145**表4** RegulatorEnable参数描述
146
147| 参数 | 参数描述 |
148| ---------- | ----------------- |
149| handle | Regulator设备句柄 |
150| **返回值** | **返回值描述** |
151| 0 | 使能成功 |
152| 负数 | 使能失败 |
153
154
155
156```c
157int32_t ret;
158
159/* 启用Regulator设备 */
160ret = RegulatorEnable(handle);
161if (ret != 0) {
162	/* 错误处理 */
163}
164```
165
166#### 禁用
167
168禁用Regulator设备。如果Regulator设备状态为常开，或存在Regulator设备子节点未禁用，则禁用失败。
169
170```c
171int32_t RegulatorDisable(DevHandle handle);
172```
173
174**表5** RegulatorDisable参数描述
175
176| 参数 | 参数描述 |
177| ---------- | ----------------- |
178| handle | Regulator设备句柄 |
179| **返回值** | **返回值描述** |
180| 0 | 禁用成功 |
181| 负数 | 禁用失败 |
182
183```c
184int32_t ret;
185
186/* 禁用Regulator设备 */
187ret = RegulatorDisable(handle);
188if (ret != 0) {
189	/* 错误处理 */
190}
191```
192
193#### 强制禁用
194
195强制禁用Regulator设备。无论Regulator设备的状态是常开还是子节点已使能，Regulator设备都会被禁用。
196
197```c
198int32_t RegulatorForceDisable(DevHandle handle);
199```
200
201**表6** RegulatorForceDisable参数描述
202
203
204| 参数 | 参数描述 |
205| ---------- | ----------------- |
206| handle | Regulator设备句柄 |
207| **返回值** | **返回值描述** |
208| 0 | 禁用成功 |
209| 负数 | 禁用失败 |
210
211```c
212int32_t ret;
213
214/* 强制禁用Regulator设备 */
215ret = RegulatorForceDisable(handle);
216if (ret != 0) {
217	/* 错误处理 */
218}
219```
220
221#### 设置Regulator输出电压范围
222
223```c
224int32_t RegulatorSetVoltage(DevHandle handle, uint32_t minUv, uint32_t maxUv);
225```
226
227**表7** RegulatorSetVoltage参数描述
228
229| 参数 | 参数描述 |
230| ---------- | ----------------- |
231| handle | Regulator设备句柄 |
232| minUv | 最小电压 |
233| maxUv | 最大电压 |
234| **返回值** | **返回值描述** |
235| 0 | 设置成功 |
236| 负数 | 设置失败 |
237
238```c
239int32_t ret;
240int32_t minUv = 0;        // 最小电压为0µV
241int32_t maxUv = 20000;    // 最大电压为20000µV
242
243/* 设置Regulator电压输出电压范围 */
244ret = RegulatorSetVoltage(handle, minUv, maxUv);
245if (ret != 0) {
246	/* 错误处理 */
247}
248```
249
250#### 获取Regulator电压
251
252```c
253int32_t RegulatorGetVoltage(DevHandle handle, uint32_t *voltage);
254```
255
256**表8** RegulatorGetVoltage参数描述
257
258
259| 参数 | 参数描述 |
260| ---------- | ----------------- |
261| handle | Regulator设备句柄 |
262| *voltage | 参数指针 |
263| **返回值** | **返回值描述** |
264| 0 | 获取成功 |
265| 负数 | 获取失败 |
266
267```c
268int32_t ret;
269uint32_t voltage;
270
271/*获取Regulator电压*/
272ret = RegulatorGetVoltage(handle, &voltage);
273if (ret != 0) {
274	/*错误处理*/
275}
276```
277
278#### 设置Regulator输出电流范围
279
280```c
281int32_t RegulatorSetCurrent(DevHandle handle, uint32_t minUa, uint32_t maxUa);
282```
283
284**表9** RegulatorSetCurrent参数描述
285
286| 参数 | 参数描述 |
287| ---------- | ----------------- |
288| handle | Regulator设备句柄 |
289| minUa | 最小电流 |
290| maxUa | 最大电流 |
291| **返回值** | **返回值描述** |
292| 0<br>| 设置成功 |
293| 负数 | 设置失败 |
294
295```c
296int32_t ret;
297int32_t minUa = 0;	    // 最小电流为0μA
298int32_t maxUa = 200;    // 最大电流为200μA
299
300/* 设置Regulator输出电流范围 */
301ret = RegulatorSetCurrent(handle, minUa, maxUa);
302if (ret != 0) {
303	/* 错误处理 */
304}
305```
306
307#### 获取Regulator电流
308
309```c
310int32_t RegulatorGetCurrent(DevHandle handle, uint32_t *regCurrent);
311```
312
313**表10** RegulatorGetCurrent参数描述
314
315| 参数 | 参数描述 |
316| ----------- | ----------------- |
317| handle | Regulator设备句柄 |
318| *regCurrent | 参数指针 |
319| **返回值** | **返回值描述** |
320| 0 | 获取成功 |
321| 负数 | 获取失败 |
322
323```c
324int32_t ret;
325uint32_t regCurrent;
326
327/* 获取Regulator电流 */
328ret = RegulatorGetCurrent(handle, &regCurrent);
329if (ret != 0) {
330	/* 错误处理 */
331}
332```
333
334#### 获取Regulator状态
335
336```c
337int32_t RegulatorGetStatus(DevHandle handle, uint32_t *status);
338```
339
340**表11** RegulatorGetStatus参数描述
341
342| 参数 | 参数描述 |
343| ---------- | ----------------- |
344| handle | Regulator设备句柄 |
345| *status | 参数指针 |
346| **返回值** | **返回值描述** |
347| 0 | 获取成功 |
348| 负数 | 获取失败 |
349
350```c
351int32_t ret;
352uint32_t status;
353
354/* 获取Regulator状态 */
355ret = RegulatorGetStatus(handle, &status);
356if (ret != 0) {
357	/* 错误处理 */
358}
359```
360
361
362
363## 使用实例
364
365本例拟对Hi3516DV300开发板上Regulator设备进行简单的读取操作。
366
367Regulator设备完整的使用示例如下所示，首先获取Regulator设备句柄，然后使能，设置电压，获取电压、状态，禁用，最后销毁Regulator设备句柄。
368
369```c
370void RegulatorTestSample(void)
371{
372    int32_t ret;
373
374    /* Regulator设备名称 */
375	const char *name = "regulator_virtual_1";
376	DevHandle handle = NULL;
377
378	/* 获取Regulator设备句柄 */
379	handle = RegulatorOpen(name);
380	if (handle  == NULL) {
381    	HDF_LOGE("RegulatorOpen: failed!\n");
382        return;
383	}
384
385	/* 启用Regulator设备 */
386	ret = RegulatorEnable(handle);
387	if (ret != 0) {
388		HDF_LOGE("RegulatorEnable: failed, ret %d\n", ret);
389        goto _ERR;
390	}
391
392    int32_t minUv = 0;		// 最小电压为0µV
393	int32_t maxUv = 20000;  // 最大电压为20000µV
394
395	/* 设置Regulator输出电压范围 */
396	ret = RegulatorSetVoltage(handle, minUv, maxUv);
397	if (ret != 0) {
398		HDF_LOGE("RegulatorSetVoltage: failed, ret %d\n", ret);
399        goto _ERR;
400	}
401
402    uint32_t voltage;
403
404    /* 获取Regulator电压 */
405    ret = RegulatorGetVoltage(handle, &voltage);
406    if (ret != 0) {
407        HDF_LOGE("RegulatorGetVoltage: failed, ret %d\n", ret);
408        goto _ERR;
409    }
410
411    uint32_t status;
412
413    /* 获取Regulator状态 */
414    ret = RegulatorGetStatus(handle, &status);
415    if (ret != 0) {
416        HDF_LOGE("RegulatorGetStatus: failed, ret %d\n", ret);
417        goto _ERR;
418    }
419
420   /* 禁用Regulator设备 */
421    ret = RegulatorDisable(handle);
422    if (ret != 0) {
423        HDF_LOGE("RegulatorDisable: failed, ret %d\n", ret);
424        goto _ERR;
425    }
426
427_ERR:
428    /* 销毁Regulator设备句柄 */
429    RegulatorClose(handle);
430}
431```
432