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