driver-platform-regulator-des.md 10.9 KB
Newer Older
1
# Regulator
Z
zhangyalei 已提交
2 3


4
## 概述
Z
zhangyalei 已提交
5

6
### 功能简介
Z
zhangyalei 已提交
7

8 9 10 11 12 13
Regulator模块用于控制系统中某些设备的电压/电流供应。在嵌入式系统(尤其是手机)中,控制耗电量很重要,直接影响到电池的续航时间。所以,如果系统中某一个模块暂时不需要使用,就可以通过Regulator关闭其电源供应;或者降低提供给该模块的电压、电流大小。
Regulator接口定义了操作Regulator设备的通用方法集合,包括:
- Regulator设备句柄获取和销毁。
- Regulator设备电压、电流的设置。
- Regulator设备使能和关闭。
- Regulator设备电压、电流和状态的获取。
Z
zhangyalei 已提交
14 15


16
### 基本概念 
Z
zhangyalei 已提交
17 18 19 20 21 22 23

-  校准器 

   当输入电压和输出负载发生变化时可以通过软件调整,使其能够提供稳定的输出电压。 

- Consumer

24
   由Regulator供电的设备统称为Consumer, 其可分为静态和动态两类:
Z
zhangyalei 已提交
25 26 27 28

   * 静态:不需要改变电压电流,只需要开关电源,通常在bootloader、firmware、kernel board阶段被设置。
   * 动态:根据操作需求改变电压电流。

29
- PMIC(Power Management IC)
Z
zhangyalei 已提交
30 31 32 33

   电源管理芯片,内含多个电源甚至其他子系统。 


34
### 运作机制
Z
zhangyalei 已提交
35

36
在HDF框架中,Regulator模块接口适配模式采用统一服务模式,这需要一个设备服务来作为Regulator模块的管理器,统一处理外部访问,这会在配置文件中有所体现。统一服务模式适合于同类型设备对象较多的情况,如Regulator可能同时具备十几个控制器,采用独立服务模式需要配置更多的设备节点,且服务会占据内存资源。
Z
zhangyalei 已提交
37

38
Regulator模块各分层的作用为:接口层提供打开设备,写入数据,关闭设备接口的能力。核心层主要提供绑定设备、初始化设备以及释放设备的能力。适配层实现其他具体的功能。
Z
zhangyalei 已提交
39

40
![](../public_sys-resources/icon-note.gif) 说明:<br>核心层可以调用接口层的函数,也可以通过钩子函数调用适配层函数,从而使得适配层间接的可以调用接口层函数,但是不可逆转接口层调用适配层函数。
Z
zhangyalei 已提交
41

42
**图 1** 统一服务模式结构图
Z
zhangyalei 已提交
43 44 45

![image1](figures/统一服务模式结构图.png)

46
### 约束与限制
Z
zhangyalei 已提交
47

48
Regulator模块当前仅支持轻量和小型系统内核(LiteOS)。
Z
zhangyalei 已提交
49

50
## 使用指导
Z
zhangyalei 已提交
51

52
### 场景介绍
Z
zhangyalei 已提交
53

54
Regulator主要用于:
Z
zhangyalei 已提交
55 56

1. 用于控制系统中某些设备的电压/电流供应。
57
2. 用于稳压电源的管理。
Z
zhangyalei 已提交
58

59
### 接口说明
60

61
**表1**  Regulator设备API接口说明
62

63
| 接口名 | 描述 |
Z
zhangyalei 已提交
64
| --------------------- | ------------------------- |
65 66 67 68 69 70 71 72 73 74
| RegulatorOpen | 获取Regulator设备驱动句柄 |
| RegulatorClose | 销毁Regulator设备驱动句柄 |
| RegulatorEnable | 使能Regulator |
| RegulatorDisable | 禁用Regulator |
| RegulatorForceDisable | 强制禁用Regulator |
| RegulatorSetVoltage | 设置Regulator输出电压 |
| RegulatorGetVoltage | 获取Regulator输出电压 |
| RegulatorSetCurrent | 设置Regulator输出电流 |
| RegulatorGetCurrent | 获取Regulator输出电流 |
| RegulatorGetStatus | 获取Regulator状态 |
Z
zhangyalei 已提交
75 76 77



