OpenHarmony @CnapData

概述

功能简介

PIN即管脚控制器，用于统一管理各SoC厂商管脚资源，对外提供管脚复用功能。

基本概念

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

SoC（System on Chip）

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

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

运作机制

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

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

图 1 无服务模式结构图

约束与限制

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

开发指导

场景介绍

PIN模块主要用于管脚资源管理。在各SoC厂商对接HDF框架时，需要来适配PIN驱动。

接口说明

通过以下PinCntlrMethod中的函数调用PIN驱动对应的函数。 PinCntlrMethod定义：

struct PinCntlrMethod {
    int32_t (*SetPinPull)(struct PinCntlr *cntlr, uint32_t index, enum PinPullType pullType);
    int32_t (*GetPinPull)(struct PinCntlr *cntlr, uint32_t index, enum PinPullType *pullType);
    int32_t (*SetPinStrength)(struct PinCntlr *cntlr, uint32_t index, uint32_t strength);
    int32_t (*GetPinStrength)(struct PinCntlr *cntlr, uint32_t index, uint32_t *strength);
    int32_t (*SetPinFunc)(struct PinCntlr *cntlr, uint32_t index, const char *funcName);
    int32_t (*GetPinFunc)(struct PinCntlr *cntlr, uint32_t index, const char **funcName);
};

表 1 PinCntlrMethod成员的回调函数功能说明

成员函数	入参	出参	返回值	功能
SetPinPull	cntlr：结构体指针，核心层Pin控制器； index：uint32_t变量，管脚索引号； pullType：枚举常量，Pin管脚推拉方式；	无	HDF_STATUS相关状态	PIN设置管脚推拉方式
GetPinPull	cntlr：结构体指针，核心层Pin控制器； index：uint32_t变量，管脚索引号；	pullType：枚举常量指针，传出Pin管脚推拉方式；	HDF_STATUS相关状态	PIN获取管脚推拉方式
SetPinStrength	cntlr：结构体指针，核心层Pin控制器； index：uint32_t变量，管脚索引号； strength：uint32_t变量，Pin推拉强度；	无	HDF_STATUS相关状态	PIN设置推拉强度
GetPinStrength	cntlr：结构体指针，核心层Pin控制器； index：uint32_t变量，管脚索引号；	strength：uint32_t变量指针，传出Pin推拉强度；	HDF_STATUS相关状态	PIN获取推拉强度
SetPinFunc	cntlr：结构体指针，核心层Pin控制器； index：uint32_t变量，管脚索引号； funcName：char指针常量，传入Pin管脚功能；	无	HDF_STATUS相关状态	PIN设置管脚功能
GetPinFunc	cntlr：结构体指针，核心层Pin控制器； index：uint32_t变量，管脚索引号；	funcName：char双重指针常量，传出Pin管脚功能；	HDF_STATUS相关状态	PIN获取管脚功能

开发步骤

PIN模块适配包含以下四个步骤：

实例化驱动入口。
配置属性文件。
实例化核心层接口函数。
驱动调试。

实例化驱动入口：
- 实例化HdfDriverEntry结构体成员。驱动开发首先需要实例化驱动入口，驱动入口必须为HdfDriverEntry（在 hdf_device_desc.h 中定义）类型的全局变量，且moduleName要和device_info.hcs中保持一致。
- 调用HDF_INIT将HdfDriverEntry实例化对象注册到HDF框架中。一般在加载驱动时HDF会先调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。
```
static struct HdfDriverEntry g_hi35xxPinDriverEntry = {
    .moduleVersion = 1,
    .Bind = Hi35xxPinBind,
    .Init = Hi35xxPinInit,
    .Release = Hi35xxPinRelease,
    .moduleName = "hi35xx_pin_driver", // 【必要且与HCS文件中里面的moduleName匹配】
};
HDF_INIT(g_hi35xxPinDriverEntry); // 调用HDF_INIT将驱动入口注册到HDF框架中
```

配置属性文件：

在vendor/hisilicon/hispark_taurus/hdf_config/device_info/device_info.hcs文件中添加deviceNode描述。

