driver-platform-regulator-develop.md 16.6 KB
Newer Older
1
# Regulator
2 3


4
## 概述
5

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

8
Regulator模块用于控制系统中某些设备的电压/电流供应。
Z
zhangyalei 已提交
9

10
### 基本概念
Z
zhangyalei 已提交
11

12
Regulator模块用于控制系统中某些设备的电压/电流供应。在嵌入式系统(尤其是手机)中,控制耗电量很重要,直接影响到电池的续航时间。所以,如果系统中某一个模块暂时不需要使用,就可以通过Regulator关闭其电源供应;或者降低提供给该模块的电压、电流大小。
Z
zhangyalei 已提交
13

14
### 运作机制
Z
zhangyalei 已提交
15

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

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

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

22
**图 1** 统一服务模式结构图
Z
zhangyalei 已提交
23

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



28
### 约束与限制
Z
zhangyalei 已提交
29

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

32
## 开发指导
Z
zhangyalei 已提交
33

34
### 场景介绍
Z
zhangyalei 已提交
35

36
Regulator模块用于控制系统中某些设备的电压/电流供应。
Z
zhangyalei 已提交
37

38
### 接口说明
Z
zhangyalei 已提交
39

40
通过以下RegulatorMethod中的函数调用Regulator驱动对应的函数。
Z
zhangyalei 已提交
41 42 43 44

RegulatorMethod定义:

```
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59
struct RegulatorMethod {
    int32_t (*open)(struct RegulatorNode *node);
    int32_t (*close)(struct RegulatorNode *node);
    int32_t (*release)(struct RegulatorNode *node);
    int32_t (*enable)(struct RegulatorNode *node);
    int32_t (*disable)(struct RegulatorNode *node);
    int32_t (*forceDisable)(struct RegulatorNode *node);
    int32_t (*setVoltage)(struct RegulatorNode *node, uint32_t minUv, uint32_t maxUv);
    int32_t (*getVoltage)(struct RegulatorNode *node, uint32_t *voltage);
    int32_t (*setCurrent)(struct RegulatorNode *node, uint32_t minUa, uint32_t maxUa);
    int32_t (*getCurrent)(struct RegulatorNode *node, uint32_t *regCurrent);
    int32_t (*getStatus)(struct RegulatorNode *node, uint32_t *status);
};
```

Z
zhangyalei 已提交
60
**表 1**  RegulatorMethod 结构体成员的回调函数功能说明
61 62


Z
zhangyalei 已提交
63 64
| 成员函数     | 入参                                                         | 返回值             | 功能             |
| ------------ | ------------------------------------------------------------ | ------------------ | ---------------- |
65 66 67 68 69 70 71 72 73 74 75 76 77 78 79
| open         | **node**:结构体指针,核心层Regulator节点;                  | HDF_STATUS相关状态 | 打开设备         |
| close        | **node**:结构体指针,核心层Regulator节点;                  | HDF_STATUS相关状态 | 关闭设备         |
| release      | **node**:结构体指针,核心层Regulator节点;                  | HDF_STATUS相关状态 | 释放设备句柄     |
| enable       | **node**:结构体指针,核心层Regulator节点;                  | HDF_STATUS相关状态 | 使能             |
| disable      | **node**:结构体指针,核心层Regulator节点;                  | HDF_STATUS相关状态 | 禁用             |
| forceDisable | **node**:结构体指针,核心层Regulator节点;                  | HDF_STATUS相关状态 | 强制禁用         |
| setVoltage   | **node**:结构体指针,核心层Regulator节点;<br>**minUv**:uint32_t变量,最小电压;<br>**maxUv**:uint32_t变量,最大电压; | HDF_STATUS相关状态 | 设置输出电压范围 |
| getVoltage   | **node**:结构体指针,核心层Regulator节点;<br>**voltage**:uint32_t指针,传出电压值; | HDF_STATUS相关状态 | 获取电压         |
| setCurrent   | **node**:结构体指针,核心层Regulator节点;<br>**minUa**:uint32_t变量,最小电流;<br>**maxUa**:uint32_t变量,最大电流; | HDF_STATUS相关状态 | 设置输出电流范围 |
| getCurrent   | **node**:结构体指针,核心层Regulator节点;<br>**regCurrent**:uint32_t指针,传出电流值; | HDF_STATUS相关状态 | 获取电流         |
| getStatus    | **node**:结构体指针,核心层Regulator节点;<br>**status**:uint32_t指针,传出状态值; | HDF_STATUS相关状态 | 获取设备状态     |