78
### 开发步骤
79

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

82
使用Regulator设备的一般流程如图2所示。
83

84
**图 2**  Regulator设备使用流程图  
85 86 87

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

88
#### 获取Regulator设备句柄
89

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

Z
zhangyalei 已提交
92
```
93 94 95 96 97
DevHandle RegulatorOpen(const char *name);
```

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

98
| 参数 | 参数描述 |
99
| ---------- | ----------------------------- |
100 101 102 103
| name | Regulator设备名称 |
| **返回值** | **返回值描述** |
| handle | 获取成功返回Regulator设备句柄 |
| NULL | 获取失败 |
104 105


Z
zhangyalei 已提交
106 107

```
108
/* Regulator设备名称 */
109 110 111
const char *name = "regulator_virtual_1";
DevHandle handle = NULL;

112
/* 获取Regulator设备句柄 */
113 114 115 116 117 118
handle = RegulatorOpen(name);
if (handle  == NULL) {
    /* 错误处理 */
}
```

119
#### 销毁Regulator设备句柄
120

121
关闭Regulator设备,系统释放对应的资源。
122

Z
zhangyalei 已提交
123
```
124 125 126 127 128
void RegulatorClose(DevHandle handle);
```

**表3**  RegulatorClose参数描述

129
| 参数 | 参数描述 |
130
| ------ | ----------------- |
131
| handle | Regulator设备句柄 |
132

Z
zhangyalei 已提交
133
```
134
/* 销毁Regulator设备句柄 */
135 136 137
RegulatorClose(handle);
```

138
#### 使能
139

140
启用Regulator设备。
141

Z
zhangyalei 已提交
142
```
143 144 145
int32_t RegulatorEnable(DevHandle handle);
```

146
**表4** RegulatorEnable参数描述
147

148
| 参数 | 参数描述 |
149
| ---------- | ----------------- |
150 151 152 153
| handle | Regulator设备句柄 |
| **返回值** | **返回值描述** |
| 0 | 使能成功 |
| 负数 | 使能失败 |
154

Z
zhangyalei 已提交
155 156 157


```
158 159
int32_t ret;

160
/* 启用Regulator设备 */
161 162
ret = RegulatorEnable(handle);
if (ret != 0) {
163
	/* 错误处理 */
164 165 166
}
```

167
#### 禁用
168

169
禁用Regulator设备。如果Regulator设备状态为常开,或存在Regulator设备子节点未禁用,则禁用失败。
170

Z
zhangyalei 已提交
171
```
172 173 174 175 176
int32_t RegulatorDisable(DevHandle handle);
```

**表5** RegulatorDisable参数描述

177
| 参数 | 参数描述 |
178
| ---------- | ----------------- |
179 180 181 182
| handle | Regulator设备句柄 |
| **返回值** | **返回值描述** |
| 0 | 禁用成功 |
| 负数 | 禁用失败 |
183

Z
zhangyalei 已提交
184
```
185 186
int32_t ret;

187
/* 禁用Regulator设备 */
188 189
ret = RegulatorDisable(handle);
if (ret != 0) {
190
	/* 错误处理 */
191 192 193
}
```

194
#### 强制禁用
195

196
强制禁用Regulator设备。无论Regulator设备的状态是常开还是子节点已使能,Regulator设备都会被禁用。
197

Z
zhangyalei 已提交
198
```
199 200 201
int32_t RegulatorForceDisable(DevHandle handle);
```

202
**表6** RegulatorForceDisable参数描述
203 204


