一文搞懂 | Linux pinctrl/gpio子系统

发表于 2年以前 | 总阅读数：536 次

pinctrl 子系统和 gpio 子系统虽然难度不大，但在内核里的使用率非常高，本文争取一次性把相关内容介绍一遍。

pinctrl

数据结构

使用 struct pinctrl_desc 抽象一个 pin controller，该结构的定义如下:

struct pinctrl_desc {
 const char *name;
 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;
#ifdef CONFIG_GENERIC_PINCONF
 unsigned int num_custom_params;
 const struct pinconf_generic_params *custom_params;
 const struct pin_config_item *custom_conf_items;
#endif
};

pins

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

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

pin groups

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

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

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

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);
};

group 的组织方式是由驱动决定的。

pin configuration

除了上面的 pin 和 pin group，有些管脚可以配置，比如上拉，下拉，高阻等。pin configuration 来封装这些功能，具体体现在 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 mux

为了兼容不同的应用场景，有很多管脚可以配置为不同的功能，例如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;
};

pin state

根据前面的描述，pinctrl driver 抽象出来了一些离散的对象：pin（pin group）、function、configuration，并实现了这些对象的控制和配置方式。然后我们回到某一个具体的 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。

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

pin controller 驱动初始化

我们再来回忆下 pin 控制器的描述符：

struct pinctrl_desc {
 const char *name;
 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;
#ifdef CONFIG_GENERIC_PINCONF
 unsigned int num_custom_params;
 const struct pinconf_generic_params *custom_params;
 const struct pin_config_item *custom_conf_items;
#endif
};

pin 控制器描述符中包括了三类操作函数：pctlops 是一些全局的控制函数；pmxops 是复用引脚相关的操作函数；confops操作函数是用来配置引脚的特性。pin 控制器驱动的初始化主要是注册这三类函数的回调。

struct pinctrl_ops *pctlops

callback函数描述get_groups_count该pin controller支持多少个pin groupget_group_name给定一个selector（index），获取指定pin group的nameget_group_pins给定一个selector（index），获取该pin group中pin的信息（该pin group包括多少个pin，每个pin的ID是什么）pin_dbg_showdebug fs的callback接口dt_node_to_map分析一个pin configuration node并把分析的结果保存成mapping table entry，每一个entry表示一个setting（一个功能复用设定，或者电气特性设定）dt_free_map上面函数的逆函数

struct pinmux_ops *pmxops

callback函数	描述
get_groups_count	该pin controller支持多少个pin group
get_group_name	给定一个selector（index），获取指定pin group的name
get_group_pins	给定一个selector（index），获取该pin group中pin的信息（该pin group包括多少个pin，每个pin的ID是什么）
pin_dbg_show	debug fs的callback接口
dt_node_to_map	分析一个pin configuration node并把分析的结果保存成mapping table entry，每一个entry表示一个setting（一个功能复用设定，或者电气特性设定）
dt_free_map	上面函数的逆函数

struct pinconf_ops *confops

callback函数	描述
get_functions_count	返回pin controller支持的function的数目
get_function_name	给定一个selector（index），获取指定function的name
get_function_groups	给定一个selector（index），获取指定function的pin groups信息
set_mux	将指定的pin group（group_selector）设置为指定的function（func_selector）

pinctrl subsystem 的整体流程

pinctrl driver 根据 pin controller 的实际情况，定义 struct pinctrl_desc（包括pin/pin group 的抽象，function 的抽象，pinconf、pinmux 的 operation API 实现，dt_node_to_map 的实现，等等），并注册到 kernel 中。
pinctrl driver 在 pin controller的 dts node 中，根据自己定义的格式，描述每个 device 的所有 pin state。如下所示：

&iomuxc1 {
 ......
    pinctrl_lpuart5: lpuart5grp {
            fsl,pins = <
                    MX8ULP_PAD_PTF14__LPUART5_TX    0x3
                    MX8ULP_PAD_PTF15__LPUART5_RX    0x3
            >;
    };
 ......
 pinctrl_usdhc0: usdhc0grp {
            fsl,pins = <
                    MX8ULP_PAD_PTD1__SDHC0_CMD      0x3
                    MX8ULP_PAD_PTD2__SDHC0_CLK      0x10002
                    MX8ULP_PAD_PTD10__SDHC0_D0      0x3
                    MX8ULP_PAD_PTD9__SDHC0_D1       0x3
                    MX8ULP_PAD_PTD8__SDHC0_D2       0x3
                    MX8ULP_PAD_PTD7__SDHC0_D3       0x3
                    MX8ULP_PAD_PTD6__SDHC0_D4       0x3
                    MX8ULP_PAD_PTD5__SDHC0_D5       0x3
                    MX8ULP_PAD_PTD4__SDHC0_D6       0x3
                    MX8ULP_PAD_PTD3__SDHC0_D7       0x3
                    MX8ULP_PAD_PTD11__SDHC0_DQS     0x10002
            >;
    };
 ......
}