root {
    device_info { 
        platform :: host {
            hostName = "platform_host";
            priority = 50;
            device_pin :: device {
                device0 :: deviceNode {   // 为每一个Pin控制器配置一个HDF设备节点，存在多个时须添加，否则不用
                    policy = 0;			  // 2:用户态可见,1:内核态可见,0:不需要发布服务
                    priority = 10;        // 驱动启动优先级
                    permission = 0644;    // 驱动创建设备节点权限
                    /* 【必要】用于指定驱动名称，需要与期望的驱动Entry中的moduleName一致 */
                    moduleName = "hi35xx_pin_driver";
                    /* 【必要】用于配置控制器私有数据，要与pin_config.hcs中对应控制器保持一致，具体的控制器信息在pin_config.hcs中 */
                    deviceMatchAttr = "hisilicon_hi35xx_pin_0";
                }
                device1 :: deviceNode {
                    policy = 0;
                    priority = 10;
                    permission = 0644;
                    moduleName = "hi35xx_pin_driver";
                    deviceMatchAttr = "hisilicon_hi35xx_pin_1";
                }
                ......
            }
        }
    }
}

添加pin_config.hcs器件属性文件。在device/soc/hisilicon/hi3516dv300/sdk_liteos/hdf_config/pin/pin_config.hcs目录下配置器件属性，其中配置参数如下：

root {
    platform {
        pin_config_hi35xx {
            template pin_controller {    // 【必要】模板配置，继承该模板的节点如果使用模板中的默认值，则节点字段可以缺省
                number = 0;              // 【必要】controller编号
                regStartBasePhy = 0;     // 【必要】寄存器物理基地址起始地址
                regSize = 0;             // 【必要】寄存器位宽
                pinCount = 0;            // 【必要】管脚数量
                match_attr = "";
                template pin_desc {
                    pinName = "";        // 【必要】管脚名称
                    init = 0;            // 【必要】寄存器默认值
                    F0 = "";             // 【必要】功能0
                    F1 = "";             // 功能1
                    F2 = "";             // 功能2
                    F3 = "";             // 功能3
                    F4 = "";             // 功能4
                    F5 = "";             // 功能5
                }
            }
            controller_0 :: pin_controller {
                number = 0;
                regStartBasePhy = 0x10FF0000;
                regSize = 0x48;
                pinCount = 18;
                match_attr = "hisilicon_hi35xx_pin_0";
                T1 :: pin_desc {
                    pinName = "T1";
                    init = 0x0600;
                    F0 = "EMMC_CLK";
                    F1 = "SFC_CLK";
                    F2 = "SFC_BOOT_MODE";
                }
                ...... // 对应管脚控制器下的每个管脚，按实际添加
            }
            ......//每个管脚控制器对应一个controller节点，如存在多个Pin控制器，请依次添加对应的controller节点。
        }
    }
}

实例化PIN控制器对象：

初始化PinCntlr成员。在Hi35xxPinCntlrInit函数中对PinCntlr成员进行初始化操作。

struct Hi35xxPinDesc {
    // 管脚名
    const char *pinName;
    // 初始化值
    uint32_t init;
    // 管脚索引
    uint32_t index;
    // 管脚推拉方式
    int32_t pullType;
    // 管脚推拉强度
    int32_t strength;
    // 管脚功能名字符串数组
    const char *func[HI35XX_PIN_FUNC_MAX];
};

struct Hi35xxPinCntlr {
    // 管脚控制器
    struct PinCntlr cntlr;
    // 管脚描述结构体指针
    struct Hi35xxPinDesc *desc;
    // 寄存器映射地址
    volatile unsigned char *regBase;
    // 管脚控制器编号
    uint16_t number;
    // 寄存器物理基地址起始地址
    uint32_t regStartBasePhy;
    // 寄存器位宽
    uint32_t regSize;
    // 管脚数量
    uint32_t pinCount;
};

// PinCntlr是核心层控制器，其中的成员在init函数中会被赋值
struct PinCntlr {
    struct IDeviceIoService service;
    struct HdfDeviceObject *device;
    struct PinCntlrMethod *method;
    struct DListHead node;  // 链表节点
    OsalSpinlock spin;      // 自旋锁
    uint16_t number;        // 管脚控制器编号
    uint16_t pinCount;      // 管脚数量
    struct PinDesc *pins;
    void *priv;             // 私有数据
};

