gpio子系统和pinctrl子系统（上）

前言

　　随着内核的发展，linux驱动框架在不断的变化。很早很早以前，出现了gpio子系统，后来又出现了pinctrl子系统。在网上很难看到一篇讲解这类子系统的文章。就拿gpio操作来说吧，很多时候都是简单的调用gpio子系统提供的api，然后根据sdk说明文档写明的gpio号传参数，至于里面的工作过程对于驱动工程师而言就像个黑盒子。当我们自己设计的板子和demo板有很大变动时，问题就出现了。首先遇到的是怎么配置pin(是基于设备树还是不基于设备树，基于设备树的话，怎么修改设备树关于pinctrl部分的内容，里面各个字段什么意思，怎么改)，然后是在哪里配置pin（内核部分有哪些需要相应修改，还是不需要一点修改呢），接着就是怎么调试等等。我想只有清楚了尽量多的gpio子系统和pinctrl子系统细节，才会更快更好的完成这些工作。有些平台的实现没有使用内核提供的pinctrl子系统，而是继续采用在内核提供pinctrl子系统前自己实现的那套机制来pinmux操作，如omap，有些平台则基于pinctrl子系统来实现pinmux、pinconf的控制。本文以gpio子系统为入口慢慢深入，最后分析pinctrl子系统。

如果有错误的地方，欢迎大家直接指出

gpio子系统

　　gpio子系统帮助我们管理整个系统gpio的使用情况，同时通过sys文件系统导出了调试信息和应用层控制接口。它内部实现主要提供了两类接口，一类给bsp工程师，用于注册gpio chip（也就是所谓的gpio控制器驱动），另一部分给驱动工程师使用，为驱动工程师屏蔽了不同gpio chip之间的区别，驱动工程师调用的api的最终操作流程会导向gpio对应的gpio chip的控制代码，也就是bsp的代码。

gpio子系统核心实现分析

gpio子系统的内容在drivers/gpio文件夹下，主要文件有：　

devres.c

gpiolib.c

gpiolib-of.c

gpiolib-acpi.c

gpio-xxx.c

devres.c是针对gpio api增加的devres机制的支持，devres机制讲解请参考另一篇博文，gpiolib.c是gpio子系统的核心实现，gpiolib-of.c是对设备树的支持，gpiolib-acpi.c和acpi相关，不分析（acpi还未深入了解^_），最后情景分析的时候，会找一个平台的gpio-xxx.c来分析。

从驱动工程师使用的api开始分析吧！也分两代，legacy的api主要会用到的接口有（现在推荐采用新的，基于描述符的api）：

gpio_request、gpio_free

gpio_direction_input、gpio_direction_output

gpio_to_irq

gpio_export

一般的流程：

//请求一个/一组gpio
gpio_request/devm_gpio_request、gpio_request_one/devm_gpio_request_one、gpio_request_array   ---------<1>
...
//设置gpio方向为输入/输出
gpio_direction_input或者gpio_direction_output        ---------<2>
...
//将该gpio通过sys文件系统导出，应用层可以通过文件操作gpio
gpio_export                                          ---------<3>
...
//如果gpio为输入，获取gpio值，如果gpio为输出，可以设置gpio高低电平
gpio_get_value、gpio_set_value                       ---------<4>
...
//将gpio转为对应的irq，然后注册该irq的中断handler
request_irq(gpio_to_irq(gpio_num)...)                ---------<5>
...
//释放请求的一个或者一组gpio
gpio_free/devm_gpio_free、gpio_free_array                           ---------<6>
...

下面一个个来分析吧！

<1> 以gpio_request为例，gpio_request_one、gpio_request_array是它的扩展，devm_为前缀的是gpio devres机制的实现。

int gpio_request(unsigned gpio, const char *label)

参数为gpio号和为该gpio指定的表签名，具体gpio号是多少，可以通过sdk开发包说明文档查看，或者查看设备树文件，再或者基于bank数量推算（当然，这样可能不准），实在没办法的话，瞄一眼gpio chip驱动的代码吧！gpio_request主要做了以下动作：

