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, 52 insertions, 8 deletions

diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt
index 0c85bb6e3a80..3fb8f53071b8 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.
+
+or:
+
+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.
+
+or:
+
+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
+controller.
 
 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-controller;
+		#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-controller;
+		#gpio-cells = <2>;
 	};
 
 2.1) gpio- and pin-controller interaction