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
  ...

1 files changed, 35 insertions, 0 deletions

diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt
index 9da0bfa74781..f73cc7b5dc85 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
+other.
+
+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
+irqchip.