PIN

• 概述
  • 功能简介
  • 基本概念
  • 运作机制
  • 约束与限制
• 使用指导
  • 场景介绍
  • 接口说明
  • 开发步骤
  • 使用实例

概述

功能简介

• PIN即管脚控制器，用于统一管理各SoC厂商管脚资源，对外提供管脚复用功能：包括管脚推拉方式、管脚推拉强度以及管脚功能。
• PIN接口定义了操作PIN管脚的通用方法集合，包括：
  • 获取/释放管脚描述句柄: 传入管脚名与链表中每个控制器下管脚名进行匹配，匹配则会获取一个管脚描述句柄，操作完PIN管脚后释放该管脚描述句柄。
  • 设置/获取管脚推拉方式：推拉方式可以是上拉、下拉以及悬空。
  • 设置/获取管脚推拉强度：用户可根据实际设置管脚推拉强度大小。
  • 设置/获取管脚功能：通过管脚功能名设置/获取管脚功能，实现管脚复用。

基本概念

PIN是一个软件层面的概念，目的是为了统一各SoC厂商PIN管脚管理，对外提供管脚复用功能，配置PIN管脚的电气特性。

• SoC（System on Chip）

  系统级芯片，也有称作片上系统，通常是面向特定用途将微处理器、模拟IP核、数字IP核和存储器集成在单一芯片的标准产品。

• 管脚复用

  由于芯片自身的引脚数量有限，无法满足日益增多的外接需求。此时可以通过软件层面的寄存器设置，让引脚工作在不同的状态，从而实现相同引脚完成不同功能的目的。

运作机制

在HDF框架中，PIN模块暂不支持用户态，所以不需要发布服务，接口适配模式采用无服务模式，用于不需要在用户态提供API的设备类型，或者没有用户态和内核区分的OS系统，其关联方式是DevHandle直接指向设备对象内核态地址（DevHandle是一个void类型指针）。

PIN模块各分层作用：接口层提供获取PIN管脚、设置PIN管脚推拉方式、获取PIN管脚推拉方式、设置PIN管脚推拉强度、获取PIN管脚推拉强度、设置PIN管脚功能、获取PIN管脚功能、释放PIN管脚的接口。核心层主要提供PIN管脚资源匹配，PIN管脚控制器的添加、移除以及管理的能力，通过钩子函数与适配层交互。适配层主要是将钩子函数的功能实例化，实现具体的功能。

图 1 PIN无服务模式

约束与限制

PIN模块目前仅支持轻量和小型系统内核（LiteOS）。

使用指导

场景介绍

PIN模块仅是一个软件层面的概念，主要工作是管脚资源管理。使用复用管脚时，通过设置管脚功能、设置管脚推拉方式、设置管脚推拉强度来适配指定场景的需求。

接口说明

PIN模块提供的主要接口如表1所示，更多关于接口的介绍请参考对应的API接口文档。

表 1 PIN驱动API接口功能介绍

说明： 本文涉及的所有接口，仅限内核态使用，不支持在用户态使用。

开发步骤

使用PIN设备的一般流程如图2所示。

图 2 PIN使用流程图

获取PIN管脚描述句柄

在使用PIN进行管脚操作时，首先要调用PinGet获取管脚描述句柄，该函数会返回匹配传入管脚名的管脚描述句柄。

DevHandle PinGet(const char *pinName);

表 2 PinGet参数和返回值描述

假设PIN需要操作的管脚名为P18，获取其管脚描述句柄的示例如下：

DevHandle handle = NULL;               /* PIN管脚描述句柄  */
char pinName = "P18";                  /* PIN管脚号 */
handle = PinGet(pinName);
if (handle == NULL) {
    HDF_LOGE("PinGet: get handle failed!\n");
    return;
}

PIN设置管脚推拉方式

PIN设置管脚推拉方式的函数如下所示：

int32_t PinSetPull(DevHandle handle, enum PinPullType pullType);

表 3 参数和返回值描述

假设PIN要设置的管脚推拉方式为上拉，其实例如下：

int32_t ret;
enum PinPullType pullTypeNum;
/* PIN设置管脚推拉方式 */
pullTypeNum = 1;
ret = PinSetPull(handle, pullTypeNum);
if (ret != HDF_SUCCESS) {
    HDF_LOGE("PinSetPull: failed, ret %d\n", ret);
    return ret;
}

PIN获取管脚推拉方式

PIN获取管脚推拉方式的函数如下所示：

int32_t PinGetPull(DevHandle handle, enum PinPullType *pullType);

表 4 PinGetPull参数和返回值描述

PIN获取管脚推拉方式的实例如下：

int32_t ret;
enum PinPullType pullTypeNum;
/* PIN获取管脚推拉方式 */
ret = PinGetPull(handle, &pullTypeNum);
if (ret != HDF_SUCCESS) {
    HDF_LOGE("PinGetPull: failed, ret %d\n", ret);
    return ret;
}

PIN设置管脚推拉强度

PIN设置管脚推拉强度函数如下所示：

int32_t PinSetStrength(DevHandle handle, uint32_t strength);

表 5 PinSetStrength参数和返回值描述

假设PIN要设置的管脚推拉强度为2，其实例如下：

int32_t ret;
uint32_t strengthNum;
/* PIN设置管脚推拉强度 */
strengthNum = 2;
ret = PinSetStrength(handle, strengthNum);
if (ret != HDF_SUCCESS) {
    HDF_LOGE("PinSetStrength: failed, ret %d\n", ret);
    return ret;
}

