diff --git a/zh-cn/device-dev/driver/driver-platform-regulator-des.md b/zh-cn/device-dev/driver/driver-platform-regulator-des.md index 11af14de0e2daca02878b0d4b201d0dc8ddb2d4f..ef724cf08dca036fbbb8b980b09853da162e07db 100755 --- a/zh-cn/device-dev/driver/driver-platform-regulator-des.md +++ b/zh-cn/device-dev/driver/driver-platform-regulator-des.md @@ -1,107 +1,91 @@ -# REGULATOR - -- [概述](#section1_REGULATOR_des) -- [接口说明](#section2_REGULATOR_des) -- [使用指导](#section3_REGULATOR_des) - - [使用流程](#section3.1_REGULATOR_des) - - [获取REGULATOR设备句柄](#section3.2_REGULATOR_des) - - [销毁REGULATOR设备句柄](#section3.3_REGULATOR_des) - - [使能](#section3.4_REGULATOR_des) - - [禁用](#section3.5_REGULATOR_des) - - [强制禁用](#section3.6_REGULATOR_des) - - [设置REGULATOR电压输出电压范围](#section3.7_REGULATOR_des) - - [获取REGULATOR设备电压](#section3.8_REGULATOR_des) - - [设置REGULATOR设备输出电流范围](#section3.9_REGULATOR_des) - - [获取REGULATOR设备电流](#section3.10_REGULATOR_des) - - [获取REGULATOR设备状态](#section3.11_REGULATOR_des) -- [使用实例](#section4_REGULATOR_des) - -## 概述 - -- REGULATOR模块用于控制系统中某些设备的电压/电流供应。在嵌入式系统（尤其是手机）中，控制耗电量很重要，直接影响到电池的续航时间。所以，如果系统中某一个模块暂时不需要使用，就可以通过regulator关闭其电源供应；或者降低提供给该模块的电压、电流大小。 - -- REGULATOR接口定义了操作REGULATOR设备的通用方法集合，包括： - - REGULATOR设备句柄获取和销毁。 - - REGULATOR设备电压、电流的设置。 - - REGULATOR设备使能和关闭。 - - REGULATOR设备电压、电流和状态的获取 - -## 接口说明 +# REGULATOR + +- [概述](#section1) + - [功能简介](#section2) + - [基本概念](#section3) + - [运作机制](#section4) + - [约束与限制](#section5) +- [使用指导](#section6) + - [场景介绍](#section7) + - [接口说明](#section8) + - [开发步骤](#section9) + - [使用实例](#section10) + +## 概述 + +### 功能简介 + +- REGULATOR模块用于控制系统中某些设备的电压/电流供应。在嵌入式系统（尤其是手机）中，控制耗电量很重要，直接影响到电池的续航时间。所以，如果系统中某一个模块暂时不需要使用，就可以通过REGULATOR关闭其电源供应；或者降低提供给该模块的电压、电流大小。 +- REGULATOR接口定义了操作REGULATOR设备的通用方法集合，包括： + - REGULATOR设备句柄获取和销毁。 + - REGULATOR设备电压、电流的设置。 + - REGULATOR设备使能和关闭。 + - REGULATOR设备电压、电流和状态的获取。 + + +### 基本概念 + +- 校准器 + + 当输入电压和输出负载发生变化时可以通过软件调整，使其能够提供稳定的输出电压。 + +- Consumer + + 由REGULATOR供电的设备统称为Consumer， 其可分为静态和动态两类： + + * 静态：不需要改变电压电流，只需要开关电源，通常在bootloader、firmware、kernel board阶段被设置。 + * 动态：根据操作需求改变电压电流。 + +- Power Management Ic + + 电源管理芯片，内含多个电源甚至其他子系统。 + + +### 运作机制 + +在HDF框架中，REGULATOR模块接口适配模式采用统一服务模式，这需要一个设备服务来作为REGULATOR模块的管理器，统一处理外部访问，这会在配置文件中有所体现。统一服务模式适合于同类型设备对象较多的情况，如REGULATOR可能同时具备十几个控制器，采用独立服务模式需要配置更多的设备节点，且服务会占据内存资源。 + +REGULATOR模块各分层的作用为：接口层提供打开设备，写入数据，关闭设备接口的能力。核心层主要提供绑定设备、初始化设备以及释放设备的能力。适配层实现其他具体的功能。 + +![](../public_sys-resources/icon-note.gif) 说明：核心层可以调用接口层的函数，也可以通过钩子函数调用适配层函数，从而使得适配层间接的可以调用接口层函数，但是不可逆转接口层调用适配层函数。 + +图 1 统一服务模式结构图 + +![image1](figures/统一服务模式结构图.png) + +### 约束与限制 + + REGULATOR模块当前仅支持轻量和小型系统内核（LiteOS） 。 + +## 使用指导 + +### 场景介绍 + + REGULATOR主要用于： + +1. 用于控制系统中某些设备的电压/电流供应。 +2. 用于稳压电源的管理 。 + +### 接口说明 **表1** REGULATOR设备API功能介绍 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
功能分类接口名描述
REGULATOR句柄操作RegulatorOpen获取REGULATOR设备驱动句柄
RegulatorClose销毁REGULATOR设备驱动句柄
使能/禁用REGULATORRegulatorEnable使能REGULATOR
RegulatorDisable禁用REGULATOR
RegulatorForceDisable强制禁用REGULATOR
设置/获取REGULATOR输出电压RegulatorSetVoltage设置REGULATOR输出电压
RegulatorGetVoltage获取REGULATOR输出电压
设置/获取REGULATOR输出电流RegulatorSetCurrent设置REGULATOR输出电流
RegulatorGetCurrent获取REGULATOR输出电流
获取REGULATOR状态RegulatorGetStatus获取REGULATOR状态
- ->![](../public_sys-resources/icon-note.gif) **说明：** ->REGULATOR当前仅限内核态使用，不支持在用户态使用。 - -## 使用指导 - -### 使用流程 +| 接口名 | 描述 | +| --------------------- | ------------------------- | +| RegulatorOpen | 获取REGULATOR设备驱动句柄 | +| RegulatorClose | 销毁REGULATOR设备驱动句柄 | +| RegulatorEnable | 使能REGULATOR | +| RegulatorDisable | 禁用REGULATOR | +| RegulatorForceDisable | 强制禁用REGULATOR | +| RegulatorSetVoltage | 设置REGULATOR输出电压 | +| RegulatorGetVoltage | 获取REGULATOR输出电压 | +| RegulatorSetCurrent | 设置REGULATOR输出电流 | +| RegulatorGetCurrent | 获取REGULATOR输出电流 | +| RegulatorGetStatus | 获取REGULATOR状态 | + + + +### 开发步骤 在操作系统启动过程中，驱动管理模块根据配置文件加载REGULATOR驱动，REGULATOR驱动会检测REGULATOR器件并初始化驱动。 @@ -109,20 +93,19 @@ **图 1** REGULATOR设备使用流程图 - ![](figures/REGULATOR设备使用流程图.png) -### 获取REGULATOR设备句柄 +#### 获取REGULATOR设备句柄 在操作REGULATOR设备时，首先要调用RegulatorOpen获取REGULATOR设备句柄，该函数会返回指定设备名称的REGULATOR设备句柄。 -```c +``` DevHandle RegulatorOpen(const char *name); ``` **表2** RegulatorOpen参数和返回值描述 - + | 参数 | 参数描述 | | ---------- | ----------------------------- | @@ -132,7 +115,8 @@ DevHandle RegulatorOpen(const char *name); | NULL | 获取失败 | -```c + +``` /* REGULATOR设备名称 */ const char *name = "regulator_virtual_1"; DevHandle handle = NULL; @@ -144,39 +128,37 @@ if (handle == NULL) { } ``` -### 销毁REGULATOR设备句柄 +#### 销毁REGULATOR设备句柄 关闭REGULATOR设备，系统释放对应的资源。 -```c +``` void RegulatorClose(DevHandle handle); ``` **表3** RegulatorClose参数描述 - + | 参数 | 参数描述 | | ------ | ----------------- | | handle | REGULATOR设备句柄 | - -```c +``` /* 销毁REGULATOR设备句柄 */ RegulatorClose(handle); ``` -### 使能 +#### 使能 启用REGULATOR设备。 -```c +``` int32_t RegulatorEnable(DevHandle handle); ``` - **表4** RegulatorEnable参数描述 - + | 参数 | 参数描述 | | ---------- | ----------------- | @@ -185,7 +167,9 @@ int32_t RegulatorEnable(DevHandle handle); | 0 | 使能成功 | | 负数 | 使能失败 | -```c + + +``` int32_t ret; /*启用REGULATOR设备*/ @@ -195,18 +179,16 @@ if (ret != 0) { } ``` -### 禁用 +#### 禁用 禁用REGULATOR设备。 -```c +``` int32_t RegulatorDisable(DevHandle handle); ``` **表5** RegulatorDisable参数描述 - - | 参数 | 参数描述 | | ---------- | ----------------- | | handle | REGULATOR设备句柄 | @@ -214,7 +196,7 @@ int32_t RegulatorDisable(DevHandle handle); | 0 | 禁用成功 | | 负数 | 禁用失败 | -```c +``` int32_t ret; /*禁用REGULATOR设备，如果REGULATOR设备状态为常开，或存在REGULATOR设备子节点未禁用，则禁用失败*/ @@ -224,26 +206,26 @@ if (ret != 0) { } ``` -### 强制禁用 +#### 强制禁用 强制禁用REGULATOR设备。 -```c +``` int32_t RegulatorForceDisable(DevHandle handle); ``` -**表6** RegulatorForceDisable参数描述 +**表5** RegulatorDisable参数描述 - + | 参数 | 参数描述 | | ---------- | ----------------- | | handle | REGULATOR设备句柄 | | **返回值** | **返回值描述** | -| 0 | 强制禁用成功 | -| 负数 | 强制禁用失败 | +| 0 | 禁用成功 | +| 负数 | 禁用失败 | -```c +``` int32_t ret; /*强制禁用REGULATOR设备，无论REGULATOR设备的状态是常开还是子节点已使能，REGULATOR设备都会被禁用*/ @@ -252,11 +234,12 @@ if (ret != 0) { /*错误处理*/ } ``` -### 设置REGULATOR输出电压范围 + +#### 设置REGULATOR输出电压范围 设置REGULATOR电压输出电压范围。 -```c +``` int32_t RegulatorSetVoltage(DevHandle handle, uint32_t minUv, uint32_t maxUv); ``` @@ -273,7 +256,7 @@ int32_t RegulatorSetVoltage(DevHandle handle, uint32_t minUv, uint32_t maxUv); | 0 | 设置成功 | | 负数 | 设置失败 | -```c +``` int32_t ret; int32_t minUv = 0; //最小电压为0Uv int32_t maxUv = 20000; //最大电压为20000Uv @@ -284,11 +267,12 @@ if (ret != 0) { /*错误处理*/ } ``` -### 获取REGULATOR电压 + +#### 获取REGULATOR电压 获取REGULATOR电压。 -```c +``` int32_t RegulatorGetVoltage(DevHandle handle, uint32_t *voltage); ``` @@ -304,7 +288,7 @@ int32_t RegulatorGetVoltage(DevHandle handle, uint32_t *voltage); | 0 | 获取成功 | | 负数 | 获取失败 | -```c +``` int32_t ret; uint32_t voltage; @@ -315,12 +299,11 @@ if (ret != 0) { } ``` - -### 设置REGULATOR输出电流范围 +#### 设置REGULATOR输出电流范围 设置REGULATOR输出电流范围。 -```c +``` int32_t RegulatorSetCurrent(DevHandle handle, uint32_t minUa, uint32_t maxUa); ``` @@ -337,10 +320,10 @@ int32_t RegulatorSetCurrent(DevHandle handle, uint32_t minUa, uint32_t maxUa); | 0 | 设置成功 | | 负数 | 设置失败 | -```c +``` int32_t ret; int32_t minUa = 0; //最小电流为0Ua -int32_t maxUa = 200; //最大电流为200Ua +int32_t maxUa = 200; //最大电流为200Ua /*设置REGULATOR输出电流范围*/ ret = RegulatorSetCurrent(handle, minUa, maxUa); @@ -349,11 +332,11 @@ if (ret != 0) { } ``` -### 获取REGULATOR电流 +#### 获取REGULATOR电流 获取REGULATOR电流。 -```c +``` int32_t RegulatorGetCurrent(DevHandle handle, uint32_t *regCurrent); ``` @@ -369,7 +352,7 @@ int32_t RegulatorGetCurrent(DevHandle handle, uint32_t *regCurrent); | 0 | 获取成功 | | 负数 | 获取失败 | -```c +``` int32_t ret; uint32_t regCurrent; @@ -379,17 +362,18 @@ if (ret != 0) { /*错误处理*/ } ``` -### 获取REGULATOR状态 + +#### 获取REGULATOR状态 获取REGULATOR状态。 -```c +``` int32_t RegulatorGetStatus(DevHandle handle, uint32_t *status); ``` -**表11** RegulatorGetStatus参数描述 +**表10** RegulatorGetCurrent参数描述 - + | 参数 | 参数描述 | | ---------- | ----------------- | @@ -399,7 +383,7 @@ int32_t RegulatorGetStatus(DevHandle handle, uint32_t *status); | 0 | 获取成功 | | 负数 | 获取失败 | -```c +``` int32_t ret; uint32_t status; @@ -410,11 +394,13 @@ if (ret != 0) { } ``` -## 使用实例 + + +## 使用实例 REGULATOR设备完整的使用示例如下所示，首先获取REGULATOR设备句柄，然后使能，设置电压，获取电压、状态，禁用，最后销毁REGULATOR设备句柄。 -```c +``` void RegulatorTestSample(void) { int32_t ret; @@ -476,4 +462,4 @@ _ERR: /* 销毁REGULATOR设备句柄 */ RegulatorClose(handle); } -``` \ No newline at end of file +``` diff --git a/zh-cn/device-dev/driver/driver-platform-regulator-develop.md b/zh-cn/device-dev/driver/driver-platform-regulator-develop.md index 69b06d2b86712cb2c62df5075642d8bd6680c5be..d7a501f4bdabd3fadd57bc6f46303017896617d3 100755 --- a/zh-cn/device-dev/driver/driver-platform-regulator-develop.md +++ b/zh-cn/device-dev/driver/driver-platform-regulator-develop.md @@ -1,22 +1,58 @@ -# REGULATOR +# REGULATOR -- [概述](#section1_REGULATORDevelop) -- [接口说明](#section2_REGULATORDevelop) -- [开发步骤](#section3_REGULATORDevelop) -- [开发实例](#section4_REGULATORDevelop) +- [概述](#1) + - [功能简介](#2) + - [基本概念](#3) + - [运作机制](#4) + - [约束与限制](#5) +- [开发指导](#6) + - [场景介绍](#7) + - [接口说明](#8) + - [开发步骤](#9) -## 概述 +## 概述 -REGULATOR模块用于控制系统中某些设备的电压/电流供应。在HDF框架中，REGULATOR模块接口适配模式采用统一服务模式，这需要一个设备服务来作为REGULATOR模块的管理器，统一处理外部访问，这会在配置文件中有所体现。统一服务模式适合于同类型设备对象较多的情况，如REGULATOR可能同时具备十几个控制器，采用独立服务模式需要配置更多的设备节点，且服务会占据内存资源。 +### 功能简介 + +REGULATOR模块用于控制系统中某些设备的电压/电流供应。 + +### 基本概念 + +REGULATOR模块用于控制系统中某些设备的电压/电流供应。在嵌入式系统（尤其是手机）中，控制耗电量很重要，直接影响到电池的续航时间。所以，如果系统中某一个模块暂时不需要使用，就可以通过REGULATOR关闭其电源供应；或者降低提供给该模块的电压、电流大小。 + +### 运作机制 + +在HDF框架中，REGULATOR模块接口适配模式采用统一服务模式，这需要一个设备服务来作为REGULATOR模块的管理器，统一处理外部访问，这会在配置文件中有所体现。统一服务模式适合于同类型设备对象较多的情况，如REGULATOR可能同时具备十几个控制器，采用独立服务模式需要配置更多的设备节点，且服务会占据内存资源。 + +REGULATOR模块各分层的作用为：接口层提供打开设备，写入数据，关闭设备接口的能力。核心层主要提供绑定设备、初始化设备以及释放设备的能力。适配层实现其他具体的功能。 + +![](../public_sys-resources/icon-note.gif) 说明：核心层可以调用接口层的函数，也可以通过钩子函数调用适配层函数，从而使得适配层间接的可以调用接口层函数，但是不可逆转接口层调用适配层函数。 图 1 统一服务模式结构图 + ![image1](figures/统一服务模式结构图.png) -## 接口说明 -RegulatorMethod 定义： -```c + + +### 约束与限制 + + REGULATOR模块当前仅支持轻量和小型系统内核（LiteOS） 。 + +## 开发指导 + +### 场景介绍 + +REGULATOR模块用于控制系统中某些设备的电压/电流供应。 + +### 接口说明 + +通过以下RegulatorMethod中的函数调用REGULATOR驱动对应的函数。 + +RegulatorMethod定义： + +``` struct RegulatorMethod { int32_t (*open)(struct RegulatorNode *node); int32_t (*close)(struct RegulatorNode *node); @@ -32,78 +68,73 @@ struct RegulatorMethod { }; ``` -**表 1** RegulatorMethod 成员的回调函数功能说明 +**表 1** RegulatorMethod 结构体成员的回调函数功能说明 -| 成员函数 | 入参 | 返回值 | 功能 | -| ------------ | ------------------------------------------- | ------ | ---- | -| 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节点；
**minUv**：uint32_t变量，最小电压；
**maxUv**：uint32_t变量，最大电压； | HDF_STATUS相关状态 | 设置输出电压范围 | -| getVoltage | **node**：结构体指针，核心层regulator节点；
**voltage**：uint32_t指针，传出电压值； | HDF_STATUS相关状态 | 获取电压 | -| setCurrent | **node**：结构体指针，核心层regulator节点；
**minUa**：uint32_t变量，最小电流；
**maxUa**：uint32_t变量，最大电流； | HDF_STATUS相关状态 | 设置输出电流范围 | -| getCurrent | **node**：结构体指针，核心层regulator节点；
**regCurrent**：uint32_t指针，传出电流值； | HDF_STATUS相关状态 | 获取电流 | -| getStatus | **node**：结构体指针，核心层regulator节点；
**status**：uint32_t指针，传出状态值； | HDF_STATUS相关状态 | 获取设备状态 | + -## 开发步骤 - -REGULATOR模块适配的三个环节是实例化驱动入口、配置属性文件、以及实例化核心层接口函数。 - -1. **实例化驱动入口：** - - - 实例化HdfDriverEntry结构体成员。 - - 调用HDF_INIT将HdfDriverEntry实例化对象注册到HDF框架中。 - -2. **配置属性文件：** +| 成员函数 | 入参 | 返回值 | 功能 | +| ------------ | ------------------------------------------------------------ | ------------------ | ---------------- | +| 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节点； **minUv**：uint32_t变量，最小电压； **maxUv**：uint32_t变量，最大电压； | HDF_STATUS相关状态 | 设置输出电压范围 | +| getVoltage | **node**：结构体指针，核心层regulator节点； **voltage**：uint32_t指针，传出电压值； | HDF_STATUS相关状态 | 获取电压 | +| setCurrent | **node**：结构体指针，核心层regulator节点； **minUa**：uint32_t变量，最小电流； **maxUa**：uint32_t变量，最大电流； | HDF_STATUS相关状态 | 设置输出电流范围 | +| getCurrent | **node**：结构体指针，核心层regulator节点； **regCurrent**：uint32_t指针，传出电流值； | HDF_STATUS相关状态 | 获取电流 | +| getStatus | **node**：结构体指针，核心层regulator节点； **status**：uint32_t指针，传出状态值； | HDF_STATUS相关状态 | 获取设备状态 | - - 在device_info.hcs文件中添加deviceNode描述。 - - 【可选】添加regulator_config.hcs器件属性文件。 +### 开发步骤 -3. **实例化REGULATOR控制器对象：** - - - 初始化RegulatorNode成员。 - - - 实例化RegulatorNode成员RegulatorMethod。 - - >![](../public_sys-resources/icon-note.gif) **说明：** - >实例化RegulatorNode成员RegulatorMethod，其定义和成员说明见[接口说明](#section2_REGULATORDevelop)。 - -4. **驱动调试：** - - 【可选】针对新增驱动程序，建议验证驱动基本功能，例如挂载后的信息反馈，数据传输的成功与否等。 +REGULATOR模块适配包含以下四个步骤： -## 开发实例 +- 实例化驱动入口。 +- 配置属性文件。 +- 实例化核心层接口函数。 +- 驱动调试。 -下方将以regulator_virtual.c为示例，展示需要厂商提供哪些内容来完整实现设备功能。 +1. **实例化驱动入口：** -1. 驱动开发首先需要实例化驱动入口，驱动入口必须为HdfDriverEntry（在 hdf\_device\_desc.h 中定义）类型的全局变量，且moduleName要和device\_info.hcs中保持一致。HDF框架会将所有加载的驱动的HdfDriverEntry对象首地址汇总，形成一个类似数组的段地址空间，方便上层调用。 + 驱动开发首先需要实例化驱动入口，驱动入口必须为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. **配置属性文件：** - 一般在加载驱动时HDF会先调用Bind函数，再调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。 + - 在vendor/hisilicon/hispark_taurus/hdf_config/device_info/device_info.hcs文件中添加deviceNode描述。 - REGULATOR驱动入口参考 + deviceNode信息与驱动入口注册相关，器件属性值与核心层RegulatorNode成员的默认值或限制范围有密切关系。 - ```c - struct HdfDriverEntry g_regulatorDriverEntry = { - .moduleVersion = 1, - .moduleName = "virtual_regulator_driver",//【必要且与HCS文件中里面的moduleName匹配】 - .Init = VirtualRegulatorInit, - .Release = VirtualRegulatorRelease, - }; - //调用HDF_INIT将驱动入口注册到HDF框架中 - HDF_INIT(g_regulatorDriverEntry); - ``` + 由于采用了统一服务模式，device_info.hcs文件中第一个设备节点必须为REGULATOR管理器，其各项参数必须如下设置： -2. 完成驱动入口注册之后，下一步请在device\_info.hcs文件中添加deviceNode信息，并在regulator\_config.hcs中配置器件属性。deviceNode信息与驱动入口注册相关，器件属性值与核心层RegulatorNode成员的默认值或限制范围有密切关系。 + | 成员名 | 值 | + | --------------- | ------------------------------------------------------------ | + | policy | 具体配置为0，不发布服务 | + | priority | 驱动启动优先级（0-200），值越大优先级越低,，优先级相同则不保证device的加载顺序。 | + | permission | 驱动权限 | + | moduleName | 固定为 HDF_PLATFORM_REGULATOR_MANAGER | + | serviceName | 固定为HDF_PLATFORM_REGULATOR_MANAGER | + | deviceMatchAttr | 没有使用，可忽略 | - >![](W:\docs\zh-cn\device-dev\public_sys-resources\icon-note.gif) **说明：** - >如有更多个器件信息，则需要在device\_info文件增加deviceNode信息，以及在regulator\_config文件中增加对应的器件属性。 + 从第二个节点开始配置具体REGULATOR控制器信息，此节点并不表示某一路REGULATOR控制器，而是代表一个资源性质设备，用于描述一类REGULATOR控制器的信息。本例只有一个REGULATOR设备，如有多个设备，则需要在device_info文件增加deviceNode信息，以及在regulator\_config文件中增加对应的器件属性。 - - device\_info.hcs 配置参考。 + - device_info.hcs 配置参考。 - ```c - root { + ``` + root { device_info { platform :: host { hostName = "platform_host"; @@ -129,211 +160,196 @@ REGULATOR模块适配的三个环节是实例化驱动入口、配置属性文 } } } - } - ``` - - - regulator\_config.hcs 配置参考。 - - ```c - 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; - } - } - } - } - ``` - -3. 完成驱动入口注册之后，最后一步就是对核心层RegulatorNode对象的初始化，包括厂商自定义结构体（传递参数和数据），实例化RegulatorNode成员RegulatorMethod（让用户可以通过接口来调用驱动底层函数），实现HdfDriverEntry成员函数（Bind，Init，Release）。 - - - 自定义结构体参考。 - - 从驱动的角度看，RegulatorNode结构体是参数和数据的载体，HDF框架通过DeviceResourceIface将regulator\_config.hcs文件中的数值读入其中。 - - ```c - // 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 - // regulator_virtual.c 中的示例：钩子函数的填充 - static struct RegulatorMethod g_method = { - .enable = VirtualRegulatorEnable, - .disable = VirtualRegulatorDisable, - .setVoltage = VirtualRegulatorSetVoltage, - .getVoltage = VirtualRegulatorGetVoltage, - .setCurrent = VirtualRegulatorSetCurrent, - .getCurrent = VirtualRegulatorGetCurrent, - .getStatus = VirtualRegulatorGetStatus, - }; - ``` - - - Init函数参考 - - 入参： - - HdfDeviceObject 是整个驱动对外暴露的接口参数，具备 HCS 配置文件的信息。 - - 返回值： - - HDF\_STATUS相关状态 （下表为部分展示，如需使用其他状态，可见//drivers/framework/include/utils/hdf\_base.h中HDF\_STATUS 定义）。 - - **表 2** HDF\_STATUS相关状态 - - - - - - - - - - - - - - - - - - - - - - - - -