205
| 参数 | 参数描述 |
206
| ---------- | ----------------- |
207 208 209 210
| handle | Regulator设备句柄 |
| **返回值** | **返回值描述** |
| 0 | 禁用成功 |
| 负数 | 禁用失败 |
211

Z
zhangyalei 已提交
212
```
213 214
int32_t ret;

215
/* 强制禁用Regulator设备 */
216 217
ret = RegulatorForceDisable(handle);
if (ret != 0) {
218
	/* 错误处理 */
219 220
}
```
Z
zhangyalei 已提交
221

222
#### 设置Regulator输出电压范围
223

224
设置Regulator电压输出电压范围。
225

Z
zhangyalei 已提交
226
```
227 228 229 230 231
int32_t RegulatorSetVoltage(DevHandle handle, uint32_t minUv, uint32_t maxUv);
```

**表7** RegulatorSetVoltage参数描述

232
| 参数 | 参数描述 |
233
| ---------- | ----------------- |
234 235 236 237 238 239
| handle | Regulator设备句柄 |
| minUv | 最小电压 |
| maxUv | 最大电压 |
| **返回值** | **返回值描述** |
| 0 | 设置成功 |
| 负数 | 设置失败 |
240

Z
zhangyalei 已提交
241
```
242
int32_t ret;
243 244
int32_t minUv = 0;        // 最小电压为0µV
int32_t maxUv = 20000;    // 最大电压为20000µV
245

246
/* 设置Regulator电压输出电压范围 */
247 248
ret = RegulatorSetVoltage(handle, minUv, maxUv);
if (ret != 0) {
249
	/* 错误处理 */
250 251
}
```
Z
zhangyalei 已提交
252

253
#### 获取Regulator电压
254

255
获取Regulator电压。
256

Z
zhangyalei 已提交
257
```
258 259 260 261 262 263
int32_t RegulatorGetVoltage(DevHandle handle, uint32_t *voltage);
```

**表8** RegulatorGetVoltage参数描述


264
| 参数 | 参数描述 |
265
| ---------- | ----------------- |
266 267 268 269 270
| handle | Regulator设备句柄 |
| *voltage | 参数指针 |
| **返回值** | **返回值描述** |
| 0 | 获取成功 |
| 负数 | 获取失败 |
271

Z
zhangyalei 已提交
272
```
273 274 275
int32_t ret;
uint32_t voltage;

276
/*获取Regulator电压*/
277 278 279 280 281 282
ret = RegulatorGetVoltage(handle, &voltage);
if (ret != 0) {
	/*错误处理*/
}
```

283
#### 设置Regulator输出电流范围
284

285
设置Regulator输出电流范围。
286

Z
zhangyalei 已提交
287
```
288 289 290 291 292
int32_t RegulatorSetCurrent(DevHandle handle, uint32_t minUa, uint32_t maxUa);
```

**表9** RegulatorSetCurrent参数描述

293
| 参数 | 参数描述 |
294
| ---------- | ----------------- |
295 296 297 298 299 300
| handle | Regulator设备句柄 |
| minUa | 最小电流 |
| maxUa | 最大电流 |
| **返回值** | **返回值描述** |
| 0<br>| 设置成功 |
| 负数 | 设置失败 |
301

Z
zhangyalei 已提交
302
```
303
int32_t ret;
304 305
int32_t minUa = 0;	// 最小电流为0μA
int32_t maxUa = 200;    // 最大电流为200μA
306

307
/* 设置Regulator输出电流范围 */
308 309
ret = RegulatorSetCurrent(handle, minUa, maxUa);
if (ret != 0) {
310
	/* 错误处理 */
311 312 313
}
```

314
#### 获取Regulator电流
315

316
获取Regulator电流。
317

Z
zhangyalei 已提交
318
```
319 320 321 322 323
int32_t RegulatorGetCurrent(DevHandle handle, uint32_t *regCurrent);
```

**表10** RegulatorGetCurrent参数描述

