OpenHarmony（鸿蒙南向）——平台驱动开发【Regulator】

OH五星上将2024-09-29 16:08

往期知识点记录：

概述

功能简介

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

运作机制

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

Regulator模块各分层的作用为：

  • 接口层：提供打开设备，操作Regulator，关闭设备的能力。

  • 核心层：主要负责服务绑定、初始化以及释放管理器，并提供添加、删除以及获取Regulator设备的能力。

  • 适配层：由驱动适配者实现与硬件相关的具体功能，如设备的初始化等。

在统一模式下，所有的控制器都被核心层统一管理，并由核心层统一发布一个服务供接口层，因此这种模式下驱动无需再为每个控制器发布服务。

图 1 Regulator统一服务模式结构图

约束与限制

Regulator模块当前仅支持小型系统。

开发指导

场景介绍

Regulator模块用于控制系统中某些设备的电压/电流供应。当驱动开发者需要将Regulator设备适配到OpenHarmony时，需要进行Regulator驱动适配，下文将介绍如何进行Regulator驱动适配。

接口说明

为了保证上层在调用Regulator接口时能够正确的操作硬件，核心层在//drivers/hdf_core/framework/support/platform/include/regulator/regulator_core.h中定义了以下钩子函数。驱动适配者需要在适配层实现这些函数的具体功能，并与这些钩子函数挂接，从而完成接口层与核心层的交互。

RegulatorMethod定义：

复制代码 
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);
};
c

表 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_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,                   // 见Init参考
        .Release = VirtualRegulatorRelease,             // 见Release参考
    };
    HDF_INIT(g_regulatorDriverEntry);                   // 调用HDF_INIT将驱动入口注册到HDF框架中
    c
  1. 配置属性文件

以Hi3516DV300开发板为例，在//vendor/hisilicon/hispark_taurus/hdf_config/device_info/device_info.hcs文件中添加deviceNode描述。

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

由于采用了统一服务模式，device_info.hcs文件中第一个设备节点必须为Regulator管理器，其各项参数必须如如表2所示：

表 2 device_info.hcs节点参数说明

成员名 值
policy 驱动服务发布的策略，Regulator管理器具体配置为1，表示驱动对内核态发布服务
priority 驱动启动优先级（0-200）。值越大优先级越低，优先级相同则不保证device的加载顺序，regulator管理器具体配置为50
permission 驱动创建设备节点权限，Regulator管理器具体配置为0664
moduleName 驱动名称，Regulator管理器固定为HDF_PLATFORM_REGULATOR_MANAGER
serviceName 驱动对外发布服务的名称，Regulator管理器固定为HDF_PLATFORM_REGULATOR_MANAGER
deviceMatchAttr 驱动私有数据匹配的关键字，Regulator管理器设置为hdf_platform_regulator_manager

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

  • device_info.hcs 配置参考

    复制代码 
          root {
          device_info {
              platform :: host {
                  hostName = "platform_host";
                  priority = 50;
                  device_regulator :: device {
                      device0 :: deviceNode {	                                 // 为每一个Regulator控制器配置一个HDF设备节点，存在多个时添加，否则不用。
                          policy = 1;	                                         // 2：用户态、内核态均可见；1：内核态可见；0：不需要发布服务。
                          priority = 50;	                                     // 驱动启动优先级
                          permission = 0644;	                                 // 驱动创建设备节点权限
                          moduleName = "HDF_PLATFORM_REGULATOR_MANAGER";                                                //【必要】用于指定驱动名称，需要与期望的驱动Entry中的moduleName一致。
                          serviceName = "HDF_PLATFORM_REGULATOR_MANAGER";		 // 【必要且唯一】驱动对外发布服务的名称
                          deviceMatchAttr = "hdf_platform_regulator_manager";  // 【必要】用于配置控制器私有数据，要与regulator_config.hcs中对应控制器保持一致，具体的控制器信息在regulator_config.hcs中。
                      }
                      device1 :: deviceNode {
                          policy = 0;
                          priority = 55;
                          permission = 0644;
                          moduleName = "linux_regulator_adapter";
                          deviceMatchAttr = "linux_regulator_adapter";
                      }
                  }
              }
          }
      }
      c

  • regulator_config_linux.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;
                  }
              }
          }
      }
      c

需要注意的是，新增regulator_config.hcs配置文件后，必须在hdf.hcs文件中将其包含，否则配置文件无法生效。

例如：本例中regulator_config.hcs所在路径为//vendor/hisilicon/hispark_taurus_linux/hdf_config/device/regulator/regulator_config_linux.hcs，则必须在产品对应的hdf.hcs中添加如下语句：

复制代码 
        #include "device/regulator/regulator_config_linux.hcs"
        c
  1. 实例化核心层接口函数