1. 检查是否已经被申请，没有的话，标记为已申请
2. 填充label到该pin数据结构，用于debug
3. 如果chip　driver提供了request回调，调用它
4. 如果chip　driver提供了get_direction回调，调用它,通过它更新pin数据结构，标明gpio方向

gpio_request_one多一个flags参数，通过该参数，可以指定GPIOF_OPEN_DRAIN、GPIOF_OPEN_SOURCE、GPIOF_DIR_IN、GPIOF_EXPORT等标志，如果指定了GPIOF_DIR_IN，那么后面就不需要自己再额外调用gpio_direction_input或者gpio_direction_output了，如果指定了GPIOF_EXPORT，后面就不需要自己调用gpio_export了。

gpio_request_array是对gpio_request_one的封装，用于处理同时申请多个gpio的情形。

<2> gpio_direction_input或者gpio_direction_output用来设置该gpio为输入还是输出，它们主要是回调gpio chip driver提供的direction_input或者direction_output来设置该gpio寄存器为输入、输出。

<3> gpio_export主要用于调试，它会将该gpio的信息通过sys文件系统导出，这样应用层可以直接查看状态、设置状态等。

<4> gpio_get_value或者gpio_set_value和input、output类似，如果为输入，获取该gpio的值，如果为输出，设置该gpio的值，内部也是调用gpio chip driver提供的get、set。

<5> gpio_to_irq用于获取该gpio对应的中断号，这个需要设备树里的该gpio节点描述使用哪个中断号（并不是所有的gpio都可以触发中断的）。它里面的实现就是回调gpio chip driver提供的to_irq。

<6>　gpio_free就不用说了啦，gpio_request的逆操作。

要使用以上接口，需要#include <linux/gpio.h>，且还有一组用于允许睡眠场景的api没有给出，更多相关的说明可以参考Documentation/gpio/gpio-legacy.txt

上面的分析没有深入的代码层，之所以没有深入分析，是因为打算放到后面分析基于描述符api时啦！其实，legacy gpio 大部分api就是基于描述符api来实现的。最新的,基于描述符一般的流程：

...
//请求第一个/指定某一个gpio desc，该返回值用于后面的操作
gpiod_get/devm_gpiod_get、gpiod_get_index/devm_gpiod_get_index   ---------<1>
...
//设置gpio方向为输入/输出
gpiod_direction_input或者gpiod_get_direction                 ---------<2>
...
//将该gpio通过sys文件系统导出，应用层可以通过文件操作gpio
gpiod_export                                                ---------<3>
...
//如果gpio为输入，获取gpio值，如果gpio为输出，可以设置gpio高低电平
gpiod_get_value或者gpiod_set_value                           ---------<4>
...
//将gpio转为对应的irq，然后注册该irq的中断handler
request_irq(gpiod_to_irq(gpio_desc)...)                     ---------<5>
...
//释放请求的一个或者一组gpio
gpiod_put/devm_gpiod_put                                    ---------<6>
...

还是下面一个个来分析吧！

<1> gpiod_get内部的处理和gpio_request一样，不过输入参数变为char *con_id，这个需要从设备树文件里查看到，除此之外，我们还可以在设备树文件里添加参数（GPIO_ACTIVE_LOW、GPIO_OPEN_DRAIN、GPIO_OPEN_SOURCE）来触发该接口内部设置gpio，具体的参数格式和具体的gpio chip driver有关，一般可以在/Documentation/devicetree/bindings/gpio里找到对应平台的。举个例子：

        row-gpios = <&gpio1 25 GPIO_ACTIVE_HIGH     /* Bank1, pin25 */
                 &gpio1 26 GPIO_ACTIVE_HIGH     /* Bank1, pin26 */
                 &gpio1 27 GPIO_ACTIVE_HIGH>;   /* Bank1, pin27 */

struct gpio_desc *__must_check gpiod_get(struct device *dev, const char *con_id)

对应上面的设备树描述，con_id就是row了，获取的也会是第一个设置，即gpio1 25 GPIO_ACTIVE_HIGH，如果想获取第二个设置，我们得通过gpiod_get_index，并将输入参数idx设置为１。

<2> gpiod_direction_input和gpio_direction_input功能一样，实际上gpio_direction_input仅仅简单封装了gpiod_direction_input，不再描述。

