当前位置：首页 > news >正文

pinctrl子系统学习笔记

news 2026/2/11 1:26:08

一、背景

cpu的gpio引脚可以复用成多个功能，如可以配置成I2C或者普通GPIO模式。配置方式一般是通过写引脚复用的配置寄存器，但是不同芯片厂商配置寄存器格式内容各不相同，设置引脚复用无法做到通用且自由的配置，只能在启动初始化时候在soc驱动初始化时对每个引脚配置好。 linux 3.0之后内核中抽象出了pinctrl子系统，每个soc注册设置引脚复用的方法以及将soc的每个引脚可选的复用功能。

二、pinctrl实现

2.1 API

# 用于soc向pinctrl系统中注册设置引脚复用方法以及设置引脚复用状态
# driver_data用于soc驱动私有数据，一般用来保存pin 引脚的可选复用功能列表。
struct pinctrl_dev *pinctrl_register(struct pinctrl_desc *pctldesc,struct device *dev, void *driver_data)# 设置引脚复用状态，用来设置引脚复用状态
int pinctrl_select_state(struct pinctrl *p, struct pinctrl_state *state)# 用于具体设备驱动(i2c等)关联pinctrl节点，以及设置默认复用模式，设备树解析时调用
int pinctrl_bind_pins(struct device *dev)

2.2 数据结构

数据结构关系图：

在这里插入图片描述

这里主要有几个对象：

pin_group 和function : 引脚复用一般是多个引脚组成一个group，一起设置复用状态的。多个引脚复用为某个功能，成为function。

pin_conf ：设置引脚的上下拉电阻等电气参数
pin_mux：设置引脚复用

pinctrl_desc

核心数据结构是pinctrl_desc，pinctrl的全局描述。

struct pinctrl_desc {const char *name;/*系统种有多少个pinctrl*/const struct pinctrl_pin_desc *pins;unsigned int npins;/*引脚控制的操作集，不同芯片方案不同*/const struct pinctrl_ops *pctlops;const struct pinmux_ops *pmxops;const struct pinconf_ops *confops;struct module *owner;
};

pinctrl_pin_desc

描述系统中的所有引脚，drv_data保存驱动私有数据。

struct pinctrl_pin_desc {unsigned number;const char *name;void *drv_data;
};

pinctrl_ops

回调函数，获取pin group的操作，以及解析dts。

struct pinctrl_ops {/*获取系统中有多少个pin groups*/int (*get_groups_count) (struct pinctrl_dev *pctldev);/*获取指定group（由索引selector指定）的名称，由select确认*/const char *(*get_group_name) (struct pinctrl_dev *pctldev,unsigned selector);/*获取指定group的所用pin信息*/int (*get_group_pins) (struct pinctrl_dev *pctldev,unsigned selector,const unsigned **pins,unsigned *num_pins);void (*pin_dbg_show) (struct pinctrl_dev *pctldev, struct seq_file *s,unsigned offset);/*将对应驱动转换成pin map*/int (*dt_node_to_map) (struct pinctrl_dev *pctldev,struct device_node *np_config,struct pinctrl_map **map, unsigned *num_maps);void (*dt_free_map) (struct pinctrl_dev *pctldev,struct pinctrl_map *map, unsigned num_maps);
};

pinconf_ops

配置管脚状态：pinctrl也提供管脚状态如（上下拉、开漏等）的接口。