// PinCntlr管脚控制器初始化
static int32_t Hi35xxPinCntlrInit(struct HdfDeviceObject *device, struct Hi35xxPinCntlr *hi35xx)
{
    struct DeviceResourceIface *drsOps = NULL;
    int32_t ret;
    // 从hcs文件读取管脚控制器相关属性
    drsOps = DeviceResourceGetIfaceInstance(HDF_CONFIG_SOURCE);
    if (drsOps == NULL || drsOps->GetUint32 == NULL || drsOps->GetUint16 == NULL) {
        HDF_LOGE("%s: invalid drs ops fail!", __func__);
        return HDF_FAILURE;
    }
    ret = drsOps->GetUint16(device->property, "number", &hi35xx->number, 0);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("%s: read number failed", __func__);
        return ret;
    }
    
    ret = drsOps->GetUint32(device->property, "regStartBasePhy", &hi35xx->regStartBasePhy, 0);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("%s: read regStartBasePhy failed", __func__);
        return ret;
    }
    ret = drsOps->GetUint32(device->property, "regSize", &hi35xx->regSize, 0);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("%s: read regSize failed", __func__);
        return ret;
    }
    ret = drsOps->GetUint32(device->property, "pinCount", &hi35xx->pinCount, 0);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("%s: read pinCount failed", __func__);
        return ret;
    }
    // 将读取的值赋值给管脚控制器的成员，完成管脚控制器初始化
    hi35xx->cntlr.pinCount = hi35xx->pinCount;
    hi35xx->cntlr.number = hi35xx->number;
    hi35xx->regBase = OsalIoRemap(hi35xx->regStartBasePhy, hi35xx->regSize);  // 管脚控制器映射
    if (hi35xx->regBase == NULL) {
        HDF_LOGE("%s: remap Pin base failed", __func__);
        return HDF_ERR_IO;
    }
    hi35xx->desc = (struct Hi35xxPinDesc *)OsalMemCalloc(sizeof(struct Hi35xxPinDesc) * hi35xx->pinCount);
    hi35xx->cntlr.pins = (struct PinDesc *)OsalMemCalloc(sizeof(struct PinDesc) * hi35xx->pinCount);
    return HDF_SUCCESS;
}

PinCntlr成员回调函数结构体PinCntlrMethod的实例化，其他成员在Init函数中初始化。

// PinCntlrMethod结构体成员都是回调函数，厂商需要根据表1完成相应的函数功能。
static struct PinCntlrMethod g_method = {
    .SetPinPull = Hi35xxPinSetPull,              // 设置推拉方式
    .GetPinPull = Hi35xxPinGetPull,              // 获取推拉方式
    .SetPinStrength = Hi35xxPinSetStrength,      // 设置推拉强度
    .GetPinStrength = Hi35xxPinGetStrength,      // 获取推拉强度
    .SetPinFunc = Hi35xxPinSetFunc,              // 设置管脚功能
    .GetPinFunc = Hi35xxPinGetFunc,              // 获取管脚功能
};

Init函数

入参： HdfDeviceObject这个是整个驱动对外暴露的接口参数，具备HCS配置文件的信息。

返回值： HDF_STATUS相关状态（下表为部分展示，如需使用其他状态，可见/drivers/framework/include/utils/hdf_base.h中HDF_STATUS 定义）。

