Merge tag 'gpio-v3.16-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio into next

Pull GPIO updates from Linus Walleij:
 "This is the bulk of GPIO changes for the v3.16 series.

  There is a lot of action in the GPIO subsystem doing refactorings and
  cleanups, almost as many deletions as insertions and minor feature
  growth and no new drivers this time.  Which is actually pretty nice.
  Some GPIO-related stuff will come in through the pin control tree as
  well.

  Details:

   - We are finalizing and fixing up the gpiochip irqchip helpers
     bringing a helpful irqchip implementation into the gpiolib core and
     avoiding duplicate code and, more importantly, duplicate bug fixes:

     * Support for using the helpers with threaded interrupt handlers as
       used on sleeping GPIO-irqchips

     * Do not set up hardware triggers for edges or levels if the
       default IRQ type is IRQ_TYPE_NONE - some drivers would exploit
       the fact that you could get default initialization of the IRQ
       type from the core at probe() but if no default type is set up
       from the helper, we should not call the driver to configure
       anything.  Wait until a consumer requests the interrupt instead.

     * Make the irqchip helpers put the GPIO irqs into their own lock
       class.  The GPIO irqchips can often emit (harmless, but annoying)
       lockdep warnings about recursions when they are in fact just
       cascaded IRQs.  By putting them into their own lock class we help
       the lockdep core to keep track of things.

     * Switch the tc3589x GPIO expanders to use the irqchip helpers

     * Switch the OMAP GPIO driver to use the irqchip helpers

     * Add some documentation for the irqchip helpers

     * select IRQ_DOMAIN when using the helpers since some platforms may
       not be using this by default and it's a strict dependency.

   - Continued GPIO descriptor refactoring:

     * Remove the one instance of gpio_to_desc() from the device tree
       code, making the OF GPIO code use GPIO descriptors only.

     * Introduce gpiod_get_optional() and gpiod_get_optional_index()
       akin to the similar regulator functions for cases where the use
       of GPIO is optional and not strictly required.

     * Make of_get_named_gpiod_flags() private - we do not want to
       unnecessarily expose APIs to drivers that make the gpiolib harder
       than necessary to maintain and refactor.  Privatize this
       function.

   - Support "-gpio" suffix for the OF GPIO retrieveal path.  We used to
     look for "foo-gpios" or just "gpios" in device tree nodes, but it
     turns out that some drivers with a single GPIO line will just state
     "foo-gpio" (singularis).  Sigh.  Support this with a fallback
     looking for it, as this simplifies driver code and handles it in
     core code.

   - Switch the ACPI GPIO core to fetch GPIOs with the *_cansleep
     function variants as the GPIO operation region handler can sleep,
     and shall be able to handle gpiochips that sleep.

   - Tons of cleanups and janitorial work from Jingoo Han, Axel Lin,
     Javier Martinez Canillas and Abdoulaye Berthe.  Notably Jingoo cut
     off a ton of pointless OOM messages.

   - Incremental development and fixes for various drivers, nothing
     really special here"

* tag 'gpio-v3.16-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio: (85 commits)
  gpio: select IRQ_DOMAIN for gpiolib irqchip helpers
  gpio: pca953x: use gpiolib irqchip helpers
  gpio: pcf857x: Add IRQF_SHARED when request irq
  gpio: pcf857x: Avoid calling irq_domain_cleanup twice
  gpio: mcp23s08: switch chip count to int
  gpio: dwapb: use a second irq chip
  gpio: ep93xx: Use devm_ioremap_resource()
  gpio: mcp23s08: fixed count variable for devicetree probing
  gpio: Add run-time dependencies to R-Car driver
  gpio: pch: add slab include
  Documentation / ACPI: Fix location of GPIO documentation
  gpio / ACPI: use *_cansleep version of gpiod_get/set APIs
  gpio: generic: add request function pointer
  gpio-pch: Fix Kconfig dependencies
  gpio: make of_get_named_gpiod_flags() private
  gpio: gpioep93xx: use devm functions
  gpio: janzttl: use devm function
  gpio: timberdale: use devm functions
  gpio: bt8xx: use devm function for memory allocation
  gpio: include linux/bug.h in interface header
  ...

4 files changed, 73 insertions, 1 deletions

diff --git a/Documentation/acpi/enumeration.txt b/Documentation/acpi/enumeration.txt
index 2a1519b87177..fd786ea13a1f 100644
--- a/Documentation/acpi/enumeration.txt
+++ b/Documentation/acpi/enumeration.txt
@@ -296,7 +296,7 @@ specifies the path to the controller. In order to use these GPIOs in Linux
 we need to translate them to the corresponding Linux GPIO descriptors.
 
 There is a standard GPIO API for that and is documented in
