Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit f23f1516 authored by Shiraz Hashim's avatar Shiraz Hashim Committed by Linus Walleij
Browse files

gpiolib: provide provision to register pin ranges 

pinctrl subsystem needs gpio chip base to prepare set of gpio
pin ranges, which a given pinctrl driver can handle. This is
important to handle pinctrl gpio request calls in order to
program a given pin properly for gpio operation.

As gpio base is allocated dynamically during gpiochip
registration, presently there exists no clean way to pass this
information to the pinctrl subsystem.

After few discussions from [1], it was concluded that may be
gpio controller reporting the pin range it supports, is a
better way than pinctrl subsystem directly registering it.

[1] http://comments.gmane.org/gmane.linux.ports.arm.kernel/184816



Cc: Grant Likely <grant.likely@secretlab.ca>
Signed-off-by: default avatarViresh Kumar <viresh.kumar@linaro.org>
Signed-off-by: default avatarShiraz Hashim <shiraz.hashim@st.com>
[Edited documentation a bit]
Signed-off-by: default avatarLinus Walleij <linus.walleij@linaro.org>
parent 7e10ee68

Documentation/devicetree/bindings/gpio/gpio.txt

+36 −0
Original line number Diff line number Diff line
@@ -75,4 +75,40 @@ Example of two SOC GPIO banks defined as gpio-controller nodes: 
		gpio-controller;

	};



2.1) gpio-controller and pinctrl subsystem

------------------------------------------



gpio-controller on a SOC might be tightly coupled with the pinctrl

subsystem, in the sense that the pins can be used by other functions

together with optional gpio feature.



While the pin allocation is totally managed by the pin ctrl subsystem,

gpio (under gpiolib) is still maintained by gpio drivers. It may happen

that different pin ranges in a SoC is managed by different gpio drivers.



This makes it logical to let gpio drivers announce their pin ranges to

the pin ctrl subsystem and call 'pinctrl_request_gpio' in order to

request the corresponding pin before any gpio usage.



For this, the gpio controller can use a pinctrl phandle and pins to

announce the pinrange to the pin ctrl subsystem. For example,



	qe_pio_e: gpio-controller@1460 {

		#gpio-cells = <2>;

		compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";

		reg = <0x1460 0x18>;

		gpio-controller;

		gpio-ranges = <&pinctrl1 20 10>, <&pinctrl2 50 20>;



    }



where,

   &pinctrl1 and &pinctrl2 is the phandle to the pinctrl DT node.



   Next values specify the base pin and number of pins for the range

   handled by 'qe_pio_e' gpio. In the given example from base pin 20 to

   pin 29 under pinctrl1 and pin 50 to pin 69 under pinctrl2 is handled

   by this gpio controller.



The pinctrl node must have "#gpio-range-cells" property to show number of

arguments to pass with phandle from gpio controllers node.

Documentation/gpio.txt

+42 −0
Original line number Diff line number Diff line
@@ -439,6 +439,48 @@ slower clock delays the rising edge of SCK, and the I2C master adjusts its 
signaling rate accordingly.





GPIO controllers and the pinctrl subsystem

------------------------------------------



A GPIO controller on a SOC might be tightly coupled with the pinctrl

subsystem, in the sense that the pins can be used by other functions

together with an optional gpio feature. We have already covered the

case where e.g. a GPIO controller need to reserve a pin or set the

direction of a pin by calling any of:



pinctrl_request_gpio()

pinctrl_free_gpio()

pinctrl_gpio_direction_input()

pinctrl_gpio_direction_output()



But how does the pin control subsystem cross-correlate the GPIO

numbers (which are a global business) to a certain pin on a certain

pin controller?



This is done by registering "ranges" of pins, which are essentially

cross-reference tables. These are described in

Documentation/pinctrl.txt



While the pin allocation is totally managed by the pinctrl subsystem,

gpio (under gpiolib) is still maintained by gpio drivers. It may happen

that different pin ranges in a SoC is managed by different gpio drivers.



This makes it logical to let gpio drivers announce their pin ranges to

the pin ctrl subsystem before it will call 'pinctrl_request_gpio' in order

to request the corresponding pin to be prepared by the pinctrl subsystem

before any gpio usage.



For this, the gpio controller can register its pin range with pinctrl

subsystem. There are two ways of doing it currently: with or without DT.



For with DT support refer to Documentation/devicetree/bindings/gpio/gpio.txt.



For non-DT support, user can call gpiochip_add_pin_range() with appropriate

parameters to register a range of gpio pins with a pinctrl driver. For this

exact name string of pinctrl device has to be passed as one of the

argument to this routine.





What do these conventions omit?

===============================

One of the biggest things these conventions omit is pin multiplexing, since

Documentation/pinctrl.txt

+3 −0
Original line number Diff line number Diff line
@@ -364,6 +364,9 @@ will get an pin number into its handled number range. Further it is also passed 
the range ID value, so that the pin controller knows which range it should

deal with.



Calling pinctrl_add_gpio_range from pinctrl driver is DEPRECATED. Please see

section 2.1 of Documentation/devicetree/bindings/gpio/gpio.txt on how to bind