3 . 相应的 consumer driver 可以在自己的 dts node 中，引用 pinctrl driver 所定义的 pin state，如下所示：

&lpuart5 {
        /* console */
        pinctrl-names = "default", "sleep";
        pinctrl-0 = <&pinctrl_lpuart5>;
        pinctrl-1 = <&pinctrl_lpuart5>;
        status = "okay";
};

&usdhc0 {
        pinctrl-names = "default", "state_100mhz", "state_200mhz", "sleep";
        pinctrl-0 = <&pinctrl_usdhc0>;
        pinctrl-1 = <&pinctrl_usdhc0>;
        pinctrl-2 = <&pinctrl_usdhc0>;
        pinctrl-3 = <&pinctrl_usdhc0>;
        non-removable;
        bus-width = <8>;
        status = "okay";
};

4 . consumer driver 在需要的时候，可以调用 pinctrl_get/devm_pinctrl_get 接口，获得一个 pinctrl handle（struct pinctrl类型的指针）。在 pinctrl get 的过程中，解析 consumer device 的 dts node，找到相应的 pin state，进行调用 pinctrl driver 提供的 dt_node_to_map 接口，解析 pin state 并转换为 pin map。

例子

上图中，左边是 pin controller 节点，右边是 client device 节点。

pin state

对于一个“client device”来说，比如对于一个 UART 设备，它有多个“状态”：default、sleep 等，那对应的引脚也有这些状态。比如当这个设备处于 default 状态时，pinctrl 子系统会自动根据上述信息把所用引脚复用为 uart0 功能。当这这个设备处于 sleep 状态时，pinctrl 子系统会自动根据上述信息把所用引脚配置为高电平。

groups 和 function

一个设备会用到一个或多个引脚，这些引脚就可以归为一组 group。这些引脚可以复用为某个功能 function。当然，一个设备可以用到多组多功能引脚，比如A1、A2两组引脚，A1组复用为F1功能，A2组复用为F2功能。

sysfs 访问方法

gpio

数据结构

每个 GPIO 控制器用一个 gpio_device 来表示:

struct gpio_device {
 //它是系统中第几个GPIO控制器
 int   id;
 struct device  dev;
 struct cdev  chrdev;
 struct device  *mockdev;
 struct module  *owner;
 //含有各类操作函数
 struct gpio_chip *chip;
 //每一个gpio引脚用一个gpio_desc来表示
 struct gpio_desc *descs;
 //这些GPIO的号码基值
 int   base;
 //这个GPIO控制器支持多少个GPIO
 u16   ngpio;
 //标签，名字
 char   *label;
 void   *data;
 struct list_head        list;
 ......
};

用 gpio_chip 来定义控制引脚和中断相关的函数：

struct gpio_chip {
 const char  *label;
 struct gpio_device *gpiodev;
 struct device  *parent;
 struct module  *owner;

 //控制引脚的函数,中断相关的函数
 int   (*request)(struct gpio_chip *chip,
      unsigned offset);
 void   (*free)(struct gpio_chip *chip,
      unsigned offset);
 int   (*get_direction)(struct gpio_chip *chip,
      unsigned offset);
 int   (*direction_input)(struct gpio_chip *chip,
      unsigned offset);
 int   (*direction_output)(struct gpio_chip *chip,
      unsigned offset, int value);
 int   (*get)(struct gpio_chip *chip,
      unsigned offset);
 void   (*set)(struct gpio_chip *chip,
      unsigned offset, int value);
 void   (*set_multiple)(struct gpio_chip *chip,
      unsigned long *mask,
      unsigned long *bits);
 int   (*set_config)(struct gpio_chip *chip,
           unsigned offset,
           unsigned long config);
 int   (*to_irq)(struct gpio_chip *chip,
      unsigned offset);

 void   (*dbg_show)(struct seq_file *s,
      struct gpio_chip *chip);
 //GPIO控制器中引脚的号码基值
 int   base;
 //GPIO控制器中引脚的个数
 u16   ngpio;
 //每个引脚的名字
 const char  *const *names;
 bool   can_sleep;
 ......
};

每一个 gpio 引脚用一个 gpio_desc 来表示:

