Linux BSP实战课（pin 驱动篇）：pinctrl 驱动和client device使用过程

通过前面硬件原理的介绍，我们知道配置一个pin需要经过mux控制寄存器和pad控制寄存器，对于输入引脚的配置，还需要另外配置输入选择寄存器。那么把这些概念用软件来实现就是 pin 驱动控制器的本质。在了解驱动前我们先来看几个关键结构体。

pinctrl_desc 结构体

使用 struct pinctrl_desc 抽象一个 pin controller，包含控制器的名字、pin脚的数量、pinmux功能、pinconf功能和pinctl功能。其中结构体 pinmux_ops 和 pinconf_ops 分别用于配置mux模式和pad电气属性，而 pinctrl_ops 则是控制一组pin，如uart、i2c、spi等外设的pin组。该结构的定义如下:

struct pinctrl_desc {
 const char *name;//pin控制器名字
 const struct pinctrl_pin_desc *pins;//描述芯片的物理引脚pad资源
 unsigned int npins;
 const struct pinctrl_ops *pctlops;//全局pin配置
 const struct pinmux_ops *pmxops; //mux配置
 const struct pinconf_ops *confops;//电气属性配置
 struct module *owner;
 bool link_consumers;
};

其中：

pins

变量 pins 和 npins 把系统中所有的 pin 描述出来，并建立索引。驱动为了和具体的 pin 对应上，再将这些描述的这些 pin 组织成一个 struct pinctrl_pin_desc 类型的数组，该类型的定义为：

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

SoC中，有时需要将很多 pin 组合在一起，以实现特定的功能，例如 eqos 接口、i2c 接口等。因此 pin controller 需要以 group 为单位，访问、控制多个 pin，这就是 pin groups。

struct group_desc {
 const char *name;
 int *pins;
 int num_pins;
 void *data;
};

在设备树里表示就是：

pinctrl_eqos: eqosgrp {
 fsl,pins = <
  MX93_PAD_ENET1_MDC__ENET_QOS_MDC   0x57e
  MX93_PAD_ENET1_MDIO__ENET_QOS_MDIO   0x57e
  MX93_PAD_ENET1_RD0__ENET_QOS_RGMII_RD0   0x57e
  MX93_PAD_ENET1_RD1__ENET_QOS_RGMII_RD1   0x57e
  MX93_PAD_ENET1_RD2__ENET_QOS_RGMII_RD2   0x57e
  MX93_PAD_ENET1_RD3__ENET_QOS_RGMII_RD3   0x57e
  MX93_PAD_ENET1_RXC__CCM_ENET_QOS_CLOCK_GENERATE_RX_CLK 0x5fe
  MX93_PAD_ENET1_RX_CTL__ENET_QOS_RGMII_RX_CTL  0x57e
  MX93_PAD_ENET1_TD0__ENET_QOS_RGMII_TD0   0x57e
  MX93_PAD_ENET1_TD1__ENET_QOS_RGMII_TD1   0x57e
  MX93_PAD_ENET1_TD2__ENET_QOS_RGMII_TD2   0x57e
  MX93_PAD_ENET1_TD3__ENET_QOS_RGMII_TD3   0x57e
  MX93_PAD_ENET1_TXC__CCM_ENET_QOS_CLOCK_GENERATE_TX_CLK 0x5fe
  MX93_PAD_ENET1_TX_CTL__ENET_QOS_RGMII_TX_CTL  0x57e
 >;
};

pinctrl core 会在 struct pinctrl_ops 中抽象出三个回调函数，用来获取 pin groups 相关信息，如下：

pinctrl_ops

struct pinctrl_ops {
  //获取系统中pin groups的个数，后续的操作，将以相应的索引为单位（类似数组的下标，个数为数组的大小）
 int (*get_groups_count) (struct pinctrl_dev *pctldev);
  //获取指定group（由索引selector指定）的名称
 const char *(*get_group_name) (struct pinctrl_dev *pctldev, unsigned selector);
  //获取指定group的所有pins（由索引selector指定），结果保存在pins（指针数组）和num_pins（指针）中
 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);
  //用于将device tree中的pin state信息转换为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);
};