pinctrl and gpio drivers.



PINMUX interfaces

=================

drivers/gpio/gpiolib-of.c

+56 −0
Original line number Diff line number Diff line
@@ -19,6 +19,7 @@ 
#include <linux/of.h>

#include <linux/of_address.h>

#include <linux/of_gpio.h>

#include <linux/pinctrl/pinctrl.h>

#include <linux/slab.h>



/* Private data structure for of_gpiochip_find_and_xlate */
@@ -216,6 +217,58 @@ int of_mm_gpiochip_add(struct device_node *np, 
}

EXPORT_SYMBOL(of_mm_gpiochip_add);



#ifdef CONFIG_PINCTRL

void of_gpiochip_add_pin_range(struct gpio_chip *chip)

{

	struct device_node *np = chip->of_node;

	struct gpio_pin_range *pin_range;

	struct of_phandle_args pinspec;

	int index = 0, ret;



	if (!np)

		return;



	do {

		ret = of_parse_phandle_with_args(np, "gpio-ranges",

				"#gpio-range-cells", index, &pinspec);

		if (ret)

			break;



		pin_range = devm_kzalloc(chip->dev, sizeof(*pin_range),

				GFP_KERNEL);

		if (!pin_range) {

			pr_err("%s: GPIO chip: failed to allocate pin ranges\n",

					chip->label);

			break;

		}



		pin_range->range.name = chip->label;

		pin_range->range.base = chip->base;

		pin_range->range.pin_base = pinspec.args[0];

		pin_range->range.npins = pinspec.args[1];

		pin_range->pctldev = of_pinctrl_add_gpio_range(pinspec.np,

				&pin_range->range);



		list_add_tail(&pin_range->node, &chip->pin_ranges);



	} while (index++);

}



void of_gpiochip_remove_pin_range(struct gpio_chip *chip)

{

	struct gpio_pin_range *pin_range, *tmp;



	list_for_each_entry_safe(pin_range, tmp, &chip->pin_ranges, node) {

		list_del(&pin_range->node);

		pinctrl_remove_gpio_range(pin_range->pctldev,

				&pin_range->range);

	}

}

#else

void of_gpiochip_add_pin_range(struct gpio_chip *chip) {}

void of_gpiochip_remove_pin_range(struct gpio_chip *chip) {}

#endif



void of_gpiochip_add(struct gpio_chip *chip)

{

	if ((!chip->of_node) && (chip->dev))
@@ -229,11 +282,14 @@ void of_gpiochip_add(struct gpio_chip *chip) 
		chip->of_xlate = of_gpio_simple_xlate;

	}



	of_gpiochip_add_pin_range(chip);

	of_node_get(chip->of_node);

}



void of_gpiochip_remove(struct gpio_chip *chip)

{

	of_gpiochip_remove_pin_range(chip);



	if (chip->of_node)

		of_node_put(chip->of_node);

}

drivers/gpio/gpiolib.c

+43 −0
Original line number Diff line number Diff line
@@ -1083,6 +1083,10 @@ int gpiochip_add(struct gpio_chip *chip) 
		}

	}



#ifdef CONFIG_PINCTRL

	INIT_LIST_HEAD(&chip->pin_ranges);

#endif



	of_gpiochip_add(chip);



unlock:
@@ -1180,6 +1184,45 @@ struct gpio_chip *gpiochip_find(void *data, 
}

EXPORT_SYMBOL_GPL(gpiochip_find);



#ifdef CONFIG_PINCTRL

void gpiochip_add_pin_range(struct gpio_chip *chip, const char *pinctl_name,

		unsigned int pin_base, unsigned int npins)

{

	struct gpio_pin_range *pin_range;



	pin_range = devm_kzalloc(chip->dev, sizeof(*pin_range), GFP_KERNEL);

	if (!pin_range) {

		pr_err("%s: GPIO chip: failed to allocate pin ranges\n",

				chip->label);

		return;

	}



	pin_range->range.name = chip->label;

	pin_range->range.base = chip->base;

	pin_range->range.pin_base = pin_base;

	pin_range->range.npins = npins;

	pin_range->pctldev = find_pinctrl_and_add_gpio_range(pinctl_name,

			&pin_range->range);



	list_add_tail(&pin_range->node, &chip->pin_ranges);

}



void gpiochip_remove_pin_ranges(struct gpio_chip *chip)

{

	struct gpio_pin_range *pin_range, *tmp;



	list_for_each_entry_safe(pin_range, tmp, &chip->pin_ranges, node) {

		list_del(&pin_range->node);

		pinctrl_remove_gpio_range(pin_range->pctldev,

				&pin_range->range);

	}

}

#else

void gpiochip_add_pin_range(struct gpio_chip *chip, const char *pinctl_name,

		unsigned int pin_base, unsigned int npins) {}

void gpiochip_remove_pin_ranges(struct gpio_chip *chip) {}

#endif



/* These "optional" allocation calls help prevent drivers from stomping

 * on each other, and help provide better diagnostics in debugfs.

 * They're called even less than the "set direction" calls.