struct gpio_desc {
 //属于哪个 GPIO 控制器
 struct gpio_device *gdev;
 unsigned long  flags;
/* flag symbols are bit numbers */
#define FLAG_REQUESTED 0
#define FLAG_IS_OUT 1
#define FLAG_EXPORT 2 /* protected by sysfs_lock */
#define FLAG_SYSFS 3 /* exported via /sys/class/gpio/control */
#define FLAG_ACTIVE_LOW 6 /* value has active low */
#define FLAG_OPEN_DRAIN 7 /* Gpio is open drain type */
#define FLAG_OPEN_SOURCE 8 /* Gpio is open source type */
#define FLAG_USED_AS_IRQ 9 /* GPIO is connected to an IRQ */
#define FLAG_IS_HOGGED 11 /* GPIO is hogged */
#define FLAG_SLEEP_MAY_LOOSE_VALUE 12 /* GPIO may loose value in sleep */

 /* Connection label */
 //一般等于 gpio_chip 的 label
 const char  *label;
 /* Name of the GPIO */
 //引脚名
 const char  *name;
};

设备树

GPIO一般都分为几组，每组中有若干个引脚。所以在使用GPIO子系统之前，就要先确定它所在的组以及在组中的哪一个。在设备树中，“GPIO组” 就是一个 GPIO Controller，这通常都由芯片厂家设置好。我们要做的是找到它的名字，比如“gpio1”，然后指定要用它里面的哪个引脚，比如 <&gpio1 0>。

“gpio-controller”表示这个节点是一个GPIO Controller，它下面有很多引脚。

“#gpio-cells = <2>”表示这个控制器下每一个引脚要用2个32位的数(cell)来描述。用第1个cell来表示哪一个引脚，用第2个cell来表示有效电平：GPIO_ACTIVE_HIGH(高电平有效)，GPIO_ACTIVE_LOW(低电平有效)。

怎么引用某个引脚呢？在自己的设备节点中使用属性"[name]-gpios"，示例如下：

gpio controller 驱动

gpio client 驱动

GPIO 子系统有两套接口：基于描述符的(descriptor-based)、老的(legacy)。前者的函数都有前缀 “gpiod_”，它使用 gpio_desc 结构体来表示一个引脚；后者的函数都有前缀 “gpio_”，它使用一个整数来表示一个引脚。

要操作一个引脚，首先要 get 引脚，然后设置方向，读值、写值。

建议使用“devm_”版本的相关函数。有前缀“devm_”的含义是“设备资源管理”(Managed Device Resource)，这是一种自动释放资源的机制。它的思想是“资源是属于设备的，设备不存在时资源就可以自动释放”。

比如在 Linux 开发过程中，先申请了GPIO，再申请内存；如果内存申请失败，那么在返回之前就需要先释放GPIO资源。如果使用devm的相关函数，在内存申请失败时可以直接返回：设备的销毁函数会自动地释放已经申请了的GPIO资源。

以上面的设备 max9286_mipi 为例，它的驱动实现如下：

sysfs 访问方法

先确定某个GPIO Controller的基准引脚号(base number)，再计算出某个引脚的号码。

然后进入某个gpiochip目录，查看文件label的内容，根据 label 的内容对比设备树，就可以知道这对应哪一个 GPIO Controller。比如用上面的例子，通过对比设备树可知 gpiochip448 对应 gpio1。

因为 pin number = base + offset，所以 GPIO1_27 的号码是 448 + 27 = 475，那么通过 sys 可以做如下操作。

“echo 475 > /sys/class/gpio/export

echo in > /sys/class/gpio/gpio475/direction

cat /sys/class/gpio/gpio475/value

echo 475 > /sys/class/gpio/unexport

”

pinctrl subsystem 和 gpio subsysem 之间的耦合

pinctrl subsystem 管理系统的所有管脚，GPIO 是这些管脚的用途之一，因此 gpio subsystem 应该是 pinctrl subsystem 的 backend。在使用 GPIO 的时候，都需要向系统的 pinctrl subsystem 申请管脚，并将管脚配置为 GPIO 功能。

内核也提供了通过 pinctrl 控制 gpio 的接口：

“static inline int pinctrl_request_gpio(unsigned gpio);

static inline void pinctrl_free_gpio(unsigned gpio);

static inline int pinctrl_gpio_direction_input(unsigned gpio);

static inline int pinctrl_gpio_direction_output(unsigned gpio);

”

pinctrl subsystem会维护一个gpio number到pin number的map(gpio range)，将gpio subsystem传来的gpio number转换为pin number之后，调用struct pinmux_ops中有关的回调函数即可：

struct pinmux_ops {
        ...
        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);
};

gpio ranges

当 gpio driver 需要使用某一个 gpio 的时候，可以在 struct gpio_chip 的 request 函数中，调用 pinctrl core 提供的 pinctrl_request_gpio 接口（参数是gpio编号），然后 pinctrl core 会查寻 gpio ranges 链表，将 gpio 编号转换成 pin 编号，然后调用 pinctrl 的相应接口（参数是pin编号），申请该 pin 的使用。