### 开发步骤

Regulator模块适配包含以下四个步骤:
80

Z
zhangyalei 已提交
81 82 83 84
- 实例化驱动入口。
- 配置属性文件。
- 实例化核心层接口函数。
- 驱动调试。
85

Z
zhangyalei 已提交
86
1.  **实例化驱动入口:**
87

Z
zhangyalei 已提交
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103
    驱动开发首先需要实例化驱动入口,驱动入口必须为HdfDriverEntry(在 hdf_device_desc.h 中定义)类型的全局变量,且moduleName要和device_info.hcs中保持一致。 HDF框架会汇总所有加载的驱动的HdfDriverEntry对象入口 ,形成一个类似数组的段地址空间,方便上层调用。
    
    一般在加载驱动时HDF会先调用Init函数加载该驱动。当Init调用异常时,HDF框架会调用Release释放驱动资源并退出。
    
    ```
    struct HdfDriverEntry g_regulatorDriverEntry = {
        .moduleVersion = 1,
        .moduleName = "virtual_regulator_driver",//【必要且与HCS文件中里面的moduleName匹配】
        .Init = VirtualRegulatorInit,
        .Release = VirtualRegulatorRelease,
    };
    //调用HDF_INIT将驱动入口注册到HDF框架中
    HDF_INIT(g_regulatorDriverEntry);
    ```
    
2. **配置属性文件:**
104

Z
zhangyalei 已提交
105
   - 在vendor/hisilicon/hispark_taurus/hdf_config/device_info/device_info.hcs文件中添加deviceNode描述。
106

Z
zhangyalei 已提交
107
     deviceNode信息与驱动入口注册相关,器件属性值与核心层RegulatorNode成员的默认值或限制范围有密切关系。
108

109
     由于采用了统一服务模式,device_info.hcs文件中第一个设备节点必须为Regulator管理器,其各项参数必须如下设置:
110

Z
zhangyalei 已提交
111 112 113 114 115
     | 成员名          | 值                                                           |
     | --------------- | ------------------------------------------------------------ |
     | policy          | 具体配置为0,不发布服务                                      |
     | priority        | 驱动启动优先级(0-200),值越大优先级越低,,优先级相同则不保证device的加载顺序。 |
     | permission      | 驱动权限                                                     |
116
     | moduleName      | 固定为HDF_PLATFORM_REGULATOR_MANAGER                        |
Z
zhangyalei 已提交
117 118
     | serviceName     | 固定为HDF_PLATFORM_REGULATOR_MANAGER                         |
     | deviceMatchAttr | 没有使用,可忽略                                             |
Y
modify  
yinshuqing 已提交
119

120
     从第二个节点开始配置具体Regulator控制器信息,此节点并不表示某一路Regulator控制器,而是代表一个资源性质设备,用于描述一类Regulator控制器的信息。本例只有一个Regulator设备,如有多个设备,则需要在device_info文件增加deviceNode信息,以及在regulator\_config文件中增加对应的器件属性。
121

Z
zhangyalei 已提交
122
    - device_info.hcs 配置参考。
123

Z
zhangyalei 已提交
124 125
       ```
       root {
126 127 128 129 130
       device_info { 
         platform :: host {
           hostName = "platform_host";
           priority = 50;
           device_regulator :: device {
131 132 133
               device0 :: deviceNode {	//为每一个Regulator控制器配置一个HDF设备节点,存在多个时添加,否则不用
                   policy = 1;	        // 2:用户态可见,1:内核态可见,0:不需要发布服务
                   priority = 50;	// 驱动启动优先级
134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150
                   permission = 0644;	// 驱动创建设备节点权限
                   /*【必要】用于指定驱动名称,需要与期望的驱动Entry中的moduleName一致;*/
                   moduleName = "HDF_PLATFORM_REGULATOR_MANAGER";		
                   serviceName = "HDF_PLATFORM_REGULATOR_MANAGER";		//【必要且唯一】驱动对外发布服务的名称
                  /*【必要】用于配置控制器私有数据,要与regulator_config.hcs中对应控制器保持一致,具体的控制器信息在regulator_config.hcs 中*/
                   deviceMatchAttr = "hdf_platform_regulator_manager";
               }
               device1 :: deviceNode {
                   policy = 0;
                   priority = 55;
                   permission = 0644;
                   moduleName = "linux_regulator_adapter";
                   deviceMatchAttr = "linux_regulator_adapter";
               }
           }
         }
       }
Z
zhangyalei 已提交
151 152 153 154 155
       }
       ```

    - regulator\_config.hcs 配置参考。