PIN获取管脚推拉强度

PIN设置管脚推拉强度后，可以通过PIN获取管脚推拉强度接口来查看PIN管脚推拉强度，PIN获取管脚推拉强度的函数如下所示：

int32_t PinGetStrength(DevHandle handle, uint32_t *strength);

表 6 PinGetStrength参数和返回值描述

PIN获取管脚推拉强度的实例如下：

int32_t ret;
uint32_t strengthNum;
/* PIN获取管脚推拉强度 */
ret = PinGetStrength(handle, &strengthNum);
if (ret != HDF_SUCCESS) {
    HDF_LOGE("PinGetStrength: failed, ret %d\n", ret);
    return ret;
}

PIN设置管脚功能

管脚功能特指的是管脚复用的功能，每个管脚功能都不相同，管脚功能名详细可以参考PIN配置hcs文件。

PIN设置管脚功能函数如下所示：

int32_t PinSetFunc(DevHandle handle, const char *funcName);

表 7 PinSetFunc参数和返回值描述

假设PIN需要设置的管脚功能为LSADC_CH1（ADC通道1），其实例如下：

int32_t ret;
char funcName = "LSADC_CH1";
/* PIN设置管脚功能 */
ret = PinSetFunc(handle, funcName);
if (ret != HDF_SUCCESS) {
    HDF_LOGE("PinSetFunc: failed, ret %d\n", ret);
    return ret;
}

PIN获取管脚功能

PIN设置管脚功能后，可以通过PIN获取管脚功能接口来查看PIN管脚功能，PIN获取管脚功能的函数如下所示：

int32_t PinGetFunc(DevHandle handle, const char **funcName);

表 8 PinGetFunc参数和返回值描述

PIN获取管脚功能的实例如下：

int32_t ret;
char *funcName;
/* PIN获取管脚功能 */
ret = PinGetFunc(handle,&funcName);
if (ret != HDF_SUCCESS) {
    HDF_LOGE("PinGetFunc: failed, ret %d\n", ret);
    return ret;
}

释放PIN管脚描述句柄

PIN不再进行任何操作后，需要释放PIN管脚描述管脚句柄，函数如下所示：

void PinPut(DevHandle handle);

表 9 PinPut参数和返回值描述

PIN销毁管脚描述句柄实例如下：

PinPut(handle);

使用实例

使用PIN设置管脚相关属性完整使用可以参考如下示例代码，示例代码步骤主要如下：

1. 传入要设置的管脚名，获取PIN管脚描述句柄。
2. 通过PIN管脚描述句柄以及推拉方式pullTypeNum设置管脚推拉方式，如果操作失败则释放PIN管脚描述句柄。
3. 通过PIN管脚描述句柄，并用pullTypeNum承接获取的管脚推拉方式，如果操作失败则释放PIN管脚描述句柄。
4. 通过PIN管脚描述句柄以及推拉强度strengthNum设置管脚推拉强度，如果操作失败则释放PIN管脚描述句柄。
5. 通过PIN管脚描述句柄，并用strengthNum承接获取的管脚推拉强度，如果操作失败则释放PIN管脚描述句柄。
6. 通过PIN管脚描述句柄以及管脚功能名funName设置管脚功能，如果操作失败则释放PIN管脚描述句柄。
7. 通过PIN管脚描述句柄，并用funName承接获取的管脚功能名，如果操作失败则释放PIN管脚描述句柄。
8. 使用完PIN后，不再对管脚进行操作，释放PIN管脚描述句柄。

#include "hdf_log.h"   /* 标准日志打印头文件 */
#include "pin_if.h"    /* PIN标准接口头文件 */

int32_t PinTestSample(void)
{
    int32_t ret;
    uint32_t strengthNum;
    enum PinPullType pullTypeNum;
    char pinName;
    char *funName;
    DevHandle handle = NULL;

    /* PIN管脚名，要填写实际要设置的管脚名 */
    pinName = "P18"; 
    /* PIN获取管脚描述句柄 */
    handle = PinGet(pinName);
    if (handle == NULL) {
        HDF_LOGE("PinGet: failed!\n");
        return;
    }
    /* PIN设置管脚推拉方式为上拉 */
    pullTypeNum = 1;
    ret = PinSetPull(handle, pullTypeNum);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("PinSetPull: failed, ret %d\n", ret);
        goto ERR;
    }
    /* PIN获取管脚推拉方式 */
    ret = PinGetPull(handle, &pullTypeNum);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("PinGetPull: failed, ret %d\n", ret);
        goto ERR;
    }
    /* PIN设置管脚推拉强度为2 */
    strengthNum = 2;
    ret = PinSetStrength(handle, strengthNum);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("PinSetStrength: failed, ret %d\n", ret);
        goto ERR;
    }
    /* PIN获取管脚推拉强度 */
    ret = PinGetStrength(handle, &strengthNum);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("PinGetStrength: failed, ret %d\n", ret);
        goto ERR;
    }
    /* PIN设置管脚功能为LSADC_CH1 */
    funName = "LSADC_CH1";
    ret = PinSetFunc(handle, funName);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("PinSetFunc: failed, ret %d\n", ret);
        goto ERR;
    }
    /* PIN获取管脚功能 */
    ret = PinGetFunc(handle, &funcName);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("PinGetFunc: failed, ret %d\n", ret);
        goto ERR;
    }
ERR:
    /* 释放PIN管脚描述句柄 */
    PinPut(handle); 
    return ret;
}