summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2015-11-02 23:59:12 +0300
committerLinus Torvalds <torvalds@linux-foundation.org>2015-11-02 23:59:12 +0300
commite86328c489d7ecdca99410a06a3f448caf7857bf (patch)
tree5fab7d3abeb891c77c329d9bbaf6c15cea33b4e0 /Documentation
parentbc9d8c20ffb47e64a41a4716a06d37cdf88fcc42 (diff)
parent0963670aeaec2287aa263daa0d41384d4dcd5292 (diff)
downloadlinux-e86328c489d7ecdca99410a06a3f448caf7857bf.tar.xz
Merge tag 'gpio-v4.4-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio
Pull GPIO updates from Linus Walleij: "Here is the bulk of GPIO changes for the v4.4 development cycle. The only changes hitting outside drivers/gpio are in the pin control subsystem and these seem to have settled nicely in linux-next. Development mistakes and catfights are nicely documented in the reverts as you can see. The outcome of the ABI fight is that we're working on a chardev ABI for GPIO now, where hope to show results for the v4.5 kernel. Summary of changes: GPIO core: - Define and handle flags for open drain/open collector and open source/open emitter, also know as "single-ended" configurations. - Generic request/free operations that handle calling out to the (optional) pin control backend. - Some refactoring related to an ABI change that did not happen, yet provide useful. - Added a real-time compliance checklist. Many GPIO chips have irqchips, and need to think this over with the RT patches going upstream. - Restructure, fix and clean up Kconfig menus a bit. New drivers: - New driver for AMD Promony. - New driver for ACCES 104-IDIO-16, a port-mapped I/O card, ISA-style. Very retro. Subdriver changes: - OMAP changes to handle real time requirements. - Handle trigger types for edge and level IRQs on PL061 properly. As this hardware is very common it needs to set a proper example for others to follow. - Some container_of() cleanups. - Delete the unused MSM driver in favor of the driver that is embedded inside the pin control driver. - Cleanup of the ath79 GPIO driver used by many, many OpenWRT router targets. - A consolidated IT87xx driver replacing the earlier very specific IT8761e driver. - Handle the TI TCA9539 in the PCA953x driver. Also handle ACPI devices in this subdriver. - Drop xilinx arch dependencies as these FPGAs seem to profilate over a few different architectures. MIPS and ARM come to mind" * tag 'gpio-v4.4-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio: (57 commits) gpio: fix up SPI submenu gpio: drop surplus I2C dependencies gpio: drop surplus X86 dependencies gpio: dt-bindings: document the official use of "ngpios" gpio: MAINTAINERS: Add an entry for the ATH79 GPIO driver gpio / ACPI: Allow shared GPIO event to be read via operation region gpio: group port-mapped I/O drivers in a menu gpio: Add ACCES 104-IDIO-16 driver maintainer entry gpio: zynq: Document interrupt-controller DT binding gpio: xilinx: Drop architecture dependencies gpio: generic: Revert to old error handling in bgpio_map gpio: add a real time compliance notes Revert "gpio: add a real time compliance checklist" gpio: Add GPIO support for the ACCES 104-IDIO-16 gpio: driver for AMD Promontory gpio: xlp: Convert to use gpiolib irqchip helpers gpio: add a real time compliance checklist gpio/xilinx: enable for MIPS gpiolib: Add and use OF_GPIO_SINGLE_ENDED flag gpiolib: Split GPIO flags parsing and GPIO configuration ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-msm.txt26
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-pca953x.txt1
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio-zynq.txt9
-rw-r--r--Documentation/devicetree/bindings/gpio/gpio.txt41
-rw-r--r--Documentation/gpio/driver.txt80
5 files changed, 129 insertions, 28 deletions
diff --git a/Documentation/devicetree/bindings/gpio/gpio-msm.txt b/Documentation/devicetree/bindings/gpio/gpio-msm.txt
deleted file mode 100644
index ac20e68a004e..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-msm.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-MSM GPIO controller bindings
-
-Required properties:
-- compatible:
- - "qcom,msm-gpio" for MSM controllers
-- #gpio-cells : Should be two.
- - first cell is the pin number
- - second cell is used to specify optional parameters (unused)
-- gpio-controller : Marks the device node as a GPIO controller.
-- #interrupt-cells : Should be 2.
-- interrupt-controller: Mark the device node as an interrupt controller
-- interrupts : Specify the TLMM summary interrupt number
-- ngpio : Specify the number of MSM GPIOs
-
-Example:
-
- msmgpio: gpio@fd510000 {
- compatible = "qcom,msm-gpio";
- gpio-controller;
- #gpio-cells = <2>;
- interrupt-controller;
- #interrupt-cells = <2>;
- reg = <0xfd510000 0x4000>;
- interrupts = <0 208 0>;
- ngpio = <150>;
- };
diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt
index b9a42f294dd0..13df9933f4cd 100644
--- a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt
+++ b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt
@@ -24,6 +24,7 @@ Required properties:
ti,tca6408
ti,tca6416
ti,tca6424
+ ti,tca9539
exar,xra1202
Example:
diff --git a/Documentation/devicetree/bindings/gpio/gpio-zynq.txt b/Documentation/devicetree/bindings/gpio/gpio-zynq.txt
index db4c6a663c03..7b542657f259 100644
--- a/Documentation/devicetree/bindings/gpio/gpio-zynq.txt
+++ b/Documentation/devicetree/bindings/gpio/gpio-zynq.txt
@@ -12,6 +12,13 @@ Required properties:
- interrupts : Interrupt specifier (see interrupt bindings for
details)
- interrupt-parent : Must be core interrupt controller
+- interrupt-controller : Marks the device node as an interrupt controller.
+- #interrupt-cells : Should be 2. The first cell is the GPIO number.
+ The second cell bits[3:0] is used to specify trigger type and level flags:
+ 1 = low-to-high edge triggered.
+ 2 = high-to-low edge triggered.
+ 4 = active high level-sensitive.
+ 8 = active low level-sensitive.
- reg : Address and length of the register set for the device
Example:
@@ -22,5 +29,7 @@ Example:
gpio-controller;
interrupt-parent = <&intc>;
interrupts = <0 20 4>;
+ interrupt-controller;
+ #interrupt-cells = <2>;
reg = <0xe000a000 0x1000>;
};
diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt
index 82d40e2505f6..069cdf6f9dac 100644
--- a/Documentation/devicetree/bindings/gpio/gpio.txt
+++ b/Documentation/devicetree/bindings/gpio/gpio.txt
@@ -54,9 +54,13 @@ only uses one.
gpio-specifier may encode: bank, pin position inside the bank,
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. Use the macros
-defined in include/dt-bindings/gpio/gpio.h whenever possible:
+be documented in the device tree binding for the device.
+
+Most controllers are however specifying a generic flag bitfield
+in the last cell, so for these, use the macros defined in
+include/dt-bindings/gpio/gpio.h whenever possible:
Example of a node using GPIOs:
@@ -67,6 +71,15 @@ Example of a node using GPIOs:
GPIO_ACTIVE_HIGH is 0, so in this example gpio-specifier is "18 0" and encodes
GPIO pin number, and GPIO flags as accepted by the "qe_pio_e" gpio-controller.
+Optional standard bitfield specifiers for the last cell:
+
+- Bit 0: 0 means active high, 1 means active low
+- Bit 1: 1 means single-ended wiring, see:
+ https://en.wikipedia.org/wiki/Single-ended_triode
+ When used with active-low, this means open drain/collector, see:
+ https://en.wikipedia.org/wiki/Open_collector
+ When used with active-high, this means open source/emitter
+
1.1) GPIO specifier best practices
----------------------------------
@@ -118,6 +131,30 @@ 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.
+Optionally, a GPIO controller may have a "ngpios" property. This property
+indicates the number of in-use slots of available slots for GPIOs. The
+typical example is something like this: the hardware register is 32 bits
+wide, but only 18 of the bits have a physical counterpart. The driver is
+generally written so that all 32 bits can be used, but the IP block is reused
+in a lot of designs, some using all 32 bits, some using 18 and some using
+12. In this case, setting "ngpios = <18>;" informs the driver that only the
+first 18 GPIOs, at local offset 0 .. 17, are in use.
+
+If these GPIOs do not happen to be the first N GPIOs at offset 0...N-1, an
+additional bitmask is needed to specify which GPIOs are actually in use,
+and which are dummies. The bindings for this case has not yet been
+specified, but should be specified if/when such hardware appears.
+
+Example:
+
+gpio-controller@00000000 {
+ compatible = "foo";
+ reg = <0x00000000 0x1000>;
+ gpio-controller;
+ #gpio-cells = <2>;
+ ngpios = <18>;
+}
+
The GPIO chip may contain GPIO hog definitions. GPIO hogging is a mechanism
providing automatic GPIO request and configuration as part of the
gpio-controller's driver probe function.
diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt
index 90d0f6aba7a6..12a61948ec91 100644
--- a/Documentation/gpio/driver.txt
+++ b/Documentation/gpio/driver.txt
@@ -62,6 +62,11 @@ 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.
+RT_FULL: GPIO driver should not use spinlock_t or any sleepable APIs
+(like PM runtime) in its gpio_chip implementation (.get/.set and direction
+control callbacks) if it is expected to call GPIO APIs from atomic context
+on -RT (inside hard IRQ handlers and similar contexts). Normally this should
+not be required.
GPIO drivers providing IRQs
---------------------------
@@ -73,6 +78,13 @@ 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.
+RT_FULL: GPIO driver should not use spinlock_t or any sleepable APIs
+(like PM runtime) as part of its irq_chip implementation on -RT.
+- spinlock_t should be replaced with raw_spinlock_t [1].
+- If sleepable APIs have to be used, these can be done from the .irq_bus_lock()
+ and .irq_bus_unlock() callbacks, as these are the only slowpath callbacks
+ on an irqchip. Create the callbacks if needed [2].
+
GPIO irqchips usually fall in one of two categories:
* CHAINED GPIO irqchips: these are usually the type that is embedded on
@@ -93,6 +105,38 @@ GPIO irqchips usually fall in one of two categories:
Chained GPIO irqchips typically can NOT set the .can_sleep flag on
struct gpio_chip, as everything happens directly in the callbacks.
+ RT_FULL: Note, chained IRQ handlers will not be forced threaded on -RT.
+ As result, spinlock_t or any sleepable APIs (like PM runtime) can't be used
+ in chained IRQ handler.
+ if required (and if it can't be converted to the nested threaded GPIO irqchip)
+ - chained IRQ handler can be converted to generic irq handler and this way
+ it will be threaded IRQ handler on -RT and hard IRQ handler on non-RT
+ (for example, see [3]).
+ Know W/A: The generic_handle_irq() is expected to be called with IRQ disabled,
+ so IRQ core will complain if it will be called from IRQ handler wich is forced
+ thread. The "fake?" raw lock can be used to W/A this problem:
+
+ raw_spinlock_t wa_lock;
+ static irqreturn_t omap_gpio_irq_handler(int irq, void *gpiobank)
+ unsigned long wa_lock_flags;
+ raw_spin_lock_irqsave(&bank->wa_lock, wa_lock_flags);
+ generic_handle_irq(irq_find_mapping(bank->chip.irqdomain, bit));
+ raw_spin_unlock_irqrestore(&bank->wa_lock, wa_lock_flags);
+
+* GENERIC CHAINED GPIO irqchips: these are the same as "CHAINED GPIO irqchips",
+ but chained IRQ handlers are not used. Instead GPIO IRQs dispatching is
+ performed by generic IRQ handler which is configured using request_irq().
+ The GPIO irqchip will then end up calling something like this sequence in
+ its interrupt handler:
+
+ static irqreturn_t gpio_rcar_irq_handler(int irq, void *dev_id)
+ for each detected GPIO IRQ
+ generic_handle_irq(...);
+
+ RT_FULL: Such kind of handlers will be forced threaded on -RT, as result IRQ
+ core will complain that generic_handle_irq() is called with IRQ enabled and
+ the same W/A as for "CHAINED GPIO irqchips" can be applied.
+
* 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,
@@ -133,6 +177,13 @@ To use the helpers please keep the following in mind:
the irqchip can initialize. E.g. .dev and .can_sleep shall be set up
properly.
+- Nominally set all handlers to handle_bad_irq() in the setup call and pass
+ handle_bad_irq() as flow handler parameter in gpiochip_irqchip_add() if it is
+ expected for GPIO driver that irqchip .set_type() callback have to be called
+ before using/enabling GPIO IRQ. Then set the handler to handle_level_irq()
+ and/or handle_edge_irq() in the irqchip .set_type() callback depending on
+ what your controller supports.
+
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
@@ -169,6 +220,31 @@ When implementing an irqchip inside a GPIO driver, these two functions should
typically be called in the .startup() and .shutdown() callbacks from the
irqchip.
+Real-Time compliance for GPIO IRQ chips
+---------------------------------------
+
+Any provider of irqchips needs to be carefully tailored to support Real Time
+preemption. It is desireable that all irqchips in the GPIO subsystem keep this
+in mind and does the proper testing to assure they are real time-enabled.
+So, pay attention on above " RT_FULL:" notes, please.
+The following is a checklist to follow when preparing a driver for real
+time-compliance:
+
+- ensure spinlock_t is not used as part irq_chip implementation;
+- ensure that sleepable APIs are not used as part irq_chip implementation.
+ If sleepable APIs have to be used, these can be done from the .irq_bus_lock()
+ and .irq_bus_unlock() callbacks;
+- Chained GPIO irqchips: ensure spinlock_t or any sleepable APIs are not used
+ from chained IRQ handler;
+- Generic chained GPIO irqchips: take care about generic_handle_irq() calls and
+ apply corresponding W/A;
+- Chained GPIO irqchips: get rid of chained IRQ handler and use generic irq
+ handler if possible :)
+- regmap_mmio: Sry, but you are in trouble :( if MMIO regmap is used as for
+ GPIO IRQ chip implementation;
+- Test your driver with the appropriate in-kernel real time test cases for both
+ level and edge IRQs.
+
Requesting self-owned GPIO pins
-------------------------------
@@ -190,3 +266,7 @@ gpiochip_free_own_desc().
These functions must be used with care since they do not affect module use
count. Do not use the functions to request gpio descriptors not owned by the
calling driver.
+
+[1] http://www.spinics.net/lists/linux-omap/msg120425.html
+[2] https://lkml.org/lkml/2015/9/25/494
+[3] https://lkml.org/lkml/2015/9/25/495