156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198
      ```
      root {
          platform {
              regulator_config {
              match_attr = "linux_regulator_adapter";
              template regulator_controller {    //【必要】模板配置,继承该模板的节点如果使用模板中的默认值,则节点字段可以缺省
                  device_num = 1;
                  name = "";
                  devName = "regulator_adapter_consumer01";
                  supplyName = "";
                  mode = 1;
                  minUv = 0;
                  maxUv = 20000;
                  minUa = 0;
                  maxUa = 0;
                  }
              controller_0x130d0000 :: regulator_controller {
                  device_num = 1;
                  name = "regulator_adapter_1";
                  devName = "regulator_adapter_consumer01";
                  supplyName = "virtual-regulator-hdf-adapter";
                  mode = 1;
                  minUv = 1000;
                  maxUv = 50000;
                  minUa = 0;
                  maxUa = 0;
                  }
              /*每个Regulator控制器对应一个controller节点,如存在多个Regulator控制器,请依次添加对应的controller节点。*/
              controller_0x130d0001 :: regulator_controller {
                  device_num = 1;
                  name = "regulator_adapter_2";
                  devName = "regulator_adapter_consumer01";
                  supplyName = "virtual2-regulator-hdf-adapter";
                  mode = 2;
                  minUv = 0;
                  maxUv = 0;
                  minUa = 1000;
                  maxUa = 50000;
                  }
              }
          }
      }
      ```
Z
zhangyalei 已提交
199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246

3.  **实例化核心层接口函数:**
    
    - 完成驱动入口注册之后,最后一步就是对核心层RegulatorNode对象的初始化,包括厂商自定义结构体(传递参数和数据),实例化RegulatorNode成员RegulatorMethod(让用户可以通过接口来调用驱动底层函数),实现HdfDriverEntry成员函数(Bind,Init,Release)。
    
    - 自定义结构体参考。

        从驱动的角度看,RegulatorNode结构体是参数和数据的载体,HDF框架通过DeviceResourceIface将regulator\_config.hcs文件中的数值读入其中。
    
        ```
        // RegulatorNode是核心层控制器结构体,其中的成员在Init函数中会被赋值
        struct RegulatorNode {
            struct RegulatorDesc regulatorInfo;
            struct DListHead node;
            struct RegulatorMethod *ops;
            void *priv;
            struct OsalMutex lock;
        };
        
        struct RegulatorDesc {
            const char *name;              /* regulator 名称 */
            const char *parentName;        /* regulator 父节点名称 */
            struct RegulatorConstraints constraints;    /* regulator 约束信息 */
            uint32_t minUv;                  /* 最小输出电压值 */
            uint32_t maxUv;                  /* 最大输出电压值 */
            uint32_t minUa;                  /* 最小输出电流值 */
            uint32_t maxUa;                  /* 最大输出电流值 */
            uint32_t status;                 /* regulator的状态,开或关 */
            int useCount;
            int consumerRegNums;             /* regulator用户数量 */
            RegulatorStatusChangecb cb;      /* 当regulator状态改变时,可通过此变量通知 */
        };
        
        struct RegulatorConstraints {
            uint8_t alwaysOn;     /* regulator是否常开 */
            uint8_t mode;         /* 模式:电压或者电流 */
            uint32_t minUv;       /* 最小可设置输出电压 */
            uint32_t maxUv;       /* 最大可设置输出电压 */
            uint32_t minUa;       /* 最小可设置输出电流 */
            uint32_t maxUa;       /* 最大可设置输出电流 */
        };
        ```
    
      
    
    - 实例化RegulatorNode成员RegulatorMethod,其他成员在Init函数中初始化。
    
      ```c
247
      // regulator_virtual.c 中的示例:钩子函数的填充
Z
zhangyalei 已提交
248 249 250 251 252 253 254 255 256 257 258 259 260 261 262
      static struct RegulatorMethod g_method = {
          .enable = VirtualRegulatorEnable,
          .disable = VirtualRegulatorDisable,
          .setVoltage = VirtualRegulatorSetVoltage,
          .getVoltage = VirtualRegulatorGetVoltage,
          .setCurrent = VirtualRegulatorSetCurrent,
          .getCurrent = VirtualRegulatorGetCurrent,
          .getStatus = VirtualRegulatorGetStatus,
      };
      ```
      
    
    
    - Init函数参考
    