<3> gpiod_export 同上

<4> gpiod_get_value 同上

<5> gpiod_to_irq 同上

<6> gpiod_put 同上

要使用以上接口，需要#include <linux/gpio/consumer.h>，且还有一组用于允许睡眠场景的api没有给出，更多相关的说明可以参考Documentation/gpio/consumer.txt

下面简单分析下gpio子系统内部实现：

1> gpio chip driver的初始化

gpio子系统提供了两层接口，一层给上层驱动工程师调用，一层给下层bsp工程师调用。上层使用前，当然先得bsp工程师完成对应的动作。先看一张网上的截图：

bsp工程师通过gpiochip_add将gpio chip添加到gpio子系统中，下面就分析它：

int gpiochip_add(struct gpio_chip *chip)
{
	unsigned long	flags;
	int		status = 0;
	unsigned	id;
	int		base = chip->base;

	//如果指定了base，也就是指定了启示gpio号，需要校验下chip的所有gpio是否有效
    //这里会用到ARCH_NR_GPIOS宏，它可以在配置的时候，通过CONFIG_ARCH_NR_GPIO修改，
    //否则采用默认值256
	if ((!gpio_is_valid(base) || !gpio_is_valid(base + chip->ngpio - 1))
			&& base >= 0) {
		status = -EINVAL;
		goto fail;
	}

	spin_lock_irqsave(&gpio_lock, flags);

	//如果没有指定base，那么需要基于该chip的gpio数量在系统支持的gpio范围里找一段区间给该chip
	if (base < 0) {
		base = gpiochip_find_base(chip->ngpio);
		if (base < 0) {
			status = base;
			goto unlock;
		}
		chip->base = base;
	}

	//到这里的时候，说明一切正常，把它加入到全局的gpiochip链表中去吧，注意，加入的时候会基于base排序
    //这也保证了gpiochip_find_base的实现
	status = gpiochip_add_to_list(chip);

	//如果加入成功，最后一步就是初始化该chip对应的那些gpio了
	if (status == 0) {
		chip->desc = &gpio_desc[chip->base];

		for (id = 0; id < chip->ngpio; id++) {
			struct gpio_desc *desc = &chip->desc[id];
            //将该chip对应的那些gpio对应的数据结构desc初始化，指向拥有它的chip
			desc->chip = chip;

			/* REVISIT:  most hardware initializes GPIOs as
			 * inputs (often with pullups enabled) so power
			 * usage is minimized.  Linux code should set the
			 * gpio direction first thing; but until it does,
			 * and in case chip->get_direction is not set,
			 * we may expose the wrong direction in sysfs.
			 */
            //如果chip driver没有指定chip->direction_input，意味着不是输入，那就设置为输出咯
			desc->flags = !chip->direction_input
				? (1 << FLAG_IS_OUT)
				: 0;
		}
	}

	spin_unlock_irqrestore(&gpio_lock, flags);

#ifdef CONFIG_PINCTRL
	//这里在配置了pinctrl的时候，会初始化它，后面会用到
	INIT_LIST_HEAD(&chip->pin_ranges);
#endif

	//初始化设备树相关的信息，后面会详细讲一下这部分
	of_gpiochip_add(chip);
    //acpi方式的先忽略吧
	acpi_gpiochip_add(chip);

	if (status)
		goto fail;

	//将该gpiochip导出到sys，用于调试和应用层直接操作
	status = gpiochip_export(chip);
	if (status)
		goto fail;

	pr_debug("%s: registered GPIOs %d to %d on device: %s\n", __func__,
		chip->base, chip->base + chip->ngpio - 1,
		chip->label ? : "generic");

	return 0;

unlock:
	spin_unlock_irqrestore(&gpio_lock, flags);
fail:
	/* failures here can mean systems won't boot... */
	pr_err("%s: GPIOs %d..%d (%s) failed to register\n", __func__,
		chip->base, chip->base + chip->ngpio - 1,
		chip->label ? : "generic");
	return status;
}

还是以zynq平台为例，看看输入参数struct gpio_chip *chip的初始化过程：

