1# PIN 2 3## 概述 4 5### 功能简介 6 7PIN即管脚控制器，用于统一管理各SoC的管脚资源，对外提供管脚复用功能。 8 9### 基本概念 10 11PIN是一个软件层面的概念，目的是为了统一对各SoC的PIN管脚进行管理，对外提供管脚复用功能，配置PIN管脚的电气特性。 12 13- SoC（System on Chip） 14 15 系统级芯片，又称作片上系统，通常是面向特定用途将微处理器、模拟IP核、数字IP核和存储器集成在单一芯片的标准产品。 16 17- 管脚复用 18 19 由于芯片自身的引脚数量有限，无法满足日益增多的外接需求。此时可以通过软件层面的寄存器设置，让引脚工作在不同的状态，从而实现相同引脚完成不同功能的目的。 20 21### 运作机制 22 23在HDF框架中，同类型设备对象较多时（可能同时存在十几个同类型配置器），若采用独立服务模式，则需要配置更多的设备节点，且相关服务会占据更多的内存资源。相反，采用统一服务模式可以使用一个设备服务作为管理器，统一处理所有同类型对象的外部访问（这会在配置文件中有所体现），实现便捷管理和节约资源的目的。PIN模块接口适配模式采用统一服务模式（如图1所示）。 24 25在统一模式下，所有的控制器都被核心层统一管理，并由核心层统一发布一个服务供接口层，因此这种模式下驱动无需再为每个控制器发布服务。 26 27PIN模块各分层作用： 28 29- 接口层提供获取PIN管脚、设置PIN管脚推拉方式、获取PIN管脚推拉方式、设置PIN管脚推拉强度、获取PIN管脚推拉强度、设置PIN管脚功能、获取PIN管脚功能、释放PIN管脚的接口。 30- 核心层主要提供PIN管脚资源匹配，PIN管脚控制器的添加、移除以及管理的能力，通过钩子函数与适配层交互。 31- 适配层主要是将钩子函数的功能实例化，实现具体的功能。 32 33**图 1** 统一服务模式结构图 34 35 36 37### 约束与限制 38 39PIN模块目前只支持小型系统LiteOS-A内核。 40 41## 开发指导 42 43### 场景介绍 44 45PIN模块主要用于管脚资源管理。在各SoC对接HDF框架时，需要来适配PIN驱动。下文将介绍如何进行PIN驱动适配。 46 47### 接口说明 48 49为了保证上层在调用PIN接口时能够正确的操作PIN管脚，核心层在//drivers/hdf_core/framework/support/platform/include/pin/pin_core.h中定义了以下钩子函数，驱动适配者需要在适配层实现这些函数的具体功能，并与钩子函数挂接，从而完成适配层与核心层的交互。 50 51PinCntlrMethod定义： 52 53```c 54struct PinCntlrMethod { 55 int32_t (*SetPinPull)(struct PinCntlr *cntlr, uint32_t index, enum PinPullType pullType); 56 int32_t (*GetPinPull)(struct PinCntlr *cntlr, uint32_t index, enum PinPullType *pullType); 57 int32_t (*SetPinStrength)(struct PinCntlr *cntlr, uint32_t index, uint32_t strength); 58 int32_t (*GetPinStrength)(struct PinCntlr *cntlr, uint32_t index, uint32_t *strength); 59 int32_t (*SetPinFunc)(struct PinCntlr *cntlr, uint32_t index, const char *funcName); 60 int32_t (*GetPinFunc)(struct PinCntlr *cntlr, uint32_t index, const char **funcName); 61}; 62``` 63 64**表 1** PinCntlrMethod成员的钩子函数功能说明 65 66| 成员函数 | 入参 | 出参 | 返回值 | 功能 | 67| ------------ | ------------------------------------------- | ------ | ---- | ---- | 68| SetPinPull | cntlr：结构体指针，核心层PIN控制器<br>index：uint32_t类型变量，管脚索引号<br/>pullType：枚举常量，PIN管脚推拉方式 | 无 |HDF_STATUS相关状态|PIN设置管脚推拉方式| 69| GetPinPull | cntlr：结构体指针，核心层PIN控制器<br/>index：uint32_t类型变量，管脚索引号 | pullType：枚举常量指针，传出获取的PIN管脚推拉方式 | HDF_STATUS相关状态 | PIN获取管脚推拉方式 | 70| SetPinStrength | cntlr：结构体指针，核心层PIN控制器<br/>index：uint32_t类型变量，管脚索引号<br/>strength：uint32_t变量，PIN推拉强度 | 无 | HDF_STATUS相关状态 | PIN设置推拉强度 | 71| GetPinStrength | cntlr：结构体指针，核心层PIN控制器<br/>index：uint32_t类型变量，管脚索引号 | strength：uint32_t变量指针，传出获取的PIN推拉强度 | HDF_STATUS相关状态 | PIN获取推拉强度 | 72| SetPinFunc | cntlr：结构体指针，核心层PIN控制器<br/>index：uint32_t类型变量，管脚索引号<br/>funcName：char指针常量，传入PIN管脚功能 | 无 | HDF_STATUS相关状态 | PIN设置管脚功能 | 73| GetPinFunc | cntlr：结构体指针，核心层PIN控制器<br/>index：uint32_t类型变量，管脚索引号 | funcName：char双重指针常量，传出获取的PIN管脚功能 | HDF_STATUS相关状态 | PIN获取管脚功能 | 74 75### 开发步骤 76 77PIN模块适配HDF框架包含以下四个步骤： 78 79- 实例化驱动入口。 80- 配置属性文件。 81- 实例化PIN控制器对象。 82- 驱动调试。 83 84### 开发实例 85 86下方将基于Hi3516DV300开发板以//device_soc_hisilicon/common/platform/pin/pin_hi35xx.c驱动为示例，展示需要驱动适配者提供哪些内容来完整实现设备功能。 87 881. 实例化驱动入口。 89 90 驱动入口必须为HdfDriverEntry（在hdf_device_desc.h中定义）类型的全局变量，且moduleName要和device_info.hcs中保持一致。HDF框架会将所有加载的驱动的HdfDriverEntry对象首地址汇总，形成一个类似数组的段地址空间，方便上层调用。 91 一般在加载驱动时HDF会先调用Bind函数，再调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。 92 93 PIN驱动入口开发参考： 94 95 ```c 96 static struct HdfDriverEntry g_hi35xxPinDriverEntry = { 97 .moduleVersion = 1, 98 .Bind = Hi35xxPinBind, 99 .Init = Hi35xxPinInit, 100 .Release = Hi35xxPinRelease, 101 .moduleName = "hi35xx_pin_driver", // 【必要且与HCS文件中里面的moduleName匹配】 102 }; 103 HDF_INIT(g_hi35xxPinDriverEntry); // 调用HDF_INIT将驱动入口注册到HDF框架中 104 ``` 105 1062. 配置属性文件。 107 108 完成驱动入口注册之后，需要在device_info.hcs文件中添加deviceNode信息，deviceNode信息与驱动入口注册相关。本例以两个PIN控制器为例，如有多个器件信息，则需要在device_info.hcs文件增加对应的deviceNode信息。器件属性值对于驱动适配者的驱动实现以及核心层PinCntlr相关成员的默认值或限制范围有密切关系，比如控制器号，控制器管脚数量、管脚等。需要在pin_config.hcs中配置器件属性。 109 110 - device_info.hcs 配置参考： 111 112 在//vendor/hisilicon/hispark_taurus/hdf_config/device_info/device_info.hcs文件中添加deviceNode描述。 113 114 ```c 115 root { 116 device_info { 117 platform :: host { 118 hostName = "platform_host"; 119 priority = 50; 120 device_pin :: device { 121 device0 :: deviceNode { // 用于统一管理PIN并发布服务 122 policy = 2; // 2：用户态可见；1：内核态可见；0：不需要发布服务。 123 priority = 8; // 启动优先级 124 permission = 0644; // 创建设备节点权限 125 moduleName = "HDF_PLATFORM_PIN_MANAGER"; 126 serviceName = "HDF_PLATFORM_PIN_MANAGER"; 127 } 128 device1 :: deviceNode { // 为每一个PIN控制器配置一个HDF设备节点，存在多个时必须添加，否则不用。 129 policy = 0; 130 priority = 10; // 驱动启动优先级 131 permission = 0644; // 驱动创建设备节点权限 132 moduleName = "hi35xx_pin_driver"; // 【必要】用于指定驱动名称，需要与期望的驱动Entry中的moduleName一致。 133 deviceMatchAttr = "hisilicon_hi35xx_pin_0"; // 【必要】用于配置控制器私有数据，要与pin_config.hcs中对应控制器保持一致，具体的控制器信息在pin_config.hcs中。 134 } 135 device2 :: deviceNode { 136 policy = 0; 137 priority = 10; 138 permission = 0644; 139 moduleName = "hi35xx_pin_driver"; 140 deviceMatchAttr = "hisilicon_hi35xx_pin_1"; 141 } 142 ... 143 } 144 } 145 } 146 } 147 ``` 148 149 - pin_config.hcs配置参考： 150 151 在//device/soc/hisilicon/hi3516dv300/sdk_liteos/hdf_config/pin/pin_config.hcs文件配置器件属性，其中配置参数如下： 152 153 ```c 154 root { 155 platform { 156 pin_config_hi35xx { 157 template pin_controller { // 【必要】配置模板配，如果下面节点使用时继承该模板，则节点中未声明的字段会使用该模板中的默认值。 158 number = 0; // 【必要】PIN控制器号 159 regStartBasePhy = 0; // 【必要】寄存器物理基地址起始地址 160 regSize = 0; // 【必要】寄存器位宽 161 pinCount = 0; // 【必要】管脚数量 162 match_attr = ""; 163 template pin_desc { 164 pinName = ""; // 【必要】管脚名称 165 init = 0; // 【必要】寄存器默认值 166 F0 = ""; // 【必要】功能0 167 F1 = ""; // 功能1 168 F2 = ""; // 功能2 169 F3 = ""; // 功能3 170 F4 = ""; // 功能4 171 F5 = ""; // 功能5 172 } 173 } 174 controller_0 :: pin_controller { 175 number = 0; 176 regStartBasePhy = 0x10FF0000; 177 regSize = 0x48; 178 pinCount = 18; 179 match_attr = "hisilicon_hi35xx_pin_0"; 180 T1 :: pin_desc { 181 pinName = "T1"; 182 init = 0x0600; 183 F0 = "EMMC_CLK"; 184 F1 = "SFC_CLK"; 185 F2 = "SFC_BOOT_MODE"; 186 } 187 ... // 对应管脚控制器下的每个管脚，按实际添加。 188 } 189 ... // 每个管脚控制器对应一个控制器节点，如存在多个PIN控制器，请依次添加对应的控制器节点。 190 } 191 } 192 } 193 ``` 194 195 需要注意的是，新增pin_config.hcs配置文件后，必须在产品对应的hdf.hcs文件中将其包含如下语句所示，否则配置文件无法生效。 196 197 ```c 198 #include "../../../../device/soc/hisilicon/hi3516dv300/sdk_liteos/hdf_config/pin/pin_config.hcs" // 配置文件相对路径 199 ``` 200 2013. 实例化PIN控制器对象。 202 203 完成配置属性文件之后，下一步就是以核心层PinCntlr对象的初始化为核心，包括驱动适配者自定义结构体（传递参数和数据），实例化PinCntlr成员PinCntlrMethod（让用户可以通过接口来调用驱动底层函数），实现HdfDriverEntry成员函数（Bind、Init、Release）。 204 205 - 驱动适配者自定义结构体参考 206 207 从驱动的角度看，自定义结构体是参数和数据的载体，而且pin_config.hcs文件中的数值会被HDF读入并通过DeviceResourceIface来初始化结构体成员，一些重要数值也会传递给核心层对象。 208 209 在Hi35xxPinCntlrInit函数中对PinCntlr成员进行初始化操作。 210 211 ```c 212 // 驱动适配者自定义管脚描述结构体 213 struct Hi35xxPinDesc { 214 const char *pinName; // 管脚名 215 uint32_t init; // 初始化值 216 uint32_t index; // 管脚索引 217 int32_t pullType; // 管脚推拉方式 218 int32_t strength; // 管脚推拉强度 219 const char *func[HI35XX_PIN_FUNC_MAX]; // 管脚功能名字符串数组 220 }; 221 222 // 驱动适配者自定义结构体 223 struct Hi35xxPinCntlr { 224 struct PinCntlr cntlr; // 是核心层控制对象，具体描述见下面 225 struct Hi35xxPinDesc *desc; // 驱动适配者自定义管脚描述结构体指针 226 volatile unsigned char *regBase; // 寄存器映射地址 227 uint16_t number; // 管脚控制器编号 228 uint32_t regStartBasePhy; // 寄存器物理基地址起始地址 229 uint32_t regSize; // 寄存器位宽 230 uint32_t pinCount; // 管脚数量 231 }; 232 233 // PinCntlr是核心层控制器结构体，其中的成员在Init函数中会被赋值。 234 struct PinCntlr { 235 struct IDeviceIoService service; // 驱动服务 236 struct HdfDeviceObject *device; // 驱动设备对象 237 struct PinCntlrMethod *method; // 钩子函数 238 struct DListHead node; // 链表节点 239 OsalSpinlock spin; // 自旋锁 240 uint16_t number; // 管脚控制器编号 241 uint16_t pinCount; // 管脚数量 242 struct PinDesc *pins; // 管脚资源 243 void *priv; // 私有数据 244 }; 245 246 // PIN管脚控制器初始化 247 static int32_t Hi35xxPinCntlrInit(struct HdfDeviceObject *device, struct Hi35xxPinCntlr *hi35xx) 248 { 249 struct DeviceResourceIface *drsOps = NULL; 250 int32_t ret; 251 // 从hcs文件读取管脚控制器相关属性 252 drsOps = DeviceResourceGetIfaceInstance(HDF_CONFIG_SOURCE); 253 if (drsOps == NULL || drsOps->GetUint32 == NULL || drsOps->GetUint16 == NULL) { 254 HDF_LOGE("%s: invalid drs ops fail!", __func__); 255 return HDF_FAILURE; 256 } 257 ret = drsOps->GetUint16(device->property, "number", &hi35xx->number, 0); 258 if (ret != HDF_SUCCESS) { 259 HDF_LOGE("%s: read number failed", __func__); 260 return ret; 261 } 262 263 if (hi35xx->number > HI35XX_PIN_MAX_NUMBER) { 264 HDF_LOGE("%s: invalid number:%u", __func__, hi35xx->number); 265 return HDF_ERR_INVALID_PARAM; 266 } 267 ret = drsOps->GetUint32(device->property, "regStartBasePhy", &hi35xx->regStartBasePhy, 0); 268 if (ret != HDF_SUCCESS) { 269 HDF_LOGE("%s: read regStartBasePhy failed", __func__); 270 return ret; 271 } 272 ret = drsOps->GetUint32(device->property, "regSize", &hi35xx->regSize, 0); 273 if (ret != HDF_SUCCESS) { 274 HDF_LOGE("%s: read regSize failed", __func__); 275 return ret; 276 } 277 ret = drsOps->GetUint32(device->property, "pinCount", &hi35xx->pinCount, 0); 278 if (ret != HDF_SUCCESS) { 279 HDF_LOGE("%s: read pinCount failed", __func__); 280 return ret; 281 } 282 if (hi35xx->pinCount > PIN_MAX_CNT_PER_CNTLR) { 283 HDF_LOGE("%s: invalid number:%u", __func__, hi35xx->number); 284 return HDF_ERR_INVALID_PARAM; 285 } 286 // 将读取的值赋值给管脚控制器的成员，完成管脚控制器初始化。 287 hi35xx->cntlr.pinCount = hi35xx->pinCount; 288 hi35xx->cntlr.number = hi35xx->number; 289 hi35xx->regBase = OsalIoRemap(hi35xx->regStartBasePhy, hi35xx->regSize); // 管脚控制器映射 290 if (hi35xx->regBase == NULL) { 291 HDF_LOGE("%s: remap Pin base failed", __func__); 292 return HDF_ERR_IO; 293 } 294 hi35xx->desc = (struct Hi35xxPinDesc *)OsalMemCalloc(sizeof(struct Hi35xxPinDesc) * hi35xx->pinCount); 295 if (hi35xx->desc == NULL) { 296 HDF_LOGE("%s: memcalloc hi35xx desc failed", __func__); 297 return HDF_ERR_MALLOC_FAIL; 298 } 299 hi35xx->cntlr.pins = (struct PinDesc *)OsalMemCalloc(sizeof(struct PinDesc) * hi35xx->pinCount); 300 if (hi35xx->desc == NULL) { 301 HDF_LOGE("%s: memcalloc hi35xx cntlr pins failed", __func__); 302 return HDF_ERR_MALLOC_FAIL; 303 } 304 return HDF_SUCCESS; 305 } 306 ``` 307 308 - PinCntlr成员钩子函数结构体PinCntlrMethod的实例化，其他成员在Init函数中初始化。 309 310 ```c 311 static struct PinCntlrMethod g_method = { 312 .SetPinPull = Hi35xxPinSetPull, // 设置推拉方式 313 .GetPinPull = Hi35xxPinGetPull, // 获取推拉方式 314 .SetPinStrength = Hi35xxPinSetStrength, // 设置推拉强度 315 .GetPinStrength = Hi35xxPinGetStrength, // 获取推拉强度 316 .SetPinFunc = Hi35xxPinSetFunc, // 设置管脚功能 317 .GetPinFunc = Hi35xxPinGetFunc, // 获取管脚功能 318 }; 319 ``` 320 321 - Init函数开发参考 322 323 入参 324 325 HdfDeviceObject：HDF框架给每一个驱动创建的设备对象，用来保存设备相关的私有数据和服务接口。 326 327 返回值： 328 329 HDF_STATUS相关状态（下表为部分展示，如需使用其他状态，可见//drivers/hdf_core/framework/include/utils/hdf_base.h中HDF_STATUS定义）。 330 331 | **状态(值)** | **问题描述** | 332 | ---------------------- | -------------- | 333 | HDF_ERR_INVALID_OBJECT | 控制器对象非法 | 334 | HDF_ERR_MALLOC_FAIL | 内存分配失败 | 335 | HDF_ERR_INVALID_PARAM | 参数非法 | 336 | HDF_ERR_IO | I/O 错误 | 337 | HDF_SUCCESS | 初始化成功 | 338 | HDF_FAILURE | 初始化失败 | 339 340 函数说明： 341 342 初始化自定义结构体对象和PinCntlr成员，并通过调用核心层PinCntlrAdd函数挂载PIN控制器。 343 344 ```c 345 static int32_t Hi35xxPinReadFunc(struct Hi35xxPinDesc *desc, const struct DeviceResourceNode *node, struct DeviceResourceIface *drsOps) 346 { 347 int32_t ret; 348 uint32_t funcNum = 0; 349 // 从hcs中读取管脚控制器子节点管脚功能名 350 ret = drsOps->GetString(node, "F0", &desc->func[funcNum], "NULL"); 351 if (ret != HDF_SUCCESS) { 352 HDF_LOGE("%s: read F0 failed", __func__); 353 return ret; 354 } 355 356 funcNum++; 357 ret = drsOps->GetString(node, "F1", &desc->func[funcNum], "NULL"); 358 if (ret != HDF_SUCCESS) { 359 HDF_LOGE("%s: read F1 failed", __func__); 360 return ret; 361 } 362 363 funcNum++; 364 ... 365 return HDF_SUCCESS; 366 } 367 368 static int32_t Hi35xxPinParsePinNode(const struct DeviceResourceNode *node, struct Hi35xxPinCntlr *hi35xx, int32_t index) 369 { 370 int32_t ret; 371 struct DeviceResourceIface *drsOps = NULL; 372 // 从hcs中读取管脚控制器子节点管脚相关属性 373 drsOps = DeviceResourceGetIfaceInstance(HDF_CONFIG_SOURCE); 374 if (drsOps == NULL || drsOps->GetUint32 == NULL || drsOps->GetString == NULL) { 375 HDF_LOGE("%s: invalid drs ops fail!", __func__); 376 return HDF_FAILURE; 377 } 378 ret = drsOps->GetString(node, "pinName", &hi35xx->desc[index].pinName, "NULL"); 379 if (ret != HDF_SUCCESS) { 380 HDF_LOGE("%s: read pinName failed", __func__); 381 return ret; 382 } 383 ... 384 ret = Hi35xxPinReadFunc(&hi35xx->desc[index], node, drsOps); 385 if (ret != HDF_SUCCESS) { 386 HDF_LOGE("%s:Pin read Func failed", __func__); 387 return ret; 388 } 389 hi35xx->cntlr.pins[index].pinName = hi35xx->desc[index].pinName; 390 hi35xx->cntlr.pins[index].priv = (void *)node; 391 ... 392 return HDF_SUCCESS; 393 } 394 395 static int32_t Hi35xxPinInit(struct HdfDeviceObject *device) 396 { 397 ... 398 struct Hi35xxPinCntlr *hi35xx = NULL; 399 ... 400 ret = Hi35xxPinCntlrInit(device, hi35xx); // 管脚控制器初始化 401 ... 402 DEV_RES_NODE_FOR_EACH_CHILD_NODE(device->property, childNode) { // 遍历管脚控制器的每个子节点 403 ret = Hi35xxPinParsePinNode(childNode, hi35xx, index); // 解析子节点 404 ... 405 } 406 407 hi35xx->cntlr.method = &g_method; // PinCntlrMethod实例化实例化对象的挂载 408 ret = PinCntlrAdd(&hi35xx->cntlr); // 添加控制器 409 if (ret != HDF_SUCCESS) { 410 HDF_LOGE("%s: add Pin cntlr: failed", __func__); 411 ret = HDF_FAILURE; 412 } 413 return HDF_SUCCESS; 414 } 415 ``` 416 417 - Release函数开发参考 418 419 入参： 420 421 HdfDeviceObject：HDF框架给每一个驱动创建的设备对象，用来保存设备相关的私有数据和服务接口。 422 423 返回值： 424 425 无。 426 427 函数说明： 428 429 释放内存和删除控制器，该函数需要在驱动入口结构体中赋值给Release接口。当HDF框架调用Init函数初始化驱动失败时，可以调用Release释放驱动资源。 430 431 ```c 432 static void Hi35xxPinRelease(struct HdfDeviceObject *device) 433 { 434 int32_t ret; 435 uint16_t number; 436 struct PinCntlr *cntlr = NULL; 437 struct Hi35xxPinCntlr *hi35xx = NULL; 438 struct DeviceResourceIface *drsOps = NULL; 439 440 if (device == NULL || device->property == NULL) { 441 HDF_LOGE("%s: device or property is null", __func__); 442 return; 443 } 444 // 从hcs文件中读取管脚控制器编号 445 drsOps = DeviceResourceGetIfaceInstance(HDF_CONFIG_SOURCE); 446 if (drsOps == NULL || drsOps->GetUint32 == NULL || drsOps->GetString == NULL) { 447 HDF_LOGE("%s: invalid drs ops", __func__); 448 return; 449 } 450 ret = drsOps->GetUint16(device->property, "number", &number, 0); 451 if (ret != HDF_SUCCESS) { 452 HDF_LOGE("%s: read cntlr number failed", __func__); 453 return; 454 } 455 456 cntlr = PinCntlrGetByNumber(number); // 通过管脚控制器编号获取管脚控制器 457 PinCntlrRemove(cntlr); 458 hi35xx = (struct Hi35xxPinCntlr *)cntlr; 459 if (hi35xx != NULL) { 460 if (hi35xx->regBase != NULL) { 461 OsalIoUnmap((void *)hi35xx->regBase); 462 } 463 OsalMemFree(hi35xx); 464 } 465 } 466 ``` 467 4684. 驱动调试。 469 470 【可选】针对新增驱动程序，建议验证驱动基本功能，例如挂载后的信息反馈，数据传输的成功与否等。