一文搞懂 | Linux pinctrl/gpio子系统
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 驱动初始化
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
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 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-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 引脚，然后设置方向，读值、写值。
比如在 Linux 开发过程中，先申请了GPIO，再申请内存；如果内存申请失败，那么在返回之前就需要先释放GPIO资源。如果使用devm的相关函数，在内存申请失败时可以直接返回：设备的销毁函数会自动地释放已经申请了的GPIO资源。
以上面的设备 max9286_mipi 为例，它的驱动实现如下：
sysfs 访问方法
先确定某个GPIO Controller的基准引脚号(base number)，再计算出某个引脚的号码。
“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 控制 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