263
       入参:
Z
zhangyalei 已提交
264
    
265
       HdfDeviceObject 是整个驱动对外暴露的接口参数,具备 HCS 配置文件的信息。
Z
zhangyalei 已提交
266
        
267
       返回值:
Z
zhangyalei 已提交
268
        
269
       HDF\_STATUS相关状态(下表为部分展示,如需使用其他状态,可见//drivers/framework/include/utils/hdf\_base.h中HDF\_STATUS 定义)。
Z
zhangyalei 已提交
270
        
271
       **表 2**  HDF\_STATUS相关状态
Z
zhangyalei 已提交
272
    
273 274 275 276 277 278 279 280
       | 状态(值)               | 问题描述       |
       | ---------------------- | -------------- |
       | HDF_ERR_INVALID_OBJECT | 控制器对象非法 |
       | HDF_ERR_MALLOC_FAIL    | 内存分配失败   |
       | HDF_ERR_INVALID_PARAM  | 参数非法       |
       | HDF_ERR_IO             | I/O 错误       |
       | HDF_SUCCESS            | 初始化成功     |
       | HDF_FAILURE            | 初始化失败     |
Z
zhangyalei 已提交
281
    
282
       函数说明:
Z
zhangyalei 已提交
283
    
284
       初始化自定义结构体和RegulatorNode成员,并通过调用核心层RegulatorNodeAdd函数挂载Regulator控制器。
Z
zhangyalei 已提交
285
    
286 287 288 289 290 291 292 293 294 295 296 297 298

       ```c
       static int32_t VirtualRegulatorInit(struct HdfDeviceObject *device)
       {
           int32_t ret;
           const struct DeviceResourceNode *childNode = NULL;
           ...
           DEV_RES_NODE_FOR_EACH_CHILD_NODE(device->property, childNode) {
           ret = VirtualRegulatorParseAndInit(device, childNode);//【必要】实现见下
           ...
           }
           ...
       }
Z
zhangyalei 已提交
299
    
300 301 302 303 304
       static int32_t VirtualRegulatorParseAndInit(struct HdfDeviceObject *device, const struct DeviceResourceNode *node)
       {
           int32_t ret;
           struct RegulatorNode *regNode = NULL;
           (void)device;
Z
zhangyalei 已提交
305
    
306 307 308 309 310 311
           regNode = (struct RegulatorNode *)OsalMemCalloc(sizeof(*regNode));//加载HCS文件
           ...
           ret = VirtualRegulatorReadHcs(regNode, node);//读取HCS文件信息
           ...
           regNode->priv = (void *)node;    //实例化节点
           regNode->ops = &g_method;        //实例化ops
Z
zhangyalei 已提交
312
    
313 314 315 316
           ret = RegulatorNodeAdd(regNode); //挂载节点
           ...
       }
       ```
Z
zhangyalei 已提交
317 318 319 320 321 322 323 324 325 326 327 328 329 330 331
    
    -   Release 函数参考
        
         入参:
        
         HdfDeviceObject是整个驱动对外暴露的接口参数,其包含了HCS配置文件中的相关配置信息。
        
         返回值:
        
         无。
        
         函数说明:
        
         释放内存和删除控制器,该函数需要在驱动入口结构体中赋值给Release接口,当HDF框架调用Init函数      初始化驱动失败时,可以调用Release释放驱动资源。
      
Y
modify  
yinshuqing 已提交
332 333 334 335 336 337
        ```c
        static void VirtualRegulatorRelease(struct HdfDeviceObject *device)
        {
            ...
            RegulatorNodeRemoveAll();//【必要】调用核心层函数,释放RegulatorNode的设备和服务
        }
Z
zhangyalei 已提交
338 339 340 341 342 343 344
        ```
    
4. **驱动调试:**

   【可选】针对新增驱动程序,建议验证驱动基本功能,例如挂载后的测试用例是否成功等。