324
| 参数 | 参数描述 |
325
| ----------- | ----------------- |
326 327 328 329 330
| handle | Regulator设备句柄 |
| *regCurrent | 参数指针 |
| **返回值** | **返回值描述** |
| 0 | 获取成功 |
| 负数 | 获取失败 |
331

Z
zhangyalei 已提交
332
```
333 334 335
int32_t ret;
uint32_t regCurrent;

336
/* 获取Regulator电流 */
337 338
ret = RegulatorGetCurrent(handle, &regCurrent);
if (ret != 0) {
339
	/* 错误处理 */
340 341
}
```
Z
zhangyalei 已提交
342

343
#### 获取Regulator状态
344

345
获取Regulator状态。
346

Z
zhangyalei 已提交
347
```
348 349 350
int32_t RegulatorGetStatus(DevHandle handle, uint32_t *status);
```

351
**表11** RegulatorGetStatus参数描述
352

353
| 参数 | 参数描述 |
354
| ---------- | ----------------- |
355 356 357 358 359
| handle | Regulator设备句柄 |
| *status | 参数指针 |
| **返回值** | **返回值描述** |
| 0 | 获取成功 |
| 负数 | 获取失败 |
360

Z
zhangyalei 已提交
361
```
362 363 364
int32_t ret;
uint32_t status;

365
/* 获取Regulator状态 */
366 367
ret = RegulatorGetStatus(handle, &status);
if (ret != 0) {
368
	/* 错误处理 */
369 370 371
}
```

Z
zhangyalei 已提交
372 373


374
## 使用实例
375

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

Z
zhangyalei 已提交
378
```
379 380 381 382
void RegulatorTestSample(void)
{
    int32_t ret;
     
383
    /* Regulator设备名称 */
384 385 386
	const char *name = "regulator_virtual_1";
	DevHandle handle = NULL;

387
	/* 获取Regulator设备句柄 */
388 389 390 391 392 393
	handle = RegulatorOpen(name);
	if (handle  == NULL) {
    	HDF_LOGE("RegulatorOpen: failed!\n");
        return;
	}

394
	/* 启用Regulator设备 */
395 396 397 398 399 400
	ret = RegulatorEnable(handle);
	if (ret != 0) {
		HDF_LOGE("RegulatorEnable: failed, ret %d\n", ret);
        goto _ERR;
	}
    
401 402
    int32_t minUv = 0;		// 最小电压为0µV
	int32_t maxUv = 20000;  // 最大电压为20000µV
403

404
	/* 设置Regulator输出电压范围 */
405 406 407 408 409 410 411 412
	ret = RegulatorSetVoltage(handle, minUv, maxUv);
	if (ret != 0) {
		HDF_LOGE("RegulatorSetVoltage: failed, ret %d\n", ret);
        goto _ERR;
	}
    
    uint32_t voltage;

413
    /* 获取Regulator电压 */
414 415 416 417 418 419 420 421
    ret = RegulatorGetVoltage(handle, &voltage);
    if (ret != 0) {
        HDF_LOGE("RegulatorGetVoltage: failed, ret %d\n", ret);
        goto _ERR;
    }
    
    uint32_t status;

422
    /* 获取Regulator状态 */
423 424 425 426 427 428
    ret = RegulatorGetStatus(handle, &status);
    if (ret != 0) {
        HDF_LOGE("RegulatorGetStatus: failed, ret %d\n", ret);
        goto _ERR;
    }

429
   /* 禁用Regulator设备 */
430 431 432 433 434 435 436
    ret = RegulatorDisable(handle);
    if (ret != 0) {
        HDF_LOGE("RegulatorDisable: failed, ret %d\n", ret);
        goto _ERR;
    }
    
_ERR:
437
    /* 销毁Regulator设备句柄 */
438 439
    RegulatorClose(handle); 
}
Z
zhangyalei 已提交
440
```