状态(值)	问题描述
HDF_ERR_INVALID_OBJECT	控制器对象非法
HDF_ERR_MALLOC_FAIL	内存分配失败
HDF_ERR_INVALID_PARAM	参数非法
HDF_ERR_IO	I/O 错误
HDF_SUCCESS	初始化成功
HDF_FAILURE	初始化失败

    函数说明：
    初始化自定义结构体对象和PinCntlr成员，并通过调用核心层PinCntlrAdd函数挂载Pin控制器。
    
    ```c
    static int32_t Hi35xxPinReadFunc(struct Hi35xxPinDesc *desc, const struct DeviceResourceNode *node, struct DeviceResourceIface *drsOps)
    {
        int32_t ret;
        uint32_t funcNum = 0;
        // 从hcs中读取管脚控制器子节点管脚功能名
        ret = drsOps->GetString(node, "F0", &desc->func[funcNum], "NULL");
        if (ret != HDF_SUCCESS) {
            HDF_LOGE("%s: read F0 failed", __func__);
            return ret;
        }

        funcNum++;
        ret = drsOps->GetString(node, "F1", &desc->func[funcNum], "NULL");
        if (ret != HDF_SUCCESS) {
            HDF_LOGE("%s: read F1 failed", __func__);
            return ret;
        }

        funcNum++;
        ......
        return HDF_SUCCESS;
    }

    static int32_t Hi35xxPinParsePinNode(const struct DeviceResourceNode *node, struct Hi35xxPinCntlr *hi35xx, int32_t index)
    {
        int32_t ret;
        struct DeviceResourceIface *drsOps = NULL;
        // 从hcs中读取管脚控制器子节点管脚相关属性
        drsOps = DeviceResourceGetIfaceInstance(HDF_CONFIG_SOURCE);
        if (drsOps == NULL || drsOps->GetUint32 == NULL || drsOps->GetString == NULL) {
            HDF_LOGE("%s: invalid drs ops fail!", __func__);
            return HDF_FAILURE;
        }
        ret = drsOps->GetString(node, "pinName", &hi35xx->desc[index].pinName, "NULL");
        if (ret != HDF_SUCCESS) {
            HDF_LOGE("%s: read pinName failed", __func__);
            return ret;
        }
        ......
        ret = Hi35xxPinReadFunc(&hi35xx->desc[index], node, drsOps);
        if (ret != HDF_SUCCESS) {
            HDF_LOGE("%s:Pin read Func failed", __func__);
            return ret;
        }
        hi35xx->cntlr.pins[index].pinName = hi35xx->desc[index].pinName;
        hi35xx->cntlr.pins[index].priv = (void *)node;
        ......
        return HDF_SUCCESS;
    }

    static int32_t Hi35xxPinInit(struct HdfDeviceObject *device)
    {
        ......
        struct Hi35xxPinCntlr *hi35xx = NULL;
        ......
        ret = Hi35xxPinCntlrInit(device, hi35xx);    // 管脚控制器初始化
        ......
        DEV_RES_NODE_FOR_EACH_CHILD_NODE(device->property, childNode) { // 遍历管脚控制器的每个子节点
            ret = Hi35xxPinParsePinNode(childNode, hi35xx, index);    // 解析子节点
            ......
        }

        hi35xx->cntlr.method = &g_method;    // 实例化method
        ret = PinCntlrAdd(&hi35xx->cntlr);   // 挂载控制器
        if (ret != HDF_SUCCESS) {
            HDF_LOGE("%s: add Pin cntlr: failed", __func__);
            ret = HDF_FAILURE;
        }
        return HDF_SUCCESS;
    }
    ```

Release 函数

入参：

HdfDeviceObject 是整个驱动对外暴露的接口参数，具备 HCS 配置文件的信息。

返回值：

无。

函数说明：

释放内存和删除控制器，该函数需要在驱动入口结构体中赋值给 Release 接口，当HDF框架调用Init函数初始化驱动失败时，可以调用 Release 释放驱动资源。

static void Hi35xxPinRelease(struct HdfDeviceObject *device)
{
    int32_t ret;
    uint16_t number;
    struct PinCntlr *cntlr = NULL;
    struct Hi35xxPinCntlr *hi35xx = NULL;
    struct DeviceResourceIface *drsOps = NULL;

    if (device == NULL || device->property == NULL) {
        HDF_LOGE("%s: device or property is null", __func__);
        return;
    }
    // 从hcs文件中读取管脚控制器编号
    drsOps = DeviceResourceGetIfaceInstance(HDF_CONFIG_SOURCE);
    if (drsOps == NULL || drsOps->GetUint32 == NULL || drsOps->GetString == NULL) {   
        HDF_LOGE("%s: invalid drs ops", __func__);
        return;
    }
    ret = drsOps->GetUint16(device->property, "number", &number, 0);
    if (ret != HDF_SUCCESS) {
        HDF_LOGE("%s: read cntlr number failed", __func__);
        return;
    }
 
    cntlr = PinCntlrGetByNumber(number);   // 通过管脚控制器编号获取管脚控制器
    PinCntlrRemove(cntlr);
    hi35xx = (struct Hi35xxPinCntlr *)cntlr;
    if (hi35xx != NULL) {
        if (hi35xx->regBase != NULL) {
            OsalIoUnmap((void *)hi35xx->regBase);
        }
        OsalMemFree(hi35xx);
    }
}

驱动调试： 【可选】针对新增驱动程序，建议验证驱动基本功能，例如挂载后的信息反馈，数据传输的成功与否等。