状态(值)

-

问题描述

-

HDF_ERR_INVALID_OBJECT

-

控制器对象非法

-

HDF_ERR_MALLOC_FAIL

-

内存分配失败

-

HDF_ERR_INVALID_PARAM

-

参数非法

-

HDF_ERR_IO

-

I/O 错误

-

HDF_SUCCESS

-

初始化成功

-

HDF_FAILURE

-

初始化失败

-
- 函数说明： - 初始化自定义结构体和RegulatorNode成员，并通过调用核心层RegulatorNodeAdd函数挂载Regulator控制器。 - - ```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);//【必要】实现见下 - ... - } - ... - } - - static int32_t VirtualRegulatorParseAndInit(struct HdfDeviceObject *device, const struct DeviceResourceNode *node) - { - int32_t ret; - struct RegulatorNode *regNode = NULL; - (void)device; - - regNode = (struct RegulatorNode *)OsalMemCalloc(sizeof(*regNode));//加载HCS文件 - ... - ret = VirtualRegulatorReadHcs(regNode, node);//读取HCS文件信息 - ... - regNode->priv = (void *)node; //实例化节点 - regNode->ops = &g_method; //实例化ops - - ret = RegulatorNodeAdd(regNode); //挂载节点 - ... - } - - - - Release 函数参考 - + } + ``` + + - regulator\_config.hcs 配置参考。 + + ``` + 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; + } + } + } + } + ``` + +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 + // regulator_virtual.c 中的示例：钩子函数的填充 + static struct RegulatorMethod g_method = { + .enable = VirtualRegulatorEnable, + .disable = VirtualRegulatorDisable, + .setVoltage = VirtualRegulatorSetVoltage, + .getVoltage = VirtualRegulatorGetVoltage, + .setCurrent = VirtualRegulatorSetCurrent, + .getCurrent = VirtualRegulatorGetCurrent, + .getStatus = VirtualRegulatorGetStatus, + }; + ``` + + + + - Init函数参考 + 入参： - - HdfDeviceObject是整个驱动对外暴露的接口参数，其包含了HCS配置文件中的相关配置信息。 - + + HdfDeviceObject 是整个驱动对外暴露的接口参数，具备 HCS 配置文件的信息。 + 返回值： - - 无。 - - 函数说明： - - 释放内存和删除控制器，该函数需要在驱动入口结构体中赋值给Release接口，当HDF框架调用Init函数初始化驱动失败时，可以调用Release释放驱动资源。 - + + HDF\_STATUS相关状态 （下表为部分展示，如需使用其他状态，可见//drivers/framework/include/utils/hdf\_base.h中HDF\_STATUS 定义）。 + + **表 2** HDF\_STATUS相关状态 + + | 状态(值) | 问题描述 | + | ---------------------- | -------------- | + | HDF_ERR_INVALID_OBJECT | 控制器对象非法 | + | HDF_ERR_MALLOC_FAIL | 内存分配失败 | + | HDF_ERR_INVALID_PARAM | 参数非法 | + | HDF_ERR_IO | I/O 错误 | + | HDF_SUCCESS | 初始化成功 | + | HDF_FAILURE | 初始化失败 | + + 函数说明： + + 初始化自定义结构体和RegulatorNode成员，并通过调用核心层RegulatorNodeAdd函数挂载Regulator控制器。 + + ```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);//【必要】实现见下 + ... + } + ... + } + + static int32_t VirtualRegulatorParseAndInit(struct HdfDeviceObject *device, const struct DeviceResourceNode *node) + { + int32_t ret; + struct RegulatorNode *regNode = NULL; + (void)device; + + regNode = (struct RegulatorNode *)OsalMemCalloc(sizeof(*regNode));//加载HCS文件 + ... + ret = VirtualRegulatorReadHcs(regNode, node);//读取HCS文件信息 + ... + regNode->priv = (void *)node; //实例化节点 + regNode->ops = &g_method; //实例化ops + + ret = RegulatorNodeAdd(regNode); //挂载节点 + ... + } + ``` + + - Release 函数参考 + + 入参： + + HdfDeviceObject是整个驱动对外暴露的接口参数，其包含了HCS配置文件中的相关配置信息。 + + 返回值： + + 无。 + + 函数说明: + + 释放内存和删除控制器，该函数需要在驱动入口结构体中赋值给Release接口，当HDF框架调用Init函数 初始化驱动失败时，可以调用Release释放驱动资源。 + ```c static void VirtualRegulatorRelease(struct HdfDeviceObject *device) { ... RegulatorNodeRemoveAll();//【必要】调用核心层函数，释放RegulatorNode的设备和服务 } + ``` + +4. **驱动调试：** + + 【可选】针对新增驱动程序，建议验证驱动基本功能，例如挂载后的测试用例是否成功等。 + +