pinmux_ops

为了兼容不同的应用场景，有很多管脚可以配置为不同的功能，例如A和B两个管脚，既可以当作普通的GPIO使用，又可以配置为I2C的的SCL和SDA，也可以配置为UART的TX和RX，这称作管脚的复用（简称 pin mux）。使用 struct pinmux_ops 来抽象 pin mux 有关的操作，如下：

struct pinmux_ops {
  //检查某个pin是否已作它用，用于管脚复用时的互斥
 int (*request) (struct pinctrl_dev *pctldev, unsigned offset);
  //request的反操作
 int (*free) (struct pinctrl_dev *pctldev, unsigned offset);
  //获取系统中function的个数
 int (*get_functions_count) (struct pinctrl_dev *pctldev);
  //获取指定function的名称
 const char *(*get_function_name) (struct pinctrl_dev *pctldev, unsigned selector);
  //获取指定function所占用的pin group
 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);
  //以下是gpio相关的操作
 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);
  //为true时，说明该pin controller不允许某个pin作为gpio和其它功能同时使用
 bool strict;
};

pinconf_ops

除了上面的 pin 和 pin group，有些管脚可以配置，比如上拉，下拉，高阻等。具体体现在 struct pinconf_ops 数据结构中，如下：

struct pinconf_ops {
#ifdef CONFIG_GENERIC_PINCONF
 bool is_generic;
#endif
  //获取指定 pin 的当前配置，保存在 config 指针中
 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);
  //设置指定pin group的配置项
 int (*pin_config_group_set) (struct pinctrl_dev *pctldev, unsigned selector, unsigned long *configs, unsigned num_configs);
  ......

pin state

根据前面的描述，pinctrl driver 抽象出来了一些离散的对象，并实现了这些对象的控制和配置方式。然后我们回到某一个具体的 device 上（如 lpuart，usdhc）。一个设备在某一状态下（如工作状态、休眠状态、等等），所使用的pin（pin group）、pin（pin group）的 function 和 configuration，是唯一确定的。所以固定的组合可以确定固定的状态，在设备树里用 pinctrl-names 指明状态名字，pinctrl-x 指明状态引脚。

pin map

pin state 有关的信息是通过 pin 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,
 //配置pin
 PIN_MAP_TYPE_CONFIGS_PIN,
 //配置pin group
 PIN_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;
};

pinctrl driver 确定了 pin map 各个字段的格式之后，就可以在 dts 文件中维护 pin state 以及相应的 mapping table。pinctrl core 在初始化的时候，会读取并解析 dts，并生成 pin map。

而各个 client device 可以在自己的 dts node 中，直接引用 pinctrl driver 定义的 pin state，并在设备驱动的相应的位置，调用 pinctrl subsystem 提供的 API（pinctrl_lookup_state，pinctrl_select_state），active 或者 deactive 这些 state。

pin controller 驱动初始化

pin controller 的设备树如下所示：

iomuxc: pinctrl@443c0000 {
 compatible = "fsl,imx93-iomuxc";
 reg = <0x443c0000 0x10000>;
 status = "okay";
};

&iomuxc {
 pinctrl_eqos: eqosgrp {
  fsl,pins = <
   ......
  >;
 };

 pinctrl_eqos_sleep: eqosgrpsleep {
  fsl,pins = <
   ......
  >;
 };

 pinctrl_fec: fecgrp {
  fsl,pins = <
   ......
  >;
 };

 pinctrl_fec_sleep: fecsleepgrp {
  fsl,pins = <
   ......
  >;
 };
 ......
 pinctrl_sai1: sai1grp {
  fsl,pins = <
   ......
  >;
 };

 pinctrl_sai1_sleep: sai1grpsleep {
  fsl,pins = <
   ......
  >;
 };
 ......
};

pin controller驱动的初始化大致如下：