-Documentation/gpio.txt.
+Documentation/gpio/.
 
 In the above example we can get the corresponding two GPIO descriptors with
 a code like this:
diff --git a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt
index f61cef74a212..941a26aa4322 100644
--- a/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt
+++ b/Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt
@@ -21,6 +21,12 @@ Required Properties:
     GPIO_ACTIVE_HIGH and GPIO_ACTIVE_LOW flags are supported.
   - gpio-ranges: Range of pins managed by the GPIO controller.
 
+Optional properties:
+
+  - clocks: Must contain a reference to the functional clock.  The property is
+    mandatory if the hardware implements a controllable functional clock for
+    the GPIO instance.
+
 Please refer to gpio.txt in this directory for details of gpio-ranges property
 and the common GPIO bindings used by client devices.
 
diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.txt
index 4f7897e99cba..10b8c5d2c797 100644
--- a/Documentation/driver-model/devres.txt
+++ b/Documentation/driver-model/devres.txt
@@ -308,3 +308,10 @@ SLAVE DMA ENGINE
 
 SPI
   devm_spi_register_master()
+
+GPIO
+  devm_gpiod_get()
+  devm_gpiod_get_index()
+  devm_gpiod_get_optional()
+  devm_gpiod_get_index_optional()
+  devm_gpiod_put()
diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt
index f73cc7b5dc85..fa9a0a8b3734 100644
--- a/Documentation/gpio/driver.txt
+++ b/Documentation/gpio/driver.txt
@@ -73,6 +73,65 @@ 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.
 
+GPIO irqchips usually fall in one of two categories:
+
+* CHAINED GPIO irqchips: these are usually the type that is embedded on
+  an SoC. This means that there is a fast IRQ handler for the GPIOs that
+  gets called in a chain from the parent IRQ handler, most typically the
+  system interrupt controller. This means the GPIO irqchip is registered
+  using irq_set_chained_handler() or the corresponding
+  gpiochip_set_chained_irqchip() helper function, and the GPIO irqchip
+  handler will be called immediately from the parent irqchip, while
+  holding the IRQs disabled. The GPIO irqchip will then end up calling
+  something like this sequence in its interrupt handler:
+
+  static irqreturn_t tc3589x_gpio_irq(int irq, void *data)
+      chained_irq_enter(...);
+      generic_handle_irq(...);
+      chained_irq_exit(...);
+
+  Chained GPIO irqchips typically can NOT set the .can_sleep flag on
+  struct gpio_chip, as everything happens directly in the callbacks.
+
+* NESTED THREADED GPIO irqchips: these are off-chip GPIO expanders and any
+  other GPIO irqchip residing on the other side of a sleeping bus. Of course
+  such drivers that need slow bus traffic to read out IRQ status and similar,
+  traffic which may in turn incur other IRQs to happen, cannot be handled
+  in a quick IRQ handler with IRQs disabled. Instead they need to spawn a
+  thread and then mask the parent IRQ line until the interrupt is handled
+  by the driver. The hallmark of this driver is to call something like
+  this in its interrupt handler:
+
+  static irqreturn_t tc3589x_gpio_irq(int irq, void *data)
+      ...
+      handle_nested_irq(irq);
+
+  The hallmark of threaded GPIO irqchips is that they set the .can_sleep
+  flag on struct gpio_chip to true, indicating that this chip may sleep
+  when accessing the GPIOs.
+
+To help out in handling the set-up and management of GPIO irqchips and the
+associated irqdomain and resource allocation callbacks, the gpiolib has
+some helpers that can be enabled by selecting the GPIOLIB_IRQCHIP Kconfig
+symbol:
+
+* gpiochip_irqchip_add(): adds an irqchip to a gpiochip. It will pass
+  the struct gpio_chip* for the chip to all IRQ callbacks, so the callbacks
+  need to embed the gpio_chip in its state container and obtain a pointer
+  to the container using container_of().
+  (See Documentation/driver-model/design-patterns.txt)
+
+* gpiochip_set_chained_irqchip(): sets up a chained irq handler for a
+  gpio_chip from a parent IRQ and passes the struct gpio_chip* as handler
+  data. (Notice handler data, since the irqchip data is likely used by the
+  parent irqchip!) This is for the chained type of chip.
+
+To use the helpers please keep the following in mind:
+
+- Make sure to assign all relevant members of the struct gpio_chip so that
+  the irqchip can initialize. E.g. .dev and .can_sleep shall be set up
+  properly.
+
 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