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![PIN统一服务模式](figures/统一服务模式结构图.png)
47
48### 约束与限制<a name="section5"></a>
49
50PIN模块目前只支持小型系统LiteOS-A内核。
51
52## 使用指导<a name="section6"></a>
53
54### 场景介绍<a name="section7"></a>
55
56PIN模块仅是一个软件层面的概念，主要工作是管脚资源管理。使用复用管脚时，通过设置管脚功能、设置管脚推拉方式、设置管脚推拉强度来适配指定场景的需求。
57
58### 接口说明<a name="section8"></a>
59
60PIN模块提供的主要接口如表1所示，具体API详见//drivers/hdf_core/framework/include/platform/pin_if.h。
61
62**表 1**  PIN驱动API接口功能介绍
63<a name="table1"></a>
64
65| **接口名** | **描述** |
66| ------------------------------------------------------------ | ---------------- |
67| DevHandle PinGet(const char \*pinName) | 获取管脚描述句柄 |
68| void PinPut(DevHandle handle) | 释放管脚描述句柄 |
69| int32_t PinSetPull(DevHandle handle, enum PinPullType pullType) | 设置管脚推拉方式 |
70| int32_t PinGetPull(DevHandle handle, enum PinPullType \*pullType) | 获取管脚推拉方式 |
71| int32_t PinSetStrength(DevHandle handle, uint32_t strength) | 设置管脚推拉强度 |
72| int32_t PinGetStrength(DevHandle handle, uint32_t \*strength) | 获取管脚推拉强度 |
73| int32_t PinSetFunc(DevHandle handle, const char \*funcName) | 设置管脚功能 |
74| int32_t PinGetFunc(DevHandle handle, const char \**funcName) | 获取管脚功能 |
75
76>![](../public_sys-resources/icon-note.gif) **说明：**<br>
77>本文涉及PIN的所有接口，支持内核态及用户态使用。
78
79### 开发步骤<a name="section9"></a>
80
81使用PIN设备的一般流程如图2所示。
82
83**图 2** PIN使用流程图<a name="fig2"></a>
84![PIN使用流程图](figures/PIN使用流程图.png)
85
86#### 获取PIN管脚描述句柄
87
88在使用PIN进行管脚操作时，首先要调用PinGet获取管脚描述句柄，该函数会返回匹配传入管脚名的管脚描述句柄。
89
90```c
91DevHandle PinGet(const char *pinName);
92```
93
94**表 2**  PinGet参数和描述
95
96<a name="table2"></a>
97
98| 参数 | 描述 |
99| ---------- | ----------------------- |
100| pinName | 字符指针类型，管脚名 |
101| **返回值** | **描述** |
102| NULL | 获取PIN管脚描述句柄失败 |
103| handle | PIN管脚描述句柄 |
104
105假设PIN需要操作的管脚名为P18，获取其管脚描述句柄的示例如下：
106
107```c
108DevHandle handle = NULL;    // PIN管脚描述句柄
109
110char pinName = "P18";       // PIN管脚名
111handle = PinGet(pinName);
112if (handle == NULL) {
113    HDF_LOGE("PinGet: get handle failed!\n");
114    return HDF_FAILURE;
115}
116```
117
118#### PIN设置管脚推拉方式
119
120PIN设置管脚推拉方式的函数如下所示：
121
122```c
123int32_t PinSetPull(DevHandle handle, enum PinPullType pullType);
124```
125
126**表 3**  参数和描述
127
128<a name="table3"></a>
129
130| 参数 | 描述 |
131| ---------- | ----------------------- |
132| handle | DevHandle类型，PIN管脚描述句柄 |
133| pullType | 枚举类型，PIN管脚推拉方式 |
134| **返回值** | **描述**          |
135| HDF_SUCCESS | PIN设置管脚推拉方式成功 |
136| 负数 | PIN设置管脚推拉方式失败 |
137
138假设PIN要设置的管脚推拉方式为上拉，其实例如下：
139
140```c
141int32_t ret;
142enum PinPullType pullTypeNum;
143
144// PIN设置管脚推拉方式
145pullTypeNum = 1;
146ret = PinSetPull(handle, pullTypeNum);
147if (ret != HDF_SUCCESS) {
148    HDF_LOGE("PinSetPull: failed, ret %d\n", ret);
149    return ret;
150}
151```
152
153#### PIN获取管脚推拉方式
154
155PIN获取管脚推拉方式的函数如下所示：
156
157```c
158int32_t PinGetPull(DevHandle handle, enum PinPullType *pullType);
159```
160
161**表 4**  PinGetPull参数和描述
162
163<a name="table4"></a>
164
165| 参数 | 描述 |
166| ---------- | ------------------------- |
167| handle | DevHandle类型，PIN管脚描述句柄 |
168| pullType | 枚举类型指针，接收PIN管脚推拉方式 |
169| **返回值** | **描述**            |
170| HDF_SUCCESS | PIN获取管脚推拉方式成功 |
171| 负数 | PIN获取管脚推拉方式失败 |
172
173PIN获取管脚推拉方式的实例如下：
174
175```c
176int32_t ret;
177enum PinPullType pullTypeNum;
178
179// PIN获取管脚推拉方式
180ret = PinGetPull(handle, &pullTypeNum);
181if (ret != HDF_SUCCESS) {
182    HDF_LOGE("PinGetPull: failed, ret %d\n", ret);
183    return ret;
184}
185```
186
187#### PIN设置管脚推拉强度
188
189PIN设置管脚推拉强度函数如下所示：
190
191```c
192int32_t PinSetStrength(DevHandle handle, uint32_t strength);
193```
194
195**表 5**  PinSetStrength参数和描述
196
197<a name="table5"></a>
198
199| 参数 | 描述 |
200| ---------- | ----------------------- |
201| handle | DevHandle类型，管脚描述句柄 |
202| strength | uint32_t类型，PIN管脚推拉强度 |
203| **返回值** | **描述**          |
204| HDF_SUCCESS | PIN设置管脚推拉强度成功 |
205| 负数 | PIN设置管脚推拉强度失败 |
206
207假设PIN要设置的管脚推拉强度为2，其实例如下：
208
209```c
210int32_t ret;
211uint32_t strengthNum;
212// PIN设置管脚推拉强度
213strengthNum = 2;
214ret = PinSetStrength(handle, strengthNum);
215if (ret != HDF_SUCCESS) {
216    HDF_LOGE("PinSetStrength: failed, ret %d\n", ret);
217    return ret;
218}
219```
220
221#### PIN获取管脚推拉强度
222
223PIN设置管脚推拉强度后，可以通过PIN获取管脚推拉强度接口来查看PIN管脚推拉强度，PIN获取管脚推拉强度的函数如下所示：
224
225```c
226int32_t PinGetStrength(DevHandle handle, uint32_t *strength);
227```
228
229**表 6**  PinGetStrength参数和描述
230
231<a name="table6"></a>
232
233| 参数 | 描述 |
234| ---------- | ------------------------- |
235| handle | DevHandle类型，管脚描述句柄 |
236| strength | uint32_t类型指针，接收PIN管脚推拉强度
237| **返回值** | **描述**            |
238| HDF_SUCCESS | PIN获取管脚推拉强度成功 |
239| 负数 | PIN获取管脚推拉强度失败 |
240
241PIN获取管脚推拉强度的实例如下：
242
243```c
244int32_t ret;
245uint32_t strengthNum;
246
247// PIN获取管脚推拉强度
248ret = PinGetStrength(handle, &strengthNum);
249if (ret != HDF_SUCCESS) {
250    HDF_LOGE("PinGetStrength: failed, ret %d\n", ret);
251    return ret;
252}
253```
254
255#### PIN设置管脚功能
256
257管脚功能特指的是管脚复用的功能，每个管脚功能都不相同，管脚功能名详细可以参考//device/soc/hisilicon/hi3516dv300/sdk_liteos/hdf_config/pin/pin_config.hcs。
258
259PIN设置管脚功能函数如下所示：
260
261```c
262int32_t PinSetFunc(DevHandle handle, const char *funcName);
263```
264
265**表 7**  PinSetFunc参数和描述
266
267<a name="table7"></a>
268
269| 参数 | 描述 |
270| ---------- | ------------------- |
271| handle | DevHandle类型，管脚描述句柄 |
272| funcName | 字符指针类型，PIN管脚功能名 |
273| **返回值** | **描述**      |
274| HDF_SUCCESS | PIN设置管脚功能成功 |
275| 负数 | PIN设置管脚功能失败 |
276
277假设PIN需要设置的管脚功能为LSADC_CH1（ADC通道1），其实例如下：
278
279```c
280int32_t ret;
281char funcName = "LSADC_CH1";
282
283// PIN设置管脚功能
284ret = PinSetFunc(handle, funcName);
285if (ret != HDF_SUCCESS) {
286    HDF_LOGE("PinSetFunc: failed, ret %d\n", ret);
287    return ret;
288}
289```
290
291#### PIN获取管脚功能
292
293PIN设置管脚功能后，可以通过PIN获取管脚功能接口来查看PIN管脚功能，PIN获取管脚功能的函数如下所示：
294
295```c
296int32_t PinGetFunc(DevHandle handle, const char **funcName);
297```
298
299**表 8**  PinGetFunc参数和描述
300
301<a name="table8"></a>
302
303| 参数 | 描述 |
304| ---------- | --------------------- |
305| handle | DevHandle类型，管脚描述句柄 |
306| funcName | 字符类型双指针，接收PIN管脚功能 |
307| **返回值** | **描述**        |
308| HDF_SUCCESS | PIN获取管脚功能成功 |
309| 负数 | PIN获取管脚功能失败 |
310
311PIN获取管脚功能的实例如下：
312
313```c
314int32_t ret;
315char *funcName = NULL;
316
317// PIN获取管脚功能
318ret = PinGetFunc(handle, &funcName);
319if (ret != HDF_SUCCESS) {
320    HDF_LOGE("PinGetFunc: failed, ret %d\n", ret);
321    return ret;
322}
323```
324
325####  释放PIN管脚描述句柄
326
327PIN不再进行任何操作后，需要释放PIN管脚描述管脚句柄，函数如下所示：
328
329```c
330void PinPut(DevHandle handle);
331```
332
333**表 9**  PinPut参数和描述
334
335<a name="table9"></a>
336
337| 参数 | 描述 |
338| ---------- | -------------- |
339| handle | DevHandle类型，管脚描述句柄 |
340| **返回值** | **描述** |
341| NA | 无返回值 |
342
343PIN销毁管脚描述句柄实例如下：
344
345```c
346PinPut(handle);
347```
348
349## 使用实例<a name="section10"></a>
350
351下面将基于Hi3516DV300开发板展示使用PIN设置管脚相关属性完整操作，步骤主要如下：
352
3531. 传入要设置的管脚名，获取PIN管脚描述句柄。
354
3552. 通过PIN管脚描述句柄以及推拉方式pullTypeNum设置管脚推拉方式，如果操作失败则释放PIN管脚描述句柄。
356
3573. 通过PIN管脚描述句柄，并用pullTypeNum承接获取的管脚推拉方式，如果操作失败则释放PIN管脚描述句柄。
358
3594. 通过PIN管脚描述句柄以及推拉强度strengthNum设置管脚推拉强度，如果操作失败则释放PIN管脚描述句柄。
360
3615. 通过PIN管脚描述句柄，并用strengthNum承接获取的管脚推拉强度，如果操作失败则释放PIN管脚描述句柄。
362
3635. 通过PIN管脚描述句柄以及管脚功能名funName设置管脚功能，如果操作失败则释放PIN管脚描述句柄。
364
3656. 通过PIN管脚描述句柄，并用funName承接获取的管脚功能名，如果操作失败则释放PIN管脚描述句柄。
366
3677. 使用完PIN后，不再对管脚进行操作，释放PIN管脚描述句柄。
368
369```c
370#include "hdf_log.h"                              // 标准日志打印头文件
371#include "pin_if.h"                               // PIN标准接口头文件
372
373int32_t PinTestSample(void)
374{
375    int32_t ret;
376    uint32_t strengthNum;
377    enum PinPullType pullTypeNum;
378    char *pinName = NULL;
379    const char *funcName = NULL;
380    DevHandle handle = NULL;
381
382    // PIN管脚名，要填写实际要设置的管脚名
383    pinName = "P18";
384    // PIN获取管脚描述句柄
385    handle = PinGet(pinName);
386    if (handle == NULL) {
387        HDF_LOGE("PinTestSample: pin get fail!\n");
388        return -1;
389    }
390    // PIN设置管脚推拉方式为上拉
391    pullTypeNum = 1;
392    ret = PinSetPull(handle, pullTypeNum);
393    if (ret != HDF_SUCCESS) {
394        HDF_LOGE("PinTestSample: pin set pull fail, ret:%d\n", ret);
395        goto ERR;
396    }
397    // PIN获取管脚推拉方式
398    ret = PinGetPull(handle, &pullTypeNum);
399    if (ret != HDF_SUCCESS) {
400        HDF_LOGE("PinTestSample: pin get pull fail, ret:%d\n", ret);
401        goto ERR;
402    }
403    // PIN设置管脚推拉强度为2
404    strengthNum = 2;
405    ret = PinSetStrength(handle, strengthNum);
406    if (ret != HDF_SUCCESS) {
407        HDF_LOGE("PinTestSample: pin set strength fail, ret:%d\n", ret);
408        goto ERR;
409    }
410    // PIN获取管脚推拉强度
411    ret = PinGetStrength(handle, &strengthNum);
412    if (ret != HDF_SUCCESS) {
413        HDF_LOGE("PinTestSample: pin get strength fail, ret:%d\n", ret);
414        goto ERR;
415    }
416    // PIN设置管脚功能为LSADC_CH1
417    funcName = "LSADC_CH1";
418    ret = PinSetFunc(handle, funcName);
419    if (ret != HDF_SUCCESS) {
420        HDF_LOGE("PinTestSample: pin set func fail, ret:%d\n", ret);
421        goto ERR;
422    }
423    // PIN获取管脚功能
424    ret = PinGetFunc(handle, &funcName);
425    if (ret != HDF_SUCCESS) {
426        HDF_LOGE("PinTestSample: pin get func fail, ret:%d\n", ret);
427        goto ERR;
428    }
429    HDF_LOGD("PinTestSample: function tests end.", __func__);
430ERR:
431    // 释放PIN管脚描述句柄
432    PinPut(handle);
433    return ret;
434}
435```
436