1# PWM 2 3- [概述](#1) 4- [开发步骤](#2) 5- [开发实例](#3) 6 7## 概述 <a name="1"></a> 8 9PWM（Pulse Width Modulator）即脉冲宽度调节器，在HDF框架中，PWM的接口适配模式采用独立服务模式，在这种模式下，每一个设备对象会独立发布一个设备服务来处理外部访问，设备管理器收到API的访问请求之后，通过提取该请求的参数，达到调用实际设备对象的相应内部方法的目的。 10 11独立服务模式可以直接借助HDFDeviceManager的服务管理能力，但需要为每个设备单独配置设备节点，增加内存占用。 12 13图 1 独立服务模式结构图 14 15 16## 开发步骤 <a name="2"></a> 17 18PWM模块适配HDF框架的三个环节是配置属性文件，实例化驱动入口，以及填充核心层接口函数。 19 201. **实例化驱动入口：** 21 - 实例化HdfDriverEntry结构体成员。 22 - 调用HDF_INIT将HdfDriverEntry实例化对象注册到HDF框架中。 23 242. **配置属性文件：** 25 26 - 在device_info.hcs文件中添加deviceNode描述。 27 - 【可选】添加pwm_config.hcs器件属性文件。 28 293. **实例化PWM控制器对象：** 30 31 - 初始化PwmDev成员。 32 - 实例化PwmDev成员PwmMethod，其定义和成员说明见下 33 344. **驱动调试：** 35 - 【可选】针对新增驱动程序，建议验证驱动基本功能，例如PWM控制状态，中断响应情况等。 36 37>  **说明：** 38> 39> PwmMethod定义 40> ```c 41> struct PwmMethod { 42> int32_t (*setConfig)(struct PwmDev *pwm, struct PwmConfig *config); 43> int32_t (*open)(struct PwmDev *pwm); 44> int32_t (*close)(struct PwmDev *pwm); 45> }; 46> ``` 47> 48> 表1 PwmMethod结构体成员的回调函数功能说明 49> |成员函数|入参|返回值|功能| 50> |-|-|-|-| 51> |setConfig|**pwm**: 结构体指针，核心层PWM控制器；<br />**config**: 结构体指针，属性传入值;|HDF_STATUS相关状态|配置属性| 52> |open |**pwm**: 结构体指针，核心层PWM控制器；|HDF_STATUS相关状态|打开设备| 53> |close|**pwm**: 结构体指针，核心层PWM控制器；|HDF_STATUS相关状态|关闭设备| 54 55## 开发实例 <a name="3"></a> 56 57下方将以pwm_hi35xx.c为示例，展示需要厂商提供哪些内容来完整实现设备功能。 58 591. 驱动开发首先需要实例化驱动入口，驱动入口必须为HdfDriverEntry（在 hdf_device_desc.h 中定义）类型的全局变量，且moduleName要和device_info.hcs中保持一致。HDF框架会将所有加载的驱动的HdfDriverEntry对象首地址汇总，形成一个类似数组的段地址空间，方便上层调用。 60 61 一般在加载驱动时HDF会先调用Bind函数，再调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。 62 63- PWM驱动入口参考 64 65 ```c 66 struct HdfDriverEntry g_hdfPwm = { 67 .moduleVersion = 1, 68 .moduleName = "HDF_PLATFORM_PWM",//【必要 且与 HCS文件中里面的moduleName匹配】 69 .Bind = HdfPwmBind, 70 .Init = HdfPwmInit, 71 .Release = HdfPwmRelease, 72 }; 73 //调用HDF_INIT将驱动入口注册到HDF框架中 74 HDF_INIT(g_hdfPwm); 75 ``` 76 772. 完成驱动入口注册之后，下一步请在device_info.hcs文件中添加deviceNode信息，并在 pwm_config.hcs 中配置器件属性。deviceNode信息与驱动入口注册相关，器件属性值与核心层PwmDev成员的默认值或限制范围有密切关系。 78 79 **如有更多个器件信息，则需要在device_info文件增加deviceNode信息，以及在pwm_config文件中增加对应的器件属性**。 80 81- device_info.hcs 配置参考 82 83 ```c 84 root { 85 device_info { 86 platform :: host { 87 hostName = "platform_host"; 88 priority = 50; 89 device_pwm :: device {//为每一个 pwm 控制器配置一个HDF设备节点，存在多个时【必须】添加，否则不用 90 device0 :: deviceNode { 91 policy = 1; // 等于1，向内核态发布服务 92 priority = 80; // 驱动启动优先级 93 permission = 0644;// 驱动创建设备节点权限 94 moduleName = "HDF_PLATFORM_PWM"; //【必要】用于指定驱动名称，需要与期望的驱动Entry中的moduleName一致； 95 serviceName = "HDF_PLATFORM_PWM_0";//【必要且唯一】驱动对外发布服务的名称 96 deviceMatchAttr = "hisilicon_hi35xx_pwm_0";//【必要】用于配置控制器私有数据，要与 pwm_config.hcs 中对应 97 // 控制器保持一致，具体的控制器信息在 pwm_config.hcs 中 98 } 99 device1 :: deviceNode { 100 policy = 1; 101 priority = 80; 102 permission = 0644; 103 moduleName = "HDF_PLATFORM_PWM"; 104 serviceName = "HDF_PLATFORM_PWM_1"; 105 deviceMatchAttr = "hisilicon_hi35xx_pwm_1"; 106 } 107 } 108 } 109 } 110 } 111 ``` 112 113- pwm_config.hcs 配置参考 114 115 ```c 116 root { 117 platform { 118 pwm_config { 119 template pwm_device { //【必要】模板配置，继承该模板的节点如果使用模板中的默认值，则节点字段可以缺省 120 serviceName = ""; 121 match_attr = ""; 122 num = 0; //【必要】设备号 123 base = 0x12070000; //【必要】地址映射需要 124 } 125 device_0x12070000 :: pwm_device { 126 match_attr = "hisilicon_hi35xx_pwm_0";//【必要】需要和device_info.hcs中的deviceMatchAttr值一致 127 } 128 device_0x12070020 :: pwm_device { //存在多个设备时【必须】添加，否则不用 129 match_attr = "hisilicon_hi35xx_pwm_1"; 130 num = 1; 131 base = 0x12070020; //【必要】地址映射需要 132 } 133 } 134 } 135 } 136 ``` 137 1383. 完成驱动入口注册之后，最后一步就是以核心层PwmDev对象的初始化为核心，包括厂商自定义结构体（传递参数和数据），实例化PwmDev成员PwmMethod（让用户可以通过接口来调用驱动底层函数），实现HdfDriverEntry成员函数（Bind，Init，Release） 139 140- 自定义结构体参考 141 142 > 从驱动的角度看，自定义结构体是参数和数据的载体，而且pwm_config.hcs文件中的数值会被HDF读入通过DeviceResourceIface来初始化结构体成员，一些重要数值也会传递给核心层对象，例如设备号等。 143 144 ```c 145 struct HiPwm { 146 struct PwmDev dev; //【必要】 核心层结构体 147 volatile unsigned char *base; 148 struct HiPwmRegs *reg; // 设备属性结构体，可自定义 149 bool supportPolarity; 150 }; 151 152 // PwmDev是核心层控制器结构体，其中的成员在Init函数中会被赋值 153 struct PwmDev { 154 struct IDeviceIoService service; 155 struct HdfDeviceObject *device; 156 struct PwmConfig cfg; //属性结构体，相关定义见下 157 struct PwmMethod *method; //钩子函数模板 158 bool busy; 159 uint32_t num; //设备号 160 OsalSpinlock lock; 161 void *priv; //私有数据，一般存储自定义结构体首地址，方便调用 162 }; 163 struct PwmConfig { 164 uint32_t duty; // 占空时间 nanoseconds 165 uint32_t period; // pwm 周期 nanoseconds 166 uint32_t number; // pwm 连续个数 167 uint8_t polarity; // Polarity 168 // ------------------- | -------------- 169 // PWM_NORMAL_POLARITY | Normal polarity 170 // PWM_INVERTED_POLARITY | Inverted polarity 171 // 172 uint8_t status; // 运行状态 173 // ------------------ | ----------------- 174 // PWM_DISABLE_STATUS | Disabled 175 // PWM_ENABLE_STATUS | Enabled 176 }; 177 ``` 178 179 180- **【重要】** PwmDev成员回调函数结构体PwmMethod的实例化，其他成员在Init函数中初始化 181 182 ```c 183 // pwm_hi35xx.c 中的示例：钩子函数的填充 184 struct PwmMethod g_pwmOps = { 185 .setConfig = HiPwmSetConfig,//配置属性 186 }; 187 ``` 188 189- **Init函数参考** 190 191 > **入参：** 192 > HdfDeviceObject 是整个驱动对外暴露的接口参数，具备 HCS 配置文件的信息 193 > 194 > **返回值：** 195 > HDF_STATUS相关状态 （下表为部分展示，如需使用其他状态，可见//drivers/framework/include/utils/hdf_base.h中HDF_STATUS 定义） 196 > 197 > |状态(值)|问题描述| 198 > |:-|:-:| 199 > |HDF_ERR_INVALID_OBJECT|控制器对象非法| 200 > |HDF_ERR_MALLOC_FAIL |内存分配失败| 201 > |HDF_ERR_INVALID_PARAM |参数非法| 202 > |HDF_ERR_IO |I/O 错误| 203 > |HDF_SUCCESS |初始化成功| 204 > |HDF_FAILURE |初始化失败| 205 > 206 > **函数说明：** 207 > 初始化自定义结构体对象，初始化PwmDev成员，调用核心层PwmDeviceAdd函数。 208 209 ```c 210 //此处bind函数为空函数，可与init函数结合，也可根据厂商需要实现相关操作 211 static int32_t HdfPwmBind(struct HdfDeviceObject *obj) 212 { 213 (void)obj; 214 return HDF_SUCCESS; 215 } 216 //挂载init的 217 static int32_t HdfPwmInit(struct HdfDeviceObject *obj) 218 { 219 int ret; 220 struct HiPwm *hp = NULL; 221 ... 222 hp = (struct HiPwm *)OsalMemCalloc(sizeof(*hp)); 223 ... 224 ret = HiPwmProbe(hp, obj); //【必要】实现见下 225 ... 226 return ret; 227 } 228 229 static int32_t HiPwmProbe(struct HiPwm *hp, struct HdfDeviceObject *obj) 230 { 231 uint32_t tmp; 232 struct DeviceResourceIface *iface = NULL; 233 234 iface = DeviceResourceGetIfaceInstance(HDF_CONFIG_SOURCE);//初始化自定义结构体HiPwm 235 ... 236 237 hp->reg = (struct HiPwmRegs *)hp->base; //初始化自定义结构体HiPwm 238 hp->supportPolarity = false; //初始化自定义结构体HiPwm 239 hp->dev.method = &g_pwmOps; //PwmMethod的实例化对象的挂载 240 hp->dev.cfg.duty = PWM_DEFAULT_DUTY_CYCLE; //初始化PwmDev 241 hp->dev.cfg.period = PWM_DEFAULT_PERIOD; //初始化PwmDev 242 hp->dev.cfg.polarity = PWM_DEFAULT_POLARITY; //初始化PwmDev 243 hp->dev.cfg.status = PWM_DISABLE_STATUS; //初始化PwmDev 244 hp->dev.cfg.number = 0; //初始化PwmDev 245 hp->dev.busy = false; //初始化PwmDev 246 if (PwmDeviceAdd(obj, &(hp->dev)) != HDF_SUCCESS) {//【重要】调用核心层函数，初始化hp->dev 的设备和服务 247 OsalIoUnmap((void *)hp->base); 248 return HDF_FAILURE; 249 } 250 return HDF_SUCCESS; 251 } 252 ``` 253 254- **Release 函数参考** 255 256 > **入参：** 257 > HdfDeviceObject 是整个驱动对外暴露的接口参数，具备 HCS 配置文件的信息 258 > 259 > **返回值：** 260 > 无 261 > 262 > **函数说明：** 263 > 释放内存和删除控制器，该函数需要在驱动入口结构体中赋值给 Release 接口， 当HDF框架调用Init函数初始化驱动失败时，可以调用 Release 释放驱动资源。 264 265 ```c 266 static void HdfPwmRelease(struct HdfDeviceObject *obj) 267 { 268 struct HiPwm *hp = NULL; 269 ... 270 hp = (struct HiPwm *)obj->service;//这里有HdfDeviceObject到HiPwm的强制转化 271 ... 272 PwmDeviceRemove(obj, &(hp->dev));//【必要】调用核心层函数，释放PwmDev的设备和服务,这里有HiPwm到PwmDev的强制转化 273 HiPwmRemove(hp); //释放HiPwm 274 } 275 ```