struct pinconf_ops {
#ifdef CONFIG_GENERIC_PINCONFbool is_generic;
#endif/*获取pin脚的当前状态*/int (*pin_config_get) (struct pinctrl_dev *pctldev,unsigned pin,unsigned long *config);/*设置pin脚状态*/int (*pin_config_set) (struct pinctrl_dev *pctldev,unsigned pin,unsigned long *configs,unsigned num_configs);/*获取或者设置指定pin group的配置项*/int (*pin_config_group_get) (struct pinctrl_dev *pctldev,unsigned selector,unsigned long *config);int (*pin_config_group_set) (struct pinctrl_dev *pctldev,unsigned selector,unsigned long *configs,unsigned num_configs);int (*pin_config_dbg_parse_modify) (struct pinctrl_dev *pctldev,const char *arg,unsigned long *config);void (*pin_config_dbg_show) (struct pinctrl_dev *pctldev,struct seq_file *s,unsigned offset);void (*pin_config_group_dbg_show) (struct pinctrl_dev *pctldev,struct seq_file *s,unsigned selector);void (*pin_config_config_dbg_show) (struct pinctrl_dev *pctldev,struct seq_file *s,unsigned long config);
};

pinmux_ops

设置或获取引脚复用情况，对应硬件是iomux。设置某个pin为某个function，通过set_mux设置function selecter。一个group设置复用状态。

struct pinmux_ops {int (*request) (struct pinctrl_dev *pctldev, unsigned offset);int (*free) (struct pinctrl_dev *pctldev, unsigned offset);int (*get_functions_count) (struct pinctrl_dev *pctldev);const char *(*get_function_name) (struct pinctrl_dev *pctldev,unsigned selector);int (*get_function_groups) (struct pinctrl_dev *pctldev,unsigned selector,const char * const **groups,unsigned *num_groups);/*将指定的pin group（group_selector）设置为指定的function（func_selector）*/int (*set_mux) (struct pinctrl_dev *pctldev, unsigned func_selector,unsigned group_selector);int (*gpio_request_enable) (struct pinctrl_dev *pctldev,struct pinctrl_gpio_range *range,unsigned offset);void (*gpio_disable_free) (struct pinctrl_dev *pctldev,struct pinctrl_gpio_range *range,unsigned offset);int (*gpio_set_direction) (struct pinctrl_dev *pctldev,struct pinctrl_gpio_range *range,unsigned offset,bool input);bool strict;
};

pinctrl_map

pinctrl_map 某个gpio具体的引脚配置和复用状态，由dts中定义，dt_node_to_map函数解析，和具体设备驱动关联。

struct pinctrl_map {//device的名称const char *dev_name;//pin state的名称const char *name;//该map的类型enum pinctrl_map_type type;//pin controller device的名字const char *ctrl_dev_name;union {struct pinctrl_map_mux mux;struct pinctrl_map_configs configs;} data;
};enum pinctrl_map_type {PIN_MAP_TYPE_INVALID,//不需要任何配置，仅仅为了表示state的存在PIN_MAP_TYPE_DUMMY_STATE,//配置管脚复用PIN_MAP_TYPE_MUX_GROUP,//配置pinPIN_MAP_TYPE_CONFIGS_PIN,//配置pin groupPIN_MAP_TYPE_CONFIGS_GROUP,
};struct pinctrl_map_mux {//group的名字const char *group;//function的名字const char *function;
};struct pinctrl_map_configs {//该pin或者pin group的名字const char *group_or_pin;//configuration数组unsigned long *configs;//配置项的个数unsigned num_configs;
};

三、实现流程

linux6.1.11为例，pinctrl系统融入内核设备树解析以及内核设备驱动模型中支持。以zynq为例从dts配置解析入手，了解pinctrl的工作原理。dts中主要关注：

1）pinctrl 子系统：描述系统多少引脚，每个引脚有多少复用情况。

2）I2C、GPIO、SPI等driver默认配置的pinctrl复用设置

《zynq-7000.dtsi》中，如列出i2C和uart的复用配置，其中只是选择了i2c0_10_grp这个pin_group，并且配置为i2c0的复用功能，具体引脚的引脚号等信息是在代码中定义的。

mux 和 conf的作用？

