path: root/Documentation
diff options
authorLinus Torvalds <torvalds@linux-foundation.org>2014-04-03 16:44:15 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2014-04-03 16:44:15 -0700
commit154d6f18a48e00dec2dc84a96914fe1a24669577 (patch)
tree7b92ac64a00eb173af396752f3bfc72c9eba615c /Documentation
parent76ca7d1cca761bb9712dfcad9a27d70b520874ae (diff)
parentb22978fc33dec72e5f8e17f90eb63ea9137aafd5 (diff)
Merge tag 'gpio-v3.15-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio
Pull bulk of gpio updates from Linus Walleij: "A pretty big chunk of changes this time, but it has all been on rotation in linux-next and had some testing. Of course there will be some amount of fixes on top... - Merged in a branch of irqchip changes from Thomas Gleixner: we need to have new callbacks from the irqchip to determine if the GPIO line will be eligible for IRQs, and this callback must be able to say "no". After some thinking I got the branch from tglx and have switched all current users over to use this. - Based on tglx patches, we have added some generic irqchip helpers in the gpiolib core. These will help centralize code when GPIO drivers have simple chained/cascaded IRQs. Drivers will still define their irqchip vtables, but the gpiolib core will take care of irqdomain set-up, mapping from local offsets to Linux irqs, and reserve resources by marking the GPIO lines for IRQs. - Initially the PL061 and Nomadik GPIO/pin control drivers have been switched over to use the new gpiochip-to-irqchip infrastructure with more drivers expected for the next kernel cycle. The factoring of just two drivers still makes it worth it so it is already a win. - A new driver for the Synopsys DesignWare APB GPIO block. - Modify the DaVinci GPIO driver to be reusable also for the new TI Keystone architecture. - A new driver for the LSI ZEVIO SoCs. - Delete the obsolte tnetv107x driver. - Some incremental work on GPIO descriptors: have gpiod_direction_output() use a logical level, respecting assertion polarity through ACTIVE_LOW flags, adding gpiod_direction_output_raw() for the case where you want to set that very value. Add gpiochip_get_desc() to fetch a GPIO descriptor from a specific offset on a certain chip inside driver code. - Switch ACPI GPIO code over to using gpiochip_get_desc() and get rid of gpio_to_desc(). - The ACPI GPIO event handling code has been reworked after encountering an actual real life implementation. - Support for ACPI GPIO operation regions. - Generic GPIO chips can now be assigned labels/names from platform data. - We now clamp values returned from GPIO drivers to the boolean [0,1] range. - Some improved documentation on how to use the polarity flag was added. - a large slew of incremental driver updates and non-critical fixes. Some targeted for stable" * tag 'gpio-v3.15-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio: (80 commits) gpio: rcar: Add helper variable dev = &pdev->dev gpio-lynxpoint: force gpio_get() to return "1" and "0" only gpio: unmap gpio irqs properly pch_gpio: set value before enabling output direction gpio: moxart: Actually set output state in moxart_gpio_direction_output() gpio: moxart: Avoid forward declaration gpio: mxs: Allow for recursive enable_irq_wake() call gpio: samsung: Add missing "break" statement gpio: twl4030: Remove redundant assignment gpio: dwapb: correct gpio-cells in binding document gpio: iop: fix devm_ioremap_resource() return value checking pinctrl: coh901: convert driver to use gpiolib irqchip pinctrl: nomadik: convert driver to use gpiolib irqchip gpio: pl061: convert driver to use gpiolib irqchip gpio: add IRQ chip helpers in gpiolib pinctrl: nomadik: factor in platform data container pinctrl: nomadik: rename secondary to latent gpio: Driver for SYSCON-based GPIOs gpio: generic: Use platform_device_id->driver_data field for driver flags pinctrl: coh901: move irq line locking to resource callbacks ...
Diffstat (limited to 'Documentation')
7 files changed, 204 insertions, 10 deletions
diff --git a/Documentation/devicetree/bindings/gpio/cirrus,clps711x-mctrl-gpio.txt b/Documentation/devicetree/bindings/gpio/cirrus,clps711x-mctrl-gpio.txt
new file mode 100644
index 00000000000..94ae9f82dcf
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/cirrus,clps711x-mctrl-gpio.txt
@@ -0,0 +1,17 @@
+Required properties:
+- compatible: Should contain "cirrus,clps711x-mctrl-gpio".
+- gpio-controller: Marks the device node as a gpio controller.
+- #gpio-cells: Should be two. The first cell is the pin number and
+ the second cell is used to specify the gpio polarity:
+ 0 = Active high,
+ 1 = Active low.
+ sysgpio: sysgpio {
+ compatible = "cirrus,ep7312-mctrl-gpio",
+ "cirrus,clps711x-mctrl-gpio";
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-davinci.txt b/Documentation/devicetree/bindings/gpio/gpio-davinci.txt
index a2e839d6e33..5079ba7d656 100644
--- a/Documentation/devicetree/bindings/gpio/gpio-davinci.txt
+++ b/Documentation/devicetree/bindings/gpio/gpio-davinci.txt
@@ -1,13 +1,17 @@
-Davinci GPIO controller bindings
+Davinci/Keystone GPIO controller bindings
Required Properties:
-- compatible: should be "ti,dm6441-gpio"
+- compatible: should be "ti,dm6441-gpio", "ti,keystone-gpio"
- reg: Physical base address of the controller and the size of memory mapped
- gpio-controller : Marks the device node as a gpio controller.
+- #gpio-cells : Should be two.
+ - first cell is the pin number
+ - second cell is used to specify optional parameters (unused)
- interrupt-parent: phandle of the parent interrupt controller.
- interrupts: Array of GPIO interrupt number. Only banked or unbanked IRQs are
@@ -27,6 +31,7 @@ Example:
gpio: gpio@1e26000 {
compatible = "ti,dm6441-gpio";
+ #gpio-cells = <2>;
reg = <0x226000 0x1000>;
interrupt-parent = <&intc>;
@@ -39,3 +44,19 @@ gpio: gpio@1e26000 {
#interrupt-cells = <2>;
+leds {
+ compatible = "gpio-leds";
+ led1 {
+ label = "davinci:green:usr1";
+ gpios = <&gpio 10 GPIO_ACTIVE_HIGH>;
+ ...
+ };
+ led2 {
+ label = "davinci:red:debug1";
+ gpios = <&gpio 11 GPIO_ACTIVE_HIGH>;
+ ...
+ };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-zevio.txt b/Documentation/devicetree/bindings/gpio/gpio-zevio.txt
new file mode 100644
index 00000000000..a37bd9ae273
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/gpio-zevio.txt
@@ -0,0 +1,16 @@
+Zevio GPIO controller
+Required properties:
+- compatible: Should be "lsi,zevio-gpio"
+- reg: Address and length of the register set for the device
+- #gpio-cells: Should be two. The first cell is the pin number and the
+ second cell is used to specify optional parameters (currently unused).
+- gpio-controller: Marks the device node as a GPIO controller.
+ gpio: gpio@90000000 {
+ compatible = "lsi,zevio-gpio";
+ reg = <0x90000000 0x1000>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ };
diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt
index 0c85bb6e3a8..3fb8f53071b 100644
--- a/Documentation/devicetree/bindings/gpio/gpio.txt
+++ b/Documentation/devicetree/bindings/gpio/gpio.txt
@@ -13,11 +13,11 @@ properties, each containing a 'gpio-list':
gpio-specifier : Array of #gpio-cells specifying specific gpio
(controller specific)
-GPIO properties should be named "[<name>-]gpios". Exact
+GPIO properties should be named "[<name>-]gpios". The exact
meaning of each gpios property must be documented in the device tree
binding for each device.
-For example, the following could be used to describe gpios pins to use
+For example, the following could be used to describe GPIO pins used
as chip select lines; with chip selects 0, 1 and 3 populated, and chip
select 2 left empty:
@@ -44,35 +44,79 @@ whether pin is open-drain and whether pin is logically inverted.
Exact meaning of each specifier cell is controller specific, and must
be documented in the device tree binding for the device.
-Example of the node using GPIOs:
+Example of a node using GPIOs:
node {
gpios = <&qe_pio_e 18 0>;
In this example gpio-specifier is "18 0" and encodes GPIO pin number,
-and empty GPIO flags as accepted by the "qe_pio_e" gpio-controller.
+and GPIO flags as accepted by the "qe_pio_e" gpio-controller.
+1.1) GPIO specifier best practices
+A gpio-specifier should contain a flag indicating the GPIO polarity; active-
+high or active-low. If it does, the follow best practices should be followed:
+The gpio-specifier's polarity flag should represent the physical level at the
+GPIO controller that achieves (or represents, for inputs) a logically asserted
+value at the device. The exact definition of logically asserted should be
+defined by the binding for the device. If the board inverts the signal between
+the GPIO controller and the device, then the gpio-specifier will represent the
+opposite physical level than the signal at the device's pin.
+When the device's signal polarity is configurable, the binding for the
+device must either:
+a) Define a single static polarity for the signal, with the expectation that
+any software using that binding would statically program the device to use
+that signal polarity.
+The static choice of polarity may be either:
+a1) (Preferred) Dictated by a binding-specific DT property.
+a2) Defined statically by the DT binding itself.
+In particular, the polarity cannot be derived from the gpio-specifier, since
+that would prevent the DT from separately representing the two orthogonal
+concepts of configurable signal polarity in the device, and possible board-
+level signal inversion.
+b) Pick a single option for device signal polarity, and document this choice
+in the binding. The gpio-specifier should represent the polarity of the signal
+(at the GPIO controller) assuming that the device is configured for this
+particular signal polarity choice. If software chooses to program the device
+to generate or receive a signal of the opposite polarity, software will be
+responsible for correctly interpreting (inverting) the GPIO signal at the GPIO
2) gpio-controller nodes
-Every GPIO controller node must both an empty "gpio-controller"
-property, and have #gpio-cells contain the size of the gpio-specifier.
+Every GPIO controller node must contain both an empty "gpio-controller"
+property, and a #gpio-cells integer property, which indicates the number of
+cells in a gpio-specifier.
Example of two SOC GPIO banks defined as gpio-controller nodes:
qe_pio_a: gpio-controller@1400 {
- #gpio-cells = <2>;
compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank";
reg = <0x1400 0x18>;
+ #gpio-cells = <2>;
qe_pio_e: gpio-controller@1460 {
- #gpio-cells = <2>;
compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
reg = <0x1460 0x18>;
+ #gpio-cells = <2>;
2.1) gpio- and pin-controller interaction
diff --git a/Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt b/Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt
new file mode 100644
index 00000000000..dd5d2c0394b
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/snps-dwapb-gpio.txt
@@ -0,0 +1,60 @@
+* Synopsys DesignWare APB GPIO controller
+Required properties:
+- compatible : Should contain "snps,dw-apb-gpio"
+- reg : Address and length of the register set for the device.
+- #address-cells : should be 1 (for addressing port subnodes).
+- #size-cells : should be 0 (port subnodes).
+The GPIO controller has a configurable number of ports, each of which are
+represented as child nodes with the following properties:
+Required properties:
+- compatible : "snps,dw-apb-gpio-port"
+- gpio-controller : Marks the device node as a gpio controller.
+- #gpio-cells : Should be two. The first cell is the pin number and
+ the second cell is used to specify the gpio polarity:
+ 0 = active high
+ 1 = active low
+- reg : The integer port index of the port, a single cell.
+Optional properties:
+- interrupt-controller : The first port may be configured to be an interrupt
+- #interrupt-cells : Specifies the number of cells needed to encode an
+ interrupt. Shall be set to 2. The first cell defines the interrupt number,
+ the second encodes the triger flags encoded as described in
+ Documentation/devicetree/bindings/interrupts.txt
+- interrupt-parent : The parent interrupt controller.
+- interrupts : The interrupt to the parent controller raised when GPIOs
+ generate the interrupts.
+- snps,nr-gpios : The number of pins in the port, a single cell.
+gpio: gpio@20000 {
+ compatible = "snps,dw-apb-gpio";
+ reg = <0x20000 0x1000>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ porta: gpio-controller@0 {
+ compatible = "snps,dw-apb-gpio-port";
+ gpio-controller;
+ #gpio-cells = <2>;
+ snps,nr-gpios = <8>;
+ reg = <0>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
+ interrupt-parent = <&vic1>;
+ interrupts = <0>;
+ };
+ portb: gpio-controller@1 {
+ compatible = "snps,dw-apb-gpio-port";
+ gpio-controller;
+ #gpio-cells = <2>;
+ snps,nr-gpios = <8>;
+ reg = <1>;
+ };
diff --git a/Documentation/gpio/consumer.txt b/Documentation/gpio/consumer.txt
index e42f77d8d4c..09854fe5930 100644
--- a/Documentation/gpio/consumer.txt
+++ b/Documentation/gpio/consumer.txt
@@ -154,6 +154,7 @@ raw line value:
void gpiod_set_raw_value(struct gpio_desc *desc, int value)
int gpiod_get_raw_value_cansleep(const struct gpio_desc *desc)
void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value)
+ int gpiod_direction_output_raw(struct gpio_desc *desc, int value)
The active-low state of a GPIO can also be queried using the following call:
diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt
index 9da0bfa7478..f73cc7b5dc8 100644
--- a/Documentation/gpio/driver.txt
+++ b/Documentation/gpio/driver.txt
@@ -62,6 +62,37 @@ Any debugfs dump method should normally ignore signals which haven't been
requested as GPIOs. They can use gpiochip_is_requested(), which returns either
NULL or the label associated with that GPIO when it was requested.
+GPIO drivers providing IRQs
+It is custom that GPIO drivers (GPIO chips) are also providing interrupts,
+most often cascaded off a parent interrupt controller, and in some special
+cases the GPIO logic is melded with a SoC's primary interrupt controller.
+The IRQ portions of the GPIO block are implemented using an irqchip, using
+the header <linux/irq.h>. So basically such a driver is utilizing two sub-
+systems simultaneously: gpio and irq.
+It is legal for any IRQ consumer to request an IRQ from any irqchip no matter
+if that is a combined GPIO+IRQ driver. The basic premise is that gpio_chip and
+irq_chip are orthogonal, and offering their services independent of each
+gpiod_to_irq() is just a convenience function to figure out the IRQ for a
+certain GPIO line and should not be relied upon to have been called before
+the IRQ is used.
+So always prepare the hardware and make it ready for action in respective
+callbacks from the GPIO and irqchip APIs. Do not rely on gpiod_to_irq() having
+been called first.
+This orthogonality leads to ambiguities that we need to solve: if there is
+competition inside the subsystem which side is using the resource (a certain
+GPIO line and register for example) it needs to deny certain operations and
+keep track of usage inside of the gpiolib subsystem. This is why the API
+below exists.
Locking IRQ usage
Input GPIOs can be used as IRQ signals. When this happens, a driver is requested
@@ -73,3 +104,7 @@ This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock
is released:
void gpiod_unlock_as_irq(struct gpio_desc *desc)
+When implementing an irqchip inside a GPIO driver, these two functions should
+typically be called in the .startup() and .shutdown() callbacks from the