chip->label = "zynq_gpio";
chip->owner = THIS_MODULE;
chip->dev = &pdev->dev;
chip->get = zynq_gpio_get_value;
chip->set = zynq_gpio_set_value;
chip->request = zynq_gpio_request;
chip->free = zynq_gpio_free;
chip->direction_input = zynq_gpio_dir_in;
chip->direction_output = zynq_gpio_dir_out;
chip->to_irq = zynq_gpio_to_irq;
chip->dbg_show = NULL;
chip->base = 0;		/* default pin base */
chip->ngpio = ZYNQ_GPIO_NR_GPIOS;
chip->can_sleep = 0;

get、set、request、free、direction_input、direction_output、to_irq这几个回调应该很清楚了，也知道是哪几个接口调用的它们了吧，另外几个关键的参数base和ngpio在上面的gpiochip_add里应该也已经清楚了它们的重要作用了吧！

of_gpiochip_add会处理gpio chip设备树相关的东西：

void of_gpiochip_add(struct gpio_chip *chip)
{
	if ((!chip->of_node) && (chip->dev))
		chip->of_node = chip->dev->of_node;

	if (!chip->of_node)
		return;

	//如果没有指定of_xlate，那给一个默认的吧！of_xlate用于解析设备树里gpio属性
    //不同的soc可能需要不同的解析方法，但是如果没有什么特别，那就用默认的解析吧
    //当前设备树的节点里支持两种格式的属性，一种是xxx-gpios，另一种就直接是gpios
    //如前文中用到的row-gpios就是一种
	if (!chip->of_xlate) {
		chip->of_gpio_n_cells = 2;
		chip->of_xlate = of_gpio_simple_xlate;
	}

	//这一步就是与pinctrl子系统打交道啦！后面会简单分析下它都做了什么　
    //等到讲pinctrl子系统的时候就更加清楚了
	of_gpiochip_add_pin_range(chip);
    //增加该节点引用计数
	of_node_get(chip->of_node);
}

关于of_gpiochip_add_pin_range，看起来很复杂，其实也就那样啦^_：