pinctrl0: pinctrl@700 {compatible = "xlnx,pinctrl-zynq";reg = <0x700 0x200>;syscon = <&slcr>;/*设置引脚的复用状态*/pinctrl_i2c0_default: i2c0-default {mux {/*pin_group*/groups = "i2c0_10_grp";/*复用功能为i2c0*/function = "i2c0";};conf {groups = "i2c0_10_grp";bias-pull-up; #上拉电阻slew-rate = <0>; #引脚转换速率io-standard = <1>;};};pinctrl_uart1_default: uart1-default {mux {groups = "uart1_10_grp";function = "uart1";};conf {groups = "uart1_10_grp";slew-rate = <0>;io-standard = <1>;};conf-rx {pins = "MIO49";bias-high-impedance;};conf-tx {pins = "MIO48";bias-disable;};};}

其他驱动如何关联pinctrl以及配置默认引脚复用？

对应驱动中的dts新增如下两个属性，在设备驱动device关联driver时，会解析如下字段，关联pinctrl驱动，并设置引脚复用状态，这里是选择pinctrl_i2c0_default。

&i2c0 {pinctrl-names = "default";pinctrl-0 = <&pinctrl_i2c0_default>;

3.1 驱动注册

《linux-6.1.11\drivers\pinctrl\pinctrl-zynq.c》

构造一个pinctrl_desc结构，然后注册到pinctrl系统中。

static struct pinctrl_desc zynq_desc = {.name = "zynq_pinctrl",.pins = zynq_pins,.npins = ARRAY_SIZE(zynq_pins),.pctlops = &zynq_pctrl_ops,.pmxops = &zynq_pinmux_ops,.confops = &zynq_pinconf_ops,.num_custom_params = ARRAY_SIZE(zynq_dt_params),.custom_params = zynq_dt_params,
#ifdef CONFIG_DEBUG_FS.custom_conf_items = zynq_conf_items,
#endif.owner = THIS_MODULE,
};static int zynq_pinctrl_probe(struct platform_device *pdev){pctrl->pctrl = devm_pinctrl_register(&pdev->dev, &zynq_desc, pctrl);
}

pin引脚定义：

/*定义系统中引脚*/
static const struct pinctrl_pin_desc zynq_pins[] = {PINCTRL_PIN(0,  "MIO0"),PINCTRL_PIN(1,  "MIO1"),...
}/*引脚可选复用功能*/
enum zynq_pinmux_functions {ZYNQ_PMUX_can0,ZYNQ_PMUX_can1,ZYNQ_PMUX_ethernet0,ZYNQ_PMUX_ethernet1,
}/* pin groups 组，每个引脚功能对应的pin脚定义*/
static const unsigned int ethernet0_0_pins[] = {16, 17, 18, 19, 20, 21, 22, 23,24, 25, 26, 27};
static const unsigned int ethernet1_0_pins[] = {28, 29, 30, 31, 32, 33, 34, 35,36, 37, 38, 39};
static const unsigned int mdio0_0_pins[] = {52, 53};
static const unsigned int mdio1_0_pins[] = {52, 53};/*zynq维护的私有数据结构pin_group组信息，关联上述pin脚*/
static const struct zynq_pctrl_group zynq_pctrl_groups[] = {DEFINE_ZYNQ_PINCTRL_GRP(ethernet0_0),DEFINE_ZYNQ_PINCTRL_GRP(ethernet1_0),DEFINE_ZYNQ_PINCTRL_GRP(mdio0_0),DEFINE_ZYNQ_PINCTRL_GRP(mdio1_0),DEFINE_ZYNQ_PINCTRL_GRP(qspi0_0),DEFINE_ZYNQ_PINCTRL_GRP(qspi1_0),DEFINE_ZYNQ_PINCTRL_GRP(qspi_fbclk),DEFINE_ZYNQ_PINCTRL_GRP(qspi_cs1),DEFINE_ZYNQ_PINCTRL_GRP(spi0_0),
}

对应的ops实现这里不展开，具体写寄存器信息。

3.2 具体驱动关联pinctrl

具体i2c、spi等驱动初始化时如何设置引脚复用情况？ dts中定义i2c选择pinctrl_i2c0_default的引脚复用。 pinctrl-names用于表示pinctrl_state，有init、default，init是在驱动初始化的状态，default是默认状态。 pinctrl-0 选择复用情况，这两个属性是pinctrl的标准属性，设备树解析框架中实现，在设备驱动匹配时关联。

&i2c0 {pinctrl-names = "default";pinctrl-0 = <&pinctrl_i2c0_default>;

时机：设备驱动匹配时关联，以及设置默认复用状态。

关键函数：pinctrl_bind_pins

《linux-6.1.11\drivers\base\dd.c》

__driver_probe_device -> really_probe -> pinctrl_bind_pins

解析dts，关联pinctrl_map

调用pinconf_generic_dt_node_to_map_all解析dts。关联pinctrl_i2c0_default的pinctrl_map。

pinctrl_bind_pins -> create_pinctrl -> pinctrl_dt_to_map -> pinconf_generic_dt_node_to_map_all

设置引脚复用

pinctrl_bind_pins -> pinctrl_select_state (选择default state) -> pinctrl_commit_state-> pinmux_disable_setting  (禁用旧的复用)-> pinmux_enable_setting  (设置新复用)-> pinconf_apply_setting  (设置引脚状态)

/*** pinctrl_bind_pins() - called by the device core before probe* @dev: the device that is just about to probe*/
int pinctrl_bind_pins(struct device *dev)
{int ret;if (dev->of_node_reused)return 0;dev->pins = devm_kzalloc(dev, sizeof(*(dev->pins)), GFP_KERNEL);if (!dev->pins)return -ENOMEM;dev->pins->p = devm_pinctrl_get(dev);if (IS_ERR(dev->pins->p)) {dev_dbg(dev, "no pinctrl handle\n");ret = PTR_ERR(dev->pins->p);goto cleanup_alloc;}dev->pins->default_state = pinctrl_lookup_state(dev->pins->p,PINCTRL_STATE_DEFAULT);if (IS_ERR(dev->pins->default_state)) {dev_dbg(dev, "no default pinctrl state\n");ret = 0;goto cleanup_get;}dev->pins->init_state = pinctrl_lookup_state(dev->pins->p,PINCTRL_STATE_INIT);if (IS_ERR(dev->pins->init_state)) {/* Not supplying this state is perfectly legal */dev_dbg(dev, "no init pinctrl state\n");ret = pinctrl_select_state(dev->pins->p,dev->pins->default_state);} else {ret = pinctrl_select_state(dev->pins->p, dev->pins->init_state);}if (ret) {dev_dbg(dev, "failed to activate initial pinctrl state\n");goto cleanup_get;}#ifdef CONFIG_PM/** If power management is enabled, we also look for the optional* sleep and idle pin states, with semantics as defined in* <linux/pinctrl/pinctrl-state.h>*/dev->pins->sleep_state = pinctrl_lookup_state(dev->pins->p,PINCTRL_STATE_SLEEP);if (IS_ERR(dev->pins->sleep_state))/* Not supplying this state is perfectly legal */dev_dbg(dev, "no sleep pinctrl state\n");dev->pins->idle_state = pinctrl_lookup_state(dev->pins->p,PINCTRL_STATE_IDLE);if (IS_ERR(dev->pins->idle_state))/* Not supplying this state is perfectly legal */dev_dbg(dev, "no idle pinctrl state\n");
#endifreturn 0;/** If no pinctrl handle or default state was found for this device,* let's explicitly free the pin container in the device, there is* no point in keeping it around.*/
cleanup_get:devm_pinctrl_put(dev->pins->p);
cleanup_alloc:devm_kfree(dev, dev->pins);dev->pins = NULL;/* Return deferrals */if (ret == -EPROBE_DEFER)return ret;/* Return serious errors */if (ret == -EINVAL)return ret;/* We ignore errors like -ENOENT meaning no pinctrl state */return 0;
}