完成驱动入口注册之后，下一步就是对核心层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;       // 最大可设置输出电流
        };
        c

  • 实例化RegulatorNode成员RegulatorMethod。

    复制代码 
          // regulator_virtual.c中的示例：钩子函数的填充
      static struct RegulatorMethod g_method = {
          .enable = VirtualRegulatorEnable,
          .disable = VirtualRegulatorDisable,
          .setVoltage = VirtualRegulatorSetVoltage,
          .getVoltage = VirtualRegulatorGetVoltage,
          .setCurrent = VirtualRegulatorSetCurrent,
          .getCurrent = VirtualRegulatorGetCurrent,
          .getStatus = VirtualRegulatorGetStatus,
      };
      c

  • Init函数开发参考

入参：

HdfDeviceObject是整个驱动对外提供的接口参数，具备HCS配置文件的信息。

返回值：

HDF_STATUS相关状态（表4为部分展示，如需使用其他状态，可参考//drivers/hdf_core/interfaces/inner_api/utils/hdf_base.h中HDF_STATUS定义）。

表 3 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控制器。

复制代码 
        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);                                   // 挂载节点
            ......
        }
        c
  • Release函数开发参考

入参：

HdfDeviceObject是整个驱动对外提供的接口参数，其包含了HCS配置文件中的相关配置信息。

返回值：

无。

函数说明:

释放内存和删除控制器，该函数需要在驱动入口结构体中赋值给Release接口，当HDF框架调用Init函数初始化驱动失败时，可以调用Release释放驱动资源。

复制代码 
        static void VirtualRegulatorRelease(struct HdfDeviceObject *device)
        {
            ......
            RegulatorNodeRemoveAll(); // 【必要】调用核心层函数，释放RegulatorNode的设备和服务
        }
        c
  1. 驱动调试

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

最后

经常有很多小伙伴抱怨说：不知道学习鸿蒙开发哪些技术？不知道需要重点掌握哪些鸿蒙应用开发知识点？

为了能够帮助到大家能够有规划的学习，这里特别整理了一套纯血版鸿蒙（HarmonyOS Next）全栈开发技术的学习路线，包含了鸿蒙开发必掌握的核心知识要点，内容有（ArkTS、ArkUI开发组件、Stage模型、多端部署、分布式应用开发、WebGL、元服务、OpenHarmony多媒体技术、Napi组件、OpenHarmony内核、OpenHarmony驱动开发、系统定制移植等等）鸿蒙（HarmonyOS NEXT）技术知识点。

《鸿蒙 (Harmony OS)开发学习手册》（共计892页）:https://gitcode.com/HarmonyOS_MN/733GH/overview

如何快速入门？

1.基本概念

2.构建第一个ArkTS应用

3.......

鸿蒙开发面试真题（含参考答案）:

《OpenHarmony源码解析》:

  • 搭建开发环境
  • Windows 开发环境的搭建
  • Ubuntu 开发环境搭建
  • Linux 与 Windows 之间的文件共享
  • ......
  • 系统架构分析
  • 构建子系统
  • 启动流程
  • 子系统
  • 分布式任务调度子系统
  • 分布式通信子系统
  • 驱动子系统
  • ......

OpenHarmony 设备开发学习手册 :https://gitcode.com/HarmonyOS_MN/733GH/overview


相关推荐
哈__几秒前
React Native 鸿蒙跨平台开发：LayoutAnimation 实现鸿蒙端表单元素的动态添加动画
react native·react.js·harmonyos
亿道电子Emdoor2 分钟前
【Altium】原理图中网络标签作用范围的设置
单片机·嵌入式硬件
风行男孩9 分钟前
stm32基础学习——串口（USART）的基本使用
stm32·嵌入式硬件·学习
点灯小铭12 分钟前
基于单片机的多模式档位调节与过热保护风扇设计
单片机·嵌入式硬件·毕业设计·课程设计·期末大作业
小雨下雨的雨12 分钟前
Flutter 框架跨平台鸿蒙开发 —— ListView 控件之高效列表渲染艺术
flutter·华为·harmonyos
行者9622 分钟前
Flutter在OpenHarmony平台的文件上传组件深度实践
flutter·harmonyos·鸿蒙
行者9625 分钟前
Flutter跨平台开发适配OpenHarmony：进度条组件的深度实践
开发语言·前端·flutter·harmonyos·鸿蒙
奋斗的小青年！！28 分钟前
Flutter适配OpenHarmony：打造无缝国际化用户体验的实战指南
flutter·harmonyos·鸿蒙
奋斗的小青年！！29 分钟前
Flutter跨平台数据筛选器：深度适配OpenHarmony实战指南
flutter·harmonyos·鸿蒙
星源~34 分钟前
Zephyr - MCU 开发快速入门指南
单片机·嵌入式硬件·物联网·嵌入式开发·zephyr
热门推荐
01GitHub 镜像站点02Labelme从安装到标注：零基础完整指南03安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）04Linux下V2Ray安装配置指南05jdk21下载、安装（Windows、Linux、macOS）06Claude Code 2.1.2 升级报错？别折腾了，一行命令搞定07KGG转MP3工具|非KGM文件|解密音频08【踩坑笔记】50系显卡适配的 PyTorch 安装09Opencode CLI 安装成功,但是启动失败102025-04-03 Latex学习1——本地配置Latex + VScode环境