static void of_gpiochip_add_pin_range(struct gpio_chip *chip)
{
	struct device_node *np = chip->of_node;
	struct of_phandle_args pinspec;
	struct pinctrl_dev *pctldev;
	int index = 0, ret;
	const char *name;
	static const char group_names_propname[] = "gpio-ranges-group-names";
	struct property *group_names;

	if (!np)
		return;

	//查找该gpiochip里的gpio-ranges-group-names属性
	group_names = of_find_property(np, group_names_propname, NULL);

	for (;; index++) {
    	//提取该gpiochip设备树信息里的gpio-ranges属性，按3个字段为一组解析，解析后
        //放到pinspec中，这个gpio-ranges可能存在多组，因此用index来控制，一组一组来处理
        //举个例子：
        //gpio0: gpio@ffc40000 {
        //    compatible = "renesas,gpio-r8a7778", "renesas,gpio-rcar";
        //    reg = <0xffc40000 0x2c>;
        //    interrupt-parent = <&gic>;
        //    interrupts = <0 103 IRQ_TYPE_LEVEL_HIGH>;
        //    #gpio-cells = <2>;
        //    gpio-controller;
        //    gpio-ranges = <&pfc 0 0 32>;
        //    #interrupt-cells = <2>;
        //    interrupt-controller;
        //};
        //gpio-ranges属性是gpio子系统规定的属性，更详细的信息参考	　　　　　　　　　　　　
        //Documentation/devicetree/bindings/gpio/gpio.txt
		ret = of_parse_phandle_with_fixed_args(np, "gpio-ranges", 3,
				index, &pinspec);
		if (ret)
			break;

		//获取到pinspec.np（也就是pinctrl对应的节点）对应的pctldev
        //注意，这个时候的gpiochip属于pinctrl的一个client
		pctldev = of_pinctrl_get(pinspec.np);
		if (!pctldev)
			break;

		//这部分的解析也是Documentation/devicetree/bindings/gpio/gpio.txt里有详细
        //说明的，如果最后一个参数为0，表示代表一个gpio group，否则，第一个参数意思是gpio号起始值
        //第二个参数意思是与之对应的pin号的起始值，最后一个参数表示连续多少各
		if (pinspec.args[2]) {
			if (group_names) {//这里仅仅是校验，如果不是表示gpio group，那么对应的
            	//gpio-ranges-group-names属性里对应的字段应该为""
				ret = of_property_read_string_index(np,
						group_names_propname,
						index, &name);
				if (strlen(name)) {
					pr_err("%s: Group name of numeric GPIO ranges must be the empty string.\n",
						np->full_name);
					break;
				}
			}
			/* npins != 0: linear range */
            //到这里说明确定不是gpio group啦，那就将它们加入到pinctrl子系统管理起来吧
            //，这里后面分析pinctrl子系统的时候再回过头来分析它
            ret = gpiochip_add_pin_range(chip,
					pinctrl_dev_get_devname(pctldev),
					pinspec.args[0],
					pinspec.args[1],
					pinspec.args[2]);
			if (ret)
				break;
		} else {
			/* npins == 0: special range */
            //校验，为pin gourp时，gpio 子系统要求第一个参数必须要0
			if (pinspec.args[1]) {
				pr_err("%s: Illegal gpio-range format.\n",
					np->full_name);
				break;
			}

			//如果是pin group，那么gpio-ranges-group-names属性必须要有，通过它来指定
            //那个group
			if (!group_names) {
				pr_err("%s: GPIO group range requested but no %s property.\n",
					np->full_name, group_names_propname);
				break;
			}

			//获取gpio-ranges-group-names属性里第index对应的字串（也就是组名）
			ret = of_property_read_string_index(np,
						group_names_propname,
						index, &name);
			if (ret)
				break;

			if (!strlen(name)) {
				pr_err("%s: Group name of GPIO group range cannot be the empty string.\n",
				np->full_name);
				break;
			}

			//一切ok，按group将它们加入到pinctrl子系统管理起来吧，这里后面分析pinctrl子系统的
            //时候再回过头来分析它
			ret = gpiochip_add_pingroup_range(chip, pctldev,
						pinspec.args[0], name);
			if (ret)
				break;
		}
	}
}

总结一下，gpiochip_add总共做了以下主要事情：

1. 将chip添加到全局的gpio chip链表中，用于gpio chip冲突处理和gpio管理
2. 将该gpio chip对应的那段gpio都初始化
3. 初始化设备树相关的信息，用于后面的属性解析及向pinctrl子系统同步下
4. 导出到sys

还有一点需要补充，从这里我们也会发现pinctrl由gpio子系统调用了，驱动工程师以及bsp工程师都不用关心，多好啊！后面会再次看到，大部分都是内核的通用部分代码处理了pinctrl，驱动工程师以及bsp工程师仍然不用关心，只需要关心设备树里pinctrl相关的部分，不过我们也得知其所以然啊，不然改动那些和pinctrl相关的总是心理没底啊！！！和bsp驱动工程师相关的部分就一个函数，没其他的了。不过准备chip里面的那些字段也够bsp工程师忙一阵子了吧^_

下面开始分析驱动工程师调用的gpio_request的过程，它的核心实现是调用gpiod_request，gpiod_get和gpiod_get_index的核心实现处理也调用了gpiod_request，但还做了一些其他事情，如解析gpios或者xxx-gpios属性获取设备树里指定的flags以及通过指定的gpio号获取到对应的desc（在上面的gpiochip_add过程中，我们有看到了desc的初始化），当然解析的过程会用到gpiochip_add里说过的of_xlate

if (IS_ENABLED(CONFIG_OF) && dev && dev->of_node) {
    dev_dbg(dev, "using device tree for GPIO lookup\n");
    desc = of_find_gpio(dev, con_id, idx, &flags);
} else if (IS_ENABLED(CONFIG_ACPI) && dev && ACPI_HANDLE(dev)) {
    dev_dbg(dev, "using ACPI for GPIO lookup\n");
    desc = acpi_find_gpio(dev, con_id, idx, &flags);
}

以及根据设备树里指定的flags设置desc，比如是否低电平有效，是否开漏输出等

if (flags & GPIO_ACTIVE_LOW)
    set_bit(FLAG_ACTIVE_LOW, &desc->flags);
if (flags & GPIO_OPEN_DRAIN)
    set_bit(FLAG_OPEN_DRAIN, &desc->flags);
if (flags & GPIO_OPEN_SOURCE)
    set_bit(FLAG_OPEN_SOURCE, &desc->flags);

gpio_request里面做的事情前面已经说的很清楚了，下面结合代码再回顾下：

static int gpiod_request(struct gpio_desc *desc, const char *label)
{
	int status = -EPROBE_DEFER;
	struct gpio_chip *chip;

	//检查desc是否有效，gpio_request会根据传入的gpio号在全局的desc里定位到desc
    //gpiod_get和gpiod_get_index则是通过解析设备树信息，提取里面的gpio号，然后再转换
	if (!desc) {
		pr_warn("%s: invalid GPIO\n", __func__);
		return -EINVAL;
	}

	//获取该desc的拥有者，即gpio chip（这个初始化在gpiochip_add里已经分析过了）
	chip = desc->chip;
	if (!chip)
		goto done;

	if (try_module_get(chip->owner)) {//增加下chip的引用
		status = __gpiod_request(desc, label);//核心动作都是在__gpiod_request里完成，就不再跟进去分析了^_^
		if (status < 0)
			module_put(chip->owner);
	}

done:
	if (status)
		gpiod_dbg(desc, "%s: status %d\n", __func__, status);

	return status;
}

总结一下，驱动工程师用gpio_request等api请求指定的gpio，这些gpio其实都是由bsp工程师调用gpiochip_add添加的，gpio_request会标记它，防止被不同的模块重复引用该gpio，当然也会告诉下gpio chip（如果chip想要被通知的话）

2> gpio_to_irq/gpiod_to_irq的过程分析

通过前面的分析，应该对gpio子系统有了一个比较完全的了解吧！其他的api应该也都能理解（猜测到会做什么），这里在对和gpio相关的中断分析下

gpio_to_irq只是简单的对gpiod_to_irq进行封装，主要看gpiod_to_irq：

int gpiod_to_irq(const struct gpio_desc *desc)
{
	struct gpio_chip	*chip;
	int			offset;

	if (!desc)
		return -EINVAL;
	chip = desc->chip;
    //获取该gpio号对应于该chip的offset，由于chip的起始号不一定就开始与系统全局desc的起点
  	//而该chip的处理又都是基于0开始的，所以得转一下啦
	offset = gpio_chip_hwgpio(desc);
    //调用芯片驱动提供的to_irq，如果chip driver不支持中断，那么to_irq应该就是空咯，说明不支持
    //从这里应该也清楚的知道了gpio号与中断号的对应关系是由chip driver处理的
    //驱动工程师用的gpio号都是全局的，bsp工程师用的gpio号都是局部的
	return chip->to_irq ? chip->to_irq(chip, offset) : -ENXIO;
}

还是看一下zynq的to_irq的实现吧！说到这里，会牵涉到中断子系统（貌似我还没写过中断子系统的文章），如果不太清楚，就跳过吧！

static int zynq_gpio_to_irq(struct gpio_chip *chip, unsigned offset)
{
	return irq_find_mapping(irq_domain, offset);
}

看起来貌似很简单吧！其实这也要归功于中断子系统的功劳啦！一般有中断控制器功能的设备会在该设备驱动里调用irq_domain_add_xxx接口来注册一个irq domain，然后会调用irq_create_mapping来创建irq号与硬件号的对应关系，里面会分配期望的irq desc，分配的时候，该中断控制器对应的中断号就确定了，然后会绑定该irq号与传入的硬件号。这就为后面的irq_find_mapping提供了支持，通过硬件号获取对应的irq号。这里再多说一句，大部分gpio chip同时也是一个中断控制器，写bsp的苦逼们不仅要gpiochip_add还要irq_domain_add等等操作，于是乎，gpio子系统解救他们来了，提供了一个接口gpiochip_irqchip_add，这接口完成后和gpio中断相关的所有事情，于是乎，bsp驱动工程师们也只需要调用两个接口了^_多么美好！

未完，待续！

2015年7月