1# PIN 2 3## 概述<a name="section1"></a> 4 5### 功能简介<a name="section2"></a> 6 7PIN即管脚控制器，用于统一管理各SoC的管脚资源，对外提供管脚复用功能：包括管脚推拉方式、管脚推拉强度以及管脚功能。 8 9PIN接口定义了操作PIN管脚的通用方法集合，包括： 10 11- 获取/释放管脚描述句柄：传入管脚名与链表中每个控制器下管脚名进行匹配，匹配则会获取一个管脚描述句柄，操作完PIN管脚后释放该管脚描述句柄。 12 13- 设置/获取管脚推拉方式：推拉方式可以是上拉、下拉以及悬空。 14 15- 设置/获取管脚推拉强度：用户可根据实际设置管脚推拉强度大小。 16 17- 设置/获取管脚功能：通过管脚功能名设置/获取管脚功能，实现管脚复用。 18 19### 基本概念<a name="section3"></a> 20 21PIN是一个软件层面的概念，目的是为了统一各SoC的PIN管脚管理，对外提供管脚复用功能，配置PIN管脚的电气特性。 22 23- SoC（System on Chip） 24 25 系统级芯片，也有称作片上系统，通常是面向特定用途将微处理器、模拟IP核、数字IP核和存储器集成在单一芯片的标准产品。 26 27- 管脚复用 28 29 由于芯片自身的引脚数量有限，无法满足日益增多的外接需求。此时可以通过软件层面的寄存器设置，让引脚工作在不同的状态，从而实现相同引脚完成不同功能的目的。 30 31### 运作机制<a name="section4"></a> 32 33在HDF框架中，同类型设备对象较多时（可能同时存在十几个同类型配置器），若采用独立服务模式，则需要配置更多的设备节点，且相关服务会占据更多的内存资源。相反，采用统一服务模式可以使用一个设备服务作为管理器，统一处理所有同类型对象的外部访问（这会在配置文件中有所体现），实现便捷管理和节约资源的目的。PIN模块接口适配模式采用统一服务模式。 34 35在统一模式下，所有的控制器都被核心层统一管理，并由核心层统一发布一个服务供接口层，因此这种模式下驱动无需再为每个控制器发布服务。 36 37PIN模块各分层作用： 38 39- 接口层提供获取PIN管脚、设置PIN管脚推拉方式、获取PIN管脚推拉方式、设置PIN管脚推拉强度、获取PIN管脚推拉强度、设置PIN管脚功能、获取PIN管脚功能、释放PIN管脚的接口。 40 41- 核心层主要提供PIN管脚资源匹配，PIN管脚控制器的添加、移除以及管理的能力，通过钩子函数与适配层交互。 42 43- 适配层主要是将钩子函数的功能实例化，实现具体的功能。 44 45**图 1** PIN统一服务模式 46 47 48 49### 约束与限制<a name="section5"></a> 50 51PIN模块目前只支持小型系统LiteOS-A内核。 52 53## 使用指导<a name="section6"></a> 54 55### 场景介绍<a name="section7"></a> 56 57PIN模块仅是一个软件层面的概念，主要工作是管脚资源管理。使用复用管脚时，通过设置管脚功能、设置管脚推拉方式、设置管脚推拉强度来适配指定场景的需求。 58 59### 接口说明<a name="section8"></a> 60 61PIN模块提供的主要接口如表1所示，具体API[详见](https://gitee.com/openharmony/drivers_hdf_core/blob/master/framework/include/platform/pin_if.h)。 62 63**表 1** PIN驱动API接口功能介绍 64<a name="table1"></a> 65 66| **接口名** | **描述** | 67| ------------------------------------------------------------ | ---------------- | 68| DevHandle PinGet(const char \*pinName) | 获取管脚描述句柄 | 69| void PinPut(DevHandle handle) | 释放管脚描述句柄 | 70| int32_t PinSetPull(DevHandle handle, enum PinPullType pullType) | 设置管脚推拉方式 | 71| int32_t PinGetPull(DevHandle handle, enum PinPullType \*pullType) | 获取管脚推拉方式 | 72| int32_t PinSetStrength(DevHandle handle, uint32_t strength) | 设置管脚推拉强度 | 73| int32_t PinGetStrength(DevHandle handle, uint32_t \*strength) | 获取管脚推拉强度 | 74| int32_t PinSetFunc(DevHandle handle, const char \*funcName) | 设置管脚功能 | 75| int32_t PinGetFunc(DevHandle handle, const char \**funcName) | 获取管脚功能 | 76 77> **说明：**<br> 78>本文涉及PIN的所有接口，支持内核态及用户态使用。 79 80### 开发步骤<a name="section9"></a> 81 82使用PIN设备的一般流程如图2所示。 83 84**图 2** PIN使用流程图<a name="fig2"></a> 85 86 87#### 获取PIN管脚描述句柄 88 89在使用PIN进行管脚操作时，首先要调用PinGet获取管脚描述句柄，该函数会返回匹配传入管脚名的管脚描述句柄。 90 91```c 92DevHandle PinGet(const char *pinName); 93``` 94 95**表 2** PinGet参数和描述 96 97<a name="table2"></a> 98 99| 参数 | 描述 | 100| ---------- | ----------------------- | 101| pinName | 字符指针类型，管脚名 | 102| **返回值** | **描述** | 103| NULL | 获取PIN管脚描述句柄失败 | 104| handle | PIN管脚描述句柄 | 105 106假设PIN需要操作的管脚名为P18，获取其管脚描述句柄的示例如下： 107 108```c 109DevHandle handle = NULL; // PIN管脚描述句柄 110 111char pinName = "P18"; // PIN管脚名 112handle = PinGet(pinName); 113if (handle == NULL) { 114 HDF_LOGE("PinGet: get handle failed!\n"); 115 return HDF_FAILURE; 116} 117``` 118 119#### PIN设置管脚推拉方式 120 121PIN设置管脚推拉方式的函数如下所示： 122 123```c 124int32_t PinSetPull(DevHandle handle, enum PinPullType pullType); 125``` 126 127**表 3** 参数和描述 128 129<a name="table3"></a> 130 131| 参数 | 描述 | 132| ---------- | ----------------------- | 133| handle | DevHandle类型，PIN管脚描述句柄 | 134| pullType | 枚举类型，PIN管脚推拉方式 | 135| **返回值** | **描述** | 136| HDF_SUCCESS | PIN设置管脚推拉方式成功 | 137| 负数 | PIN设置管脚推拉方式失败 | 138 139假设PIN要设置的管脚推拉方式为上拉，其实例如下： 140 141```c 142int32_t ret; 143enum PinPullType pullTypeNum; 144 145// PIN设置管脚推拉方式 146pullTypeNum = 1; 147ret = PinSetPull(handle, pullTypeNum); 148if (ret != HDF_SUCCESS) { 149 HDF_LOGE("PinSetPull: failed, ret %d\n", ret); 150 return ret; 151} 152``` 153 154#### PIN获取管脚推拉方式 155 156PIN获取管脚推拉方式的函数如下所示： 157 158```c 159int32_t PinGetPull(DevHandle handle, enum PinPullType *pullType); 160``` 161 162**表 4** PinGetPull参数和描述 163 164<a name="table4"></a> 165 166| 参数 | 描述 | 167| ---------- | ------------------------- | 168| handle | DevHandle类型，PIN管脚描述句柄 | 169| pullType | 枚举类型指针，接收PIN管脚推拉方式 | 170| **返回值** | **描述** | 171| HDF_SUCCESS | PIN获取管脚推拉方式成功 | 172| 负数 | PIN获取管脚推拉方式失败 | 173 174PIN获取管脚推拉方式的实例如下： 175 176```c 177int32_t ret; 178enum PinPullType pullTypeNum; 179 180// PIN获取管脚推拉方式 181ret = PinGetPull(handle, &pullTypeNum); 182if (ret != HDF_SUCCESS) { 183 HDF_LOGE("PinGetPull: failed, ret %d\n", ret); 184 return ret; 185} 186``` 187 188#### PIN设置管脚推拉强度 189 190PIN设置管脚推拉强度函数如下所示： 191 192```c 193int32_t PinSetStrength(DevHandle handle, uint32_t strength); 194``` 195 196**表 5** PinSetStrength参数和描述 197 198<a name="table5"></a> 199 200| 参数 | 描述 | 201| ---------- | ----------------------- | 202| handle | DevHandle类型，管脚描述句柄 | 203| strength | uint32_t类型，PIN管脚推拉强度 | 204| **返回值** | **描述** | 205| HDF_SUCCESS | PIN设置管脚推拉强度成功 | 206| 负数 | PIN设置管脚推拉强度失败 | 207 208假设PIN要设置的管脚推拉强度为2，其实例如下： 209 210```c 211int32_t ret; 212uint32_t strengthNum; 213// PIN设置管脚推拉强度 214strengthNum = 2; 215ret = PinSetStrength(handle, strengthNum); 216if (ret != HDF_SUCCESS) { 217 HDF_LOGE("PinSetStrength: failed, ret %d\n", ret); 218 return ret; 219} 220``` 221 222#### PIN获取管脚推拉强度 223 224PIN设置管脚推拉强度后，可以通过PIN获取管脚推拉强度接口来查看PIN管脚推拉强度，PIN获取管脚推拉强度的函数如下所示： 225 226```c 227int32_t PinGetStrength(DevHandle handle, uint32_t *strength); 228``` 229 230**表 6** PinGetStrength参数和描述 231 232<a name="table6"></a> 233 234| 参数 | 描述 | 235| ---------- | ------------------------- | 236| handle | DevHandle类型，管脚描述句柄 | 237| strength | uint32_t类型指针，接收PIN管脚推拉强度 238| **返回值** | **描述** | 239| HDF_SUCCESS | PIN获取管脚推拉强度成功 | 240| 负数 | PIN获取管脚推拉强度失败 | 241 242PIN获取管脚推拉强度的实例如下： 243 244```c 245int32_t ret; 246uint32_t strengthNum; 247 248// PIN获取管脚推拉强度 249ret = PinGetStrength(handle, &strengthNum); 250if (ret != HDF_SUCCESS) { 251 HDF_LOGE("PinGetStrength: failed, ret %d\n", ret); 252 return ret; 253} 254``` 255 256#### PIN设置管脚功能 257 258管脚功能特指的是管脚复用的功能，每个管脚功能都不相同，管脚功能名详细可以参考//device/soc/hisilicon/hi3516dv300/sdk_liteos/hdf_config/pin/pin_config.hcs。 259 260PIN设置管脚功能函数如下所示： 261 262```c 263int32_t PinSetFunc(DevHandle handle, const char *funcName); 264``` 265 266**表 7** PinSetFunc参数和描述 267 268<a name="table7"></a> 269 270| 参数 | 描述 | 271| ---------- | ------------------- | 272| handle | DevHandle类型，管脚描述句柄 | 273| funcName | 字符指针类型，PIN管脚功能名 | 274| **返回值** | **描述** | 275| HDF_SUCCESS | PIN设置管脚功能成功 | 276| 负数 | PIN设置管脚功能失败 | 277 278假设PIN需要设置的管脚功能为LSADC_CH1（ADC通道1），其实例如下： 279 280```c 281int32_t ret; 282char funcName = "LSADC_CH1"; 283 284// PIN设置管脚功能 285ret = PinSetFunc(handle, funcName); 286if (ret != HDF_SUCCESS) { 287 HDF_LOGE("PinSetFunc: failed, ret %d\n", ret); 288 return ret; 289} 290``` 291 292#### PIN获取管脚功能 293 294PIN设置管脚功能后，可以通过PIN获取管脚功能接口来查看PIN管脚功能，PIN获取管脚功能的函数如下所示： 295 296```c 297int32_t PinGetFunc(DevHandle handle, const char **funcName); 298``` 299 300**表 8** PinGetFunc参数和描述 301 302<a name="table8"></a> 303 304| 参数 | 描述 | 305| ---------- | --------------------- | 306| handle | DevHandle类型，管脚描述句柄 | 307| funcName | 字符类型双指针，接收PIN管脚功能 | 308| **返回值** | **描述** | 309| HDF_SUCCESS | PIN获取管脚功能成功 | 310| 负数 | PIN获取管脚功能失败 | 311 312PIN获取管脚功能的实例如下： 313 314```c 315int32_t ret; 316char *funcName = NULL; 317 318// PIN获取管脚功能 319ret = PinGetFunc(handle, &funcName); 320if (ret != HDF_SUCCESS) { 321 HDF_LOGE("PinGetFunc: failed, ret %d\n", ret); 322 return ret; 323} 324``` 325 326#### 释放PIN管脚描述句柄 327 328PIN不再进行任何操作后，需要释放PIN管脚描述管脚句柄，函数如下所示： 329 330```c 331void PinPut(DevHandle handle); 332``` 333 334**表 9** PinPut参数和描述 335 336<a name="table9"></a> 337 338| 参数 | 描述 | 339| ---------- | -------------- | 340| handle | DevHandle类型，管脚描述句柄 | 341| **返回值** | **描述** | 342| NA | 无返回值 | 343 344PIN销毁管脚描述句柄实例如下： 345 346```c 347PinPut(handle); 348``` 349 350## 使用实例<a name="section10"></a> 351 352下面将基于Hi3516DV300开发板展示使用PIN设置管脚相关属性完整操作，步骤主要如下： 353 3541. 传入要设置的管脚名，获取PIN管脚描述句柄。 355 3562. 通过PIN管脚描述句柄以及推拉方式pullTypeNum设置管脚推拉方式，如果操作失败则释放PIN管脚描述句柄。 357 3583. 通过PIN管脚描述句柄，并用pullTypeNum承接获取的管脚推拉方式，如果操作失败则释放PIN管脚描述句柄。 359 3604. 通过PIN管脚描述句柄以及推拉强度strengthNum设置管脚推拉强度，如果操作失败则释放PIN管脚描述句柄。 361 3625. 通过PIN管脚描述句柄，并用strengthNum承接获取的管脚推拉强度，如果操作失败则释放PIN管脚描述句柄。 363 3645. 通过PIN管脚描述句柄以及管脚功能名funName设置管脚功能，如果操作失败则释放PIN管脚描述句柄。 365 3666. 通过PIN管脚描述句柄，并用funName承接获取的管脚功能名，如果操作失败则释放PIN管脚描述句柄。 367 3687. 使用完PIN后，不再对管脚进行操作，释放PIN管脚描述句柄。 369 370```c 371#include "hdf_log.h" // 标准日志打印头文件 372#include "pin_if.h" // PIN标准接口头文件 373 374int32_t PinTestSample(void) 375{ 376 int32_t ret; 377 uint32_t strengthNum; 378 enum PinPullType pullTypeNum; 379 char *pinName = NULL; 380 const char *funcName = NULL; 381 DevHandle handle = NULL; 382 383 // PIN管脚名，要填写实际要设置的管脚名 384 pinName = "P18"; 385 // PIN获取管脚描述句柄 386 handle = PinGet(pinName); 387 if (handle == NULL) { 388 HDF_LOGE("PinTestSample: pin get fail!\n"); 389 return -1; 390 } 391 // PIN设置管脚推拉方式为上拉 392 pullTypeNum = 1; 393 ret = PinSetPull(handle, pullTypeNum); 394 if (ret != HDF_SUCCESS) { 395 HDF_LOGE("PinTestSample: pin set pull fail, ret:%d\n", ret); 396 goto ERR; 397 } 398 // PIN获取管脚推拉方式 399 ret = PinGetPull(handle, &pullTypeNum); 400 if (ret != HDF_SUCCESS) { 401 HDF_LOGE("PinTestSample: pin get pull fail, ret:%d\n", ret); 402 goto ERR; 403 } 404 // PIN设置管脚推拉强度为2 405 strengthNum = 2; 406 ret = PinSetStrength(handle, strengthNum); 407 if (ret != HDF_SUCCESS) { 408 HDF_LOGE("PinTestSample: pin set strength fail, ret:%d\n", ret); 409 goto ERR; 410 } 411 // PIN获取管脚推拉强度 412 ret = PinGetStrength(handle, &strengthNum); 413 if (ret != HDF_SUCCESS) { 414 HDF_LOGE("PinTestSample: pin get strength fail, ret:%d\n", ret); 415 goto ERR; 416 } 417 // PIN设置管脚功能为LSADC_CH1 418 funcName = "LSADC_CH1"; 419 ret = PinSetFunc(handle, funcName); 420 if (ret != HDF_SUCCESS) { 421 HDF_LOGE("PinTestSample: pin set func fail, ret:%d\n", ret); 422 goto ERR; 423 } 424 // PIN获取管脚功能 425 ret = PinGetFunc(handle, &funcName); 426 if (ret != HDF_SUCCESS) { 427 HDF_LOGE("PinTestSample: pin get func fail, ret:%d\n", ret); 428 goto ERR; 429 } 430 HDF_LOGD("PinTestSample: function tests end.", __func__); 431ERR: 432 // 释放PIN管脚描述句柄 433 PinPut(handle); 434 return ret; 435} 436``` 437
