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