1# Regulator
2
3## 概述
4
5### 功能简介
6
7Regulator模块用于控制系统中各类设备的电压/电流供应。在嵌入式系统(尤其是手机)中,控制耗电量很重要,直接影响到电池的续航时间。所以,如果系统中某一个模块暂时不需要使用,就可以通过Regulator关闭其电源供应;或者降低提供给该模块的电压、电流大小。
8
9### 运作机制
10
11在HDF框架中,Regulator模块接口适配模式采用统一服务模式(如图1所示),这需要一个设备服务来作为Regulator模块的管理器,统一处理外部访问,这会在配置文件中有所体现。统一服务模式适合于同类型设备对象较多的情况,如Regulator可能同时具备十几个控制器,采用独立服务模式需要配置更多的设备节点,且服务会占据内存资源。
12
13Regulator模块各分层的作用为:
14
15- 接口层:提供打开设备,操作Regulator,关闭设备的能力。
16
17- 核心层:主要负责服务绑定、初始化以及释放管理器,并提供添加、删除以及获取Regulator设备的能力。
18
19- 适配层:由驱动适配者实现与硬件相关的具体功能,如设备的初始化等。
20
21在统一模式下,所有的控制器都被核心层统一管理,并由核心层统一发布一个服务供接口层,因此这种模式下驱动无需再为每个控制器发布服务。
22
23**图 1** Regulator统一服务模式结构图<a name="fig1"></a>
24
25![Regulator统一服务模式结构图](figures/统一服务模式结构图.png)
26
27### 约束与限制
28
29Regulator模块当前仅支持小型系统。
30
31## 开发指导
32
33### 场景介绍
34
35Regulator模块用于控制系统中某些设备的电压/电流供应。当驱动开发者需要将Regulator设备适配到OpenHarmony时,需要进行Regulator驱动适配,下文将介绍如何进行Regulator驱动适配。
36
37### 接口说明
38
39为了保证上层在调用Regulator接口时能够正确的操作硬件,核心层在//drivers/hdf_core/framework/support/platform/include/regulator/regulator_core.h中定义了以下钩子函数。驱动适配者需要在适配层实现这些函数的具体功能,并与这些钩子函数挂接,从而完成接口层与核心层的交互。
40
41RegulatorMethod定义:
42
43```c
44struct RegulatorMethod {
45    int32_t (*open)(struct RegulatorNode *node);
46    int32_t (*close)(struct RegulatorNode *node);
47    int32_t (*release)(struct RegulatorNode *node);
48    int32_t (*enable)(struct RegulatorNode *node);
49    int32_t (*disable)(struct RegulatorNode *node);
50    int32_t (*forceDisable)(struct RegulatorNode *node);
51    int32_t (*setVoltage)(struct RegulatorNode *node, uint32_t minUv, uint32_t maxUv);
52    int32_t (*getVoltage)(struct RegulatorNode *node, uint32_t *voltage);
53    int32_t (*setCurrent)(struct RegulatorNode *node, uint32_t minUa, uint32_t maxUa);
54    int32_t (*getCurrent)(struct RegulatorNode *node, uint32_t *regCurrent);
55    int32_t (*getStatus)(struct RegulatorNode *node, uint32_t *status);
56};
57```
58
59**表 1**  RegulatorMethod 结构体成员的钩子函数功能说明
60
61| 成员函数 | 入参 | 返回值 | 功能 |
62| ------------ | ----------------------------------------------------------- | ----------------- | ---------------- |
63| open | node:结构体指针,核心层Regulator节点 | HDF_STATUS相关状态 | 打开设备 |
64| close | node:结构体指针,核心层Regulator节点 | HDF_STATUS相关状态 | 关闭设备 |
65| release | node:结构体指针,核心层Regulator节点 | HDF_STATUS相关状态 | 释放设备句柄 |
66| enable | node:结构体指针,核心层Regulator节点 | HDF_STATUS相关状态 | 使能 |
67| disable | node:结构体指针,核心层Regulator节点 | HDF_STATUS相关状态 | 禁用 |
68| forceDisable | node:结构体指针,核心层Regulator节点 | HDF_STATUS相关状态 | 强制禁用 |
69| setVoltage | node:结构体指针,核心层Regulator节点<br>minUv:uint32_t类型,最小电压<br>maxUv:uint32_t类型,最大电压 | HDF_STATUS相关状态 | 设置输出电压范围 |
70| getVoltage | node:结构体指针,核心层Regulator节点<br>voltage:uint32_t类型指针,传出电压值 | HDF_STATUS相关状态 | 获取电压 |
71| setCurrent | node:结构体指针,核心层Regulator节点<br>minUa:uint32_t类型,最小电流<br>maxUa:uint32_t类型,最大电流 | HDF_STATUS相关状态 | 设置输出电流范围 |
72| getCurrent | node:结构体指针,核心层Regulator节点<br>regCurrent:uint32_t类型指针,传出电流值 | HDF_STATUS相关状态 | 获取电流 |
73| getStatus | node:结构体指针,核心层Regulator节点<br>status:uint32_t类型指针,传出状态值 | HDF_STATUS相关状态 | 获取设备状态 |
74
75### 开发步骤
76
77Regulator模块适配包含以下四个步骤:
78
79- 实例化驱动入口
80
81- 配置属性文件
82
83- 实例化核心层接口函数
84
85- 驱动调试
86
871.  实例化驱动入口
88
89    驱动开发首先需要实例化驱动入口,驱动入口必须为HdfDriverEntry(在hdf_device_desc.h中定义)类型的全局变量,且moduleName要和device_info.hcs中保持一致。
90
91    HDF框架会汇总所有加载的驱动的HdfDriverEntry对象入口,形成一个类似数组的段地址空间,方便上层调用。
92
93    一般在加载驱动时HDF会先调用Init函数加载该驱动。当Init调用异常时,HDF框架会调用Release释放驱动资源并退出。
94
95    ```c
96    struct HdfDriverEntry g_regulatorDriverEntry = {
97        .moduleVersion = 1,
98        .moduleName = "virtual_regulator_driver",       // 【必要且与HCS文件中里面的moduleName匹配】
99        .Init = VirtualRegulatorInit,                   // 见Init参考
100        .Release = VirtualRegulatorRelease,             // 见Release参考
101    };
102    HDF_INIT(g_regulatorDriverEntry);                   // 调用HDF_INIT将驱动入口注册到HDF框架中
103    ```
104
1052. 配置属性文件
106
107    以Hi3516DV300开发板为例,在//vendor/hisilicon/hispark_taurus/hdf_config/device_info/device_info.hcs文件中添加deviceNode描述。
108
109    deviceNode信息与驱动入口注册相关,器件属性值与核心层RegulatorNode成员的默认值或限制范围有密切关系。
110
111    由于采用了统一服务模式,device_info.hcs文件中第一个设备节点必须为Regulator管理器,其各项参数必须如如表2所示:
112
113    **表 2** device_info.hcs节点参数说明
114
115    | 成员名 | 值 |
116    | --------------- | ------------------------------------------------------------ |
117    | policy | 驱动服务发布的策略,Regulator管理器具体配置为1,表示驱动对内核态发布服务 |
118    | priority | 驱动启动优先级(0-200)。值越大优先级越低,优先级相同则不保证device的加载顺序,regulator管理器具体配置为50 |
119    | permission | 驱动创建设备节点权限,Regulator管理器具体配置为0664 |
120    | moduleName | 驱动名称,Regulator管理器固定为HDF_PLATFORM_REGULATOR_MANAGER |
121    | serviceName | 驱动对外发布服务的名称,Regulator管理器固定为HDF_PLATFORM_REGULATOR_MANAGER |
122    | deviceMatchAttr | 驱动私有数据匹配的关键字,Regulator管理器设置为hdf_platform_regulator_manager |
123
124    从第二个节点开始配置具体Regulator控制器信息,此节点并不表示某一路Regulator控制器,而是代表一个资源性质设备,用于描述一类Regulator控制器的信息。本例只有一个Regulator设备,如有多个设备,则需要在device_info.hcs文件增加deviceNode信息,以及在regulator_config_linux.hcs文件中增加对应的器件属性。
125
126    - device_info.hcs 配置参考
127
128        ```c
129        root {
130            device_info {
131                platform :: host {
132                    hostName = "platform_host";
133                    priority = 50;
134                    device_regulator :: device {
135                        device0 :: deviceNode {	                                 // 为每一个Regulator控制器配置一个HDF设备节点,存在多个时添加,否则不用。
136                            policy = 1;	                                         // 2:用户态、内核态均可见;1:内核态可见;0:不需要发布服务。
137                            priority = 50;	                                     // 驱动启动优先级
138                            permission = 0644;	                                 // 驱动创建设备节点权限
139                            moduleName = "HDF_PLATFORM_REGULATOR_MANAGER";                                                //【必要】用于指定驱动名称,需要与期望的驱动Entry中的moduleName一致。
140                            serviceName = "HDF_PLATFORM_REGULATOR_MANAGER";		 // 【必要且唯一】驱动对外发布服务的名称
141                            deviceMatchAttr = "hdf_platform_regulator_manager";  // 【必要】用于配置控制器私有数据,要与regulator_config.hcs中对应控制器保持一致,具体的控制器信息在regulator_config.hcs中。
142                        }
143                        device1 :: deviceNode {
144                            policy = 0;
145                            priority = 55;
146                            permission = 0644;
147                            moduleName = "linux_regulator_adapter";
148                            deviceMatchAttr = "linux_regulator_adapter";
149                        }
150                    }
151                }
152            }
153        }
154        ```
155
156    - regulator_config_linux.hcs配置参考
157
158        ```c
159        root {
160            platform {
161                regulator_config {
162                match_attr = "linux_regulator_adapter";
163                template regulator_controller {   // 【必要】模板配置,继承该模板的节点如果使用模板中的默认值,则节点字段可以缺省。
164                    device_num = 1;
165                    name = "";
166                    devName = "regulator_adapter_consumer01";
167                    supplyName = "";
168                    mode = 1;
169                    minUv = 0;                    // 最小电压
170                    maxUv = 20000;                // 最大电压
171                    minUa = 0;                    // 最小电流
172                    maxUa = 0;                    // 最大电流
173                    }
174                controller_0x130d0000 :: regulator_controller {
175                    device_num = 1;
176                    name = "regulator_adapter_1";
177                    devName = "regulator_adapter_consumer01";
178                    supplyName = "virtual-regulator-hdf-adapter";
179                    mode = 1;
180                    minUv = 1000;
181                    maxUv = 50000;
182                    minUa = 0;
183                    maxUa = 0;
184                    }
185                // 每个Regulator控制器对应一个controller节点,如存在多个Regulator控制器,请依次添加对应的controller节点。
186                controller_0x130d0001 :: regulator_controller {
187                    device_num = 1;
188                    name = "regulator_adapter_2";
189                    devName = "regulator_adapter_consumer01";
190                    supplyName = "virtual2-regulator-hdf-adapter";
191                    mode = 2;
192                    minUv = 0;
193                    maxUv = 0;
194                    minUa = 1000;
195                    maxUa = 50000;
196                    }
197                }
198            }
199        }
200        ```
201
202        需要注意的是,新增regulator_config.hcs配置文件后,必须在hdf.hcs文件中将其包含,否则配置文件无法生效。
203
204        例如:本例中regulator_config.hcs所在路径为//vendor/hisilicon/hispark_taurus_linux/hdf_config/device/regulator/regulator_config_linux.hcs,则必须在产品对应的hdf.hcs中添加如下语句:
205
206        ```c
207        #include "device/regulator/regulator_config_linux.hcs"
208        ```
209
2103. 实例化核心层接口函数
211
212    完成驱动入口注册之后,下一步就是对核心层RegulatorNode对象的初始化,包括驱动适配者自定义结构体(传递参数和数据),实例化RegulatorNode成员RegulatorMethod(让用户可以通过接口来调用驱动底层函数),实现HdfDriverEntry成员函数(Bind、Init、Release)。
213
214    - 自定义结构体参考。
215
216        从驱动的角度看,RegulatorNode结构体是参数和数据的载体,HDF框架通过DeviceResourceIface将regulator_config.hcs文件中的数值读入其中。
217
218        ```c
219        // RegulatorNode是核心层控制器结构体,其中的成员在Init函数中会被赋值。
220        struct RegulatorNode {
221            struct RegulatorDesc regulatorInfo;
222            struct DListHead node;
223            struct RegulatorMethod *ops;
224            void *priv;
225            struct OsalMutex lock;
226        };
227
228        struct RegulatorDesc {
229            const char *name;                           // regulator名称
230            const char *parentName;                     // regulator父节点名称
231            struct RegulatorConstraints constraints;    // regulator约束信息
232            uint32_t minUv;                             // 最小输出电压值
233            uint32_t maxUv;                             // 最大输出电压值
234            uint32_t minUa;                             // 最小输出电流值
235            uint32_t maxUa;                             // 最大输出电流值
236            uint32_t status;                            // regulator的状态,开或关。
237            int useCount;
238            int consumerRegNums;                        // regulator用户数量
239            RegulatorStatusChangecb cb;                 // 当regulator状态改变时,可通过此变量通知。
240        };
241
242        struct RegulatorConstraints {
243            uint8_t alwaysOn;     // regulator是否常开
244            uint8_t mode;         // 模式:电压或者电流
245            uint32_t minUv;       // 最小可设置输出电压
246            uint32_t maxUv;       // 最大可设置输出电压
247            uint32_t minUa;       // 最小可设置输出电流
248            uint32_t maxUa;       // 最大可设置输出电流
249        };
250        ```
251
252    - 实例化RegulatorNode成员RegulatorMethod。
253
254        ```c
255        // regulator_virtual.c中的示例:钩子函数的填充
256        static struct RegulatorMethod g_method = {
257            .enable = VirtualRegulatorEnable,
258            .disable = VirtualRegulatorDisable,
259            .setVoltage = VirtualRegulatorSetVoltage,
260            .getVoltage = VirtualRegulatorGetVoltage,
261            .setCurrent = VirtualRegulatorSetCurrent,
262            .getCurrent = VirtualRegulatorGetCurrent,
263            .getStatus = VirtualRegulatorGetStatus,
264        };
265        ```
266
267    - Init函数开发参考
268
269        入参:
270
271        HdfDeviceObject是整个驱动对外提供的接口参数,具备HCS配置文件的信息。
272
273        返回值:
274
275        HDF_STATUS相关状态(表4为部分展示,如需使用其他状态,可参考//drivers/hdf_core/interfaces/inner_api/utils/hdf_base.h中HDF_STATUS定义)。
276
277        **表 3** HDF_STATUS相关状态说明
278
279        | 状态(值)               | 描述          |
280        | ---------------------- | -------------- |
281        | HDF_ERR_INVALID_OBJECT | 控制器对象非法 |
282        | HDF_ERR_MALLOC_FAIL    | 内存分配失败   |
283        | HDF_ERR_INVALID_PARAM  | 参数非法       |
284        | HDF_ERR_IO             | I/O 错误       |
285        | HDF_SUCCESS            | 初始化成功     |
286        | HDF_FAILURE            | 初始化失败     |
287
288        函数说明:
289
290        初始化自定义结构体和RegulatorNode成员,并通过调用核心层RegulatorNodeAdd函数挂载Regulator控制器。
291
292        ```c
293        static int32_t VirtualRegulatorInit(struct HdfDeviceObject *device)
294        {
295            int32_t ret;
296            const struct DeviceResourceNode *childNode = NULL;
297            ...
298            DEV_RES_NODE_FOR_EACH_CHILD_NODE(device->property, childNode) {
299                ret = VirtualRegulatorParseAndInit(device, childNode);         // 【必要】实现见下
300            ......
301            }
302            ......
303        }
304
305        static int32_t VirtualRegulatorParseAndInit(struct HdfDeviceObject *device, const struct DeviceResourceNode *node)
306        {
307            int32_t ret;
308            struct RegulatorNode *regNode = NULL;
309            (void)device;
310
311            regNode = (struct RegulatorNode *)OsalMemCalloc(sizeof(*regNode)); //加载HCS文件
312            ......
313            ret = VirtualRegulatorReadHcs(regNode, node);                      // 读取HCS文件信息
314            ......
315            regNode->priv = (void *)node;                                      // 实例化节点
316            regNode->ops = &g_method;                                          // 实例化ops
317
318            ret = RegulatorNodeAdd(regNode);                                   // 挂载节点
319            ......
320        }
321        ```
322
323    - Release函数开发参考
324
325        入参:
326
327        HdfDeviceObject是整个驱动对外提供的接口参数,其包含了HCS配置文件中的相关配置信息。
328
329        返回值:
330
331        无。
332
333        函数说明:
334
335        释放内存和删除控制器,该函数需要在驱动入口结构体中赋值给Release接口,当HDF框架调用Init函数初始化驱动失败时,可以调用Release释放驱动资源。
336
337        ```c
338        static void VirtualRegulatorRelease(struct HdfDeviceObject *device)
339        {
340            ......
341            RegulatorNodeRemoveAll(); // 【必要】调用核心层函数,释放RegulatorNode的设备和服务
342        }
343        ```
344
3454. 驱动调试
346
347   【可选】针对新增驱动程序,建议验证驱动基本功能,例如挂载后的测试用例是否成功等。
348