Commit 1b2951dd authored by Linus Torvalds's avatar Linus Torvalds

Merge tag 'gpio-v4.17-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio

Pull GPIO updates from Linus Walleij:
 "This is the bulk of GPIO changes for the v4.17 kernel cycle:

  New drivers:

   - Nintendo Wii GameCube GPIO, known as "Hollywood"

   - Raspberry Pi mailbox service GPIO expander

   - Spreadtrum main SC9860 SoC and IEC GPIO controllers.

  Improvements:

   - Implemented .get_multiple() callback for most of the
     high-performance industrial GPIO cards for the ISA bus.

   - ISA GPIO drivers now select the ISA_BUS_API instead of depending on
     it. This is merged with the same pattern for all the ISA drivers
     and some other Kconfig cleanups related to this.

  Cleanup:

   - Delete the TZ1090 GPIO drivers following the deletion of this SoC
     from the ARM tree.

   - Move the documentation over to driver-api to conform with the rest
     of the kernel documentation build.

   - Continue to make the GPIO drivers include only
     <linux/gpio/driver.h> and not the too broad <linux/gpio.h> that we
     want to get rid of.

   - Managed to remove VLA allocation from two drivers pending more
     fixes in this area for the next merge window.

   - Misc janitorial fixes"

* tag 'gpio-v4.17-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-gpio: (77 commits)
  gpio: Add Spreadtrum PMIC EIC driver support
  gpio: Add Spreadtrum EIC driver support
  dt-bindings: gpio: Add Spreadtrum EIC controller documentation
  gpio: ath79: Fix potential NULL dereference in ath79_gpio_probe()
  pinctrl: qcom: Don't allow protected pins to be requested
  gpiolib: Support 'gpio-reserved-ranges' property
  gpiolib: Change bitmap allocation to kmalloc_array
  gpiolib: Extract mask allocation into subroutine
  dt-bindings: gpio: Add a gpio-reserved-ranges property
  gpio: mockup: fix a potential crash when creating debugfs entries
  gpio: pca953x: add compatibility for pcal6524 and pcal9555a
  gpio: dwapb: Add support for a bus clock
  gpio: Remove VLA from xra1403 driver
  gpio: Remove VLA from MAX3191X driver
  gpio: ws16c48: Implement get_multiple callback
  gpio: gpio-mm: Implement get_multiple callback
  gpio: 104-idi-48: Implement get_multiple callback
  gpio: 104-dio-48e: Implement get_multiple callback
  gpio: pcie-idio-24: Implement get_multiple/set_multiple callbacks
  gpio: pci-idio-16: Implement get_multiple callback
  ...
parents 06dd3dfe 348f3cde
Spreadtrum EIC controller bindings
The EIC is the abbreviation of external interrupt controller, which can
be used only in input mode. The Spreadtrum platform has 2 EIC controllers,
one is in digital chip, and another one is in PMIC. The digital chip EIC
controller contains 4 sub-modules: EIC-debounce, EIC-latch, EIC-async and
EIC-sync. But the PMIC EIC controller contains only one EIC-debounce sub-
module.
The EIC-debounce sub-module provides up to 8 source input signal
connections. A debounce mechanism is used to capture the input signals'
stable status (millisecond resolution) and a single-trigger mechanism
is introduced into this sub-module to enhance the input event detection
reliability. In addition, this sub-module's clock can be shut off
automatically to reduce power dissipation. Moreover the debounce range
is from 1ms to 4s with a step size of 1ms. The input signal will be
ignored if it is asserted for less than 1 ms.
The EIC-latch sub-module is used to latch some special power down signals
and generate interrupts, since the EIC-latch does not depend on the APB
clock to capture signals.
The EIC-async sub-module uses a 32kHz clock to capture the short signals
(microsecond resolution) to generate interrupts by level or edge trigger.
The EIC-sync is similar with GPIO's input function, which is a synchronized
signal input register. It can generate interrupts by level or edge trigger
when detecting input signals.
Required properties:
- compatible: Should be one of the following:
"sprd,sc9860-eic-debounce",
"sprd,sc9860-eic-latch",
"sprd,sc9860-eic-async",
"sprd,sc9860-eic-sync",
"sprd,sc27xx-eic".
- reg: Define the base and range of the I/O address space containing
the GPIO controller registers.
- gpio-controller: Marks the device node as a GPIO controller.
- #gpio-cells: Should be <2>. The first cell is the gpio number and
the second cell is used to specify optional parameters.
- interrupt-controller: Marks the device node as an interrupt controller.
- #interrupt-cells: Should be <2>. Specifies the number of cells needed
to encode interrupt source.
- interrupts: Should be the port interrupt shared by all the gpios.
Example:
eic_debounce: gpio@40210000 {
compatible = "sprd,sc9860-eic-debounce";
reg = <0 0x40210000 0 0x80>;
gpio-controller;
#gpio-cells = <2>;
interrupt-controller;
#interrupt-cells = <2>;
interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>;
};
eic_latch: gpio@40210080 {
compatible = "sprd,sc9860-eic-latch";
reg = <0 0x40210080 0 0x20>;
gpio-controller;
#gpio-cells = <2>;
interrupt-controller;
#interrupt-cells = <2>;
interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>;
};
eic_async: gpio@402100a0 {
compatible = "sprd,sc9860-eic-async";
reg = <0 0x402100a0 0 0x20>;
gpio-controller;
#gpio-cells = <2>;
interrupt-controller;
#interrupt-cells = <2>;
interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>;
};
eic_sync: gpio@402100c0 {
compatible = "sprd,sc9860-eic-sync";
reg = <0 0x402100c0 0 0x20>;
gpio-controller;
#gpio-cells = <2>;
interrupt-controller;
#interrupt-cells = <2>;
interrupts = <GIC_SPI 52 IRQ_TYPE_LEVEL_HIGH>;
};
pmic_eic: gpio@300 {
compatible = "sprd,sc27xx-eic";
reg = <0x300>;
interrupt-parent = <&sc2731_pmic>;
interrupts = <5 IRQ_TYPE_LEVEL_HIGH>;
gpio-controller;
#gpio-cells = <2>;
interrupt-controller;
#interrupt-cells = <2>;
};
......@@ -16,6 +16,8 @@ Required properties:
nxp,pca9574
nxp,pca9575
nxp,pca9698
nxp,pcal6524
nxp,pcal9555a
maxim,max7310
maxim,max7312
maxim,max7313
......
Spreadtrum GPIO controller bindings
The controller's registers are organized as sets of sixteen 16-bit
registers with each set controlling a bank of up to 16 pins. A single
interrupt is shared for all of the banks handled by the controller.
Required properties:
- compatible: Should be "sprd,sc9860-gpio".
- reg: Define the base and range of the I/O address space containing
the GPIO controller registers.
- gpio-controller: Marks the device node as a GPIO controller.
- #gpio-cells: Should be <2>. The first cell is the gpio number and
the second cell is used to specify optional parameters.
- interrupt-controller: Marks the device node as an interrupt controller.
- #interrupt-cells: Should be <2>. Specifies the number of cells needed
to encode interrupt source.
- interrupts: Should be the port interrupt shared by all the gpios.
Example:
ap_gpio: gpio@40280000 {
compatible = "sprd,sc9860-gpio";
reg = <0 0x40280000 0 0x1000>;
gpio-controller;
#gpio-cells = <2>;
interrupt-controller;
#interrupt-cells = <2>;
interrupts = <GIC_SPI 50 IRQ_TYPE_LEVEL_HIGH>;
};
ImgTec TZ1090 PDC GPIO Controller
Required properties:
- compatible: Compatible property value should be "img,tz1090-pdc-gpio".
- reg: Physical base address of the controller and length of memory mapped
region. This starts at and cover the SOC_GPIO_CONTROL registers.
- gpio-controller: Specifies that the node is a gpio controller.
- #gpio-cells: Should be 2. The syntax of the gpio specifier used by client
nodes should have the following values.
<[phandle of the gpio controller node]
[PDC gpio number]
[gpio flags]>
Values for gpio specifier:
- GPIO number: a value in the range 0 to 6.
- GPIO flags: bit field of flags, as defined in <dt-bindings/gpio/gpio.h>.
Only the following flags are supported:
GPIO_ACTIVE_HIGH
GPIO_ACTIVE_LOW
Optional properties:
- gpio-ranges: Mapping to pin controller pins (as described in
Documentation/devicetree/bindings/gpio/gpio.txt)
- interrupts: Individual syswake interrupts (other GPIOs cannot interrupt)
Example:
pdc_gpios: gpio-controller@2006500 {
gpio-controller;
#gpio-cells = <2>;
compatible = "img,tz1090-pdc-gpio";
reg = <0x02006500 0x100>;
interrupt-parent = <&pdc>;
interrupts = <8 IRQ_TYPE_NONE>, /* Syswake 0 */
<9 IRQ_TYPE_NONE>, /* Syswake 1 */
<10 IRQ_TYPE_NONE>; /* Syswake 2 */
gpio-ranges = <&pdc_pinctrl 0 0 7>;
};
ImgTec TZ1090 GPIO Controller
Required properties:
- compatible: Compatible property value should be "img,tz1090-gpio".
- reg: Physical base address of the controller and length of memory mapped
region.
- #address-cells: Should be 1 (for bank subnodes)
- #size-cells: Should be 0 (for bank subnodes)
- Each bank of GPIOs should have a subnode to represent it.
Bank subnode required properties:
- reg: Index of bank in the range 0 to 2.
- gpio-controller: Specifies that the node is a gpio controller.
- #gpio-cells: Should be 2. The syntax of the gpio specifier used by client
nodes should have the following values.
<[phandle of the gpio controller node]
[gpio number within the gpio bank]
[gpio flags]>
Values for gpio specifier:
- GPIO number: a value in the range 0 to 29.
- GPIO flags: bit field of flags, as defined in <dt-bindings/gpio/gpio.h>.
Only the following flags are supported:
GPIO_ACTIVE_HIGH
GPIO_ACTIVE_LOW
Bank subnode optional properties:
- gpio-ranges: Mapping to pin controller pins (as described in
Documentation/devicetree/bindings/gpio/gpio.txt)
- interrupts: Interrupt for the entire bank
- interrupt-controller: Specifies that the node is an interrupt controller
- #interrupt-cells: Should be 2. The syntax of the interrupt specifier used by
client nodes should have the following values.
<[phandle of the interurupt controller]
[gpio number within the gpio bank]
[irq flags]>
Values for irq specifier:
- GPIO number: a value in the range 0 to 29
- IRQ flags: value to describe edge and level triggering, as defined in
<dt-bindings/interrupt-controller/irq.h>. Only the following flags are
supported:
IRQ_TYPE_EDGE_RISING
IRQ_TYPE_EDGE_FALLING
IRQ_TYPE_EDGE_BOTH
IRQ_TYPE_LEVEL_HIGH
IRQ_TYPE_LEVEL_LOW
Example:
gpios: gpio-controller@2005800 {
#address-cells = <1>;
#size-cells = <0>;
compatible = "img,tz1090-gpio";
reg = <0x02005800 0x90>;
/* bank 0 with an interrupt */
gpios0: bank@0 {
#gpio-cells = <2>;
#interrupt-cells = <2>;
reg = <0>;
interrupts = <13 IRQ_TYPE_LEVEL_HIGH>;
gpio-controller;
gpio-ranges = <&pinctrl 0 0 30>;
interrupt-controller;
};
/* bank 2 without interrupt */
gpios2: bank@2 {
#gpio-cells = <2>;
reg = <2>;
gpio-controller;
gpio-ranges = <&pinctrl 0 60 30>;
};
};
......@@ -151,9 +151,9 @@ in a lot of designs, some using all 32 bits, some using 18 and some using
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.
additional set of tuples is needed to specify which GPIOs are unusable, with
the gpio-reserved-ranges binding. This property indicates the start and size
of the GPIOs that can't be used.
Optionally, a GPIO controller may have a "gpio-line-names" property. This is
an array of strings defining the names of the GPIO lines going out of the
......@@ -178,6 +178,7 @@ gpio-controller@00000000 {
gpio-controller;
#gpio-cells = <2>;
ngpios = <18>;
gpio-reserved-ranges = <0 4>, <12 2>;
gpio-line-names = "MMC-CD", "MMC-WP", "VDD eth", "RST eth", "LED R",
"LED G", "LED B", "Col A", "Col B", "Col C", "Col D",
"Row A", "Row B", "Row C", "Row D", "NMI button",
......
Nintendo Wii (Hollywood) GPIO controller
Required properties:
- compatible: "nintendo,hollywood-gpio
- reg: Physical base address and length of the controller's registers.
- gpio-controller: Marks the device node as a GPIO controller.
- #gpio-cells: Should be <2>. The first cell is the pin number and the
second cell is used to specify optional parameters:
- bit 0 specifies polarity (0 for normal, 1 for inverted).
Optional properties:
- ngpios: see Documentation/devicetree/bindings/gpio/gpio.txt
- interrupt-controller: Marks the device node as an interrupt controller.
- #interrupt-cells: Should be two.
- interrupts: Interrupt specifier for the controller's Broadway (PowerPC)
interrupt.
- interrupt-parent: phandle of the parent interrupt controller.
Example:
GPIO: gpio@d8000c0 {
#gpio-cells = <2>;
compatible = "nintendo,hollywood-gpio";
reg = <0x0d8000c0 0x40>;
gpio-controller;
ngpios = <24>;
}
Raspberry Pi GPIO expander
The Raspberry Pi 3 GPIO expander is controlled by the VC4 firmware. The
firmware exposes a mailbox interface that allows the ARM core to control the
GPIO lines on the expander.
The Raspberry Pi GPIO expander node must be a child node of the Raspberry Pi
firmware node.
Required properties:
- compatible : Should be "raspberrypi,firmware-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
Example:
firmware: firmware-rpi {
compatible = "raspberrypi,bcm2835-firmware";
mboxes = <&mailbox>;
expgpio: gpio {
compatible = "raspberrypi,firmware-gpio";
gpio-controller;
#gpio-cells = <2>;
};
};
......@@ -152,14 +152,7 @@ Nintendo Wii device tree
1.l) The General Purpose I/O (GPIO) controller node
Represents the dual access 32 GPIO controller interface.
Required properties:
- #gpio-cells : <2>
- compatible : should be "nintendo,hollywood-gpio"
- reg : should contain the IPC registers location and length
- gpio-controller
see Documentation/devicetree/bindings/gpio/nintendo,hollywood-gpio.txt
1.m) The control node
......
=============
GPIO Mappings
=============
......@@ -23,7 +24,7 @@ device tree bindings for your controller.
GPIOs mappings are defined in the consumer device's node, in a property named
<function>-gpios, where <function> is the function the driver will request
through gpiod_get(). For example:
through gpiod_get(). For example::
foo_device {
compatible = "acme,foo";
......@@ -40,7 +41,7 @@ it but are only supported for compatibility reasons and should not be used for
newer bindings since it has been deprecated.
This property will make GPIOs 15, 16 and 17 available to the driver under the
"led" function, and GPIO 1 as the "power" GPIO:
"led" function, and GPIO 1 as the "power" GPIO::
struct gpio_desc *red, *green, *blue, *power;
......@@ -60,13 +61,13 @@ looked up by the gpiod functions internally) used in the device tree. With above
Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio")
with the string passed in con_id to get the resulting string
(snprintf(... "%s-%s", con_id, gpio_suffixes[]).
(``snprintf(... "%s-%s", con_id, gpio_suffixes[]``).
ACPI
----
ACPI also supports function names for GPIOs in a similar fashion to DT.
The above DT example can be converted to an equivalent ACPI description
with the help of _DSD (Device Specific Data), introduced in ACPI 5.1:
with the help of _DSD (Device Specific Data), introduced in ACPI 5.1::
Device (FOO) {
Name (_CRS, ResourceTemplate () {
......@@ -105,12 +106,12 @@ Documentation/acpi/gpio-properties.txt.
Platform Data
-------------
Finally, GPIOs can be bound to devices and functions using platform data. Board
files that desire to do so need to include the following header:
files that desire to do so need to include the following header::
#include <linux/gpio/machine.h>
GPIOs are mapped by the means of tables of lookups, containing instances of the
gpiod_lookup structure. Two macros are defined to help declaring such mappings:
gpiod_lookup structure. Two macros are defined to help declaring such mappings::
GPIO_LOOKUP(chip_label, chip_hwnum, con_id, flags)
GPIO_LOOKUP_IDX(chip_label, chip_hwnum, con_id, idx, flags)
......@@ -141,22 +142,24 @@ end. The 'dev_id' field of the table is the identifier of the device that will
make use of these GPIOs. It can be NULL, in which case it will be matched for
calls to gpiod_get() with a NULL device.
struct gpiod_lookup_table gpios_table = {
.dev_id = "foo.0",
.table = {
GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH),
GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH),
GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH),
GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW),
{ },
},
};
.. code-block:: c
struct gpiod_lookup_table gpios_table = {
.dev_id = "foo.0",
.table = {
GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH),
GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH),
GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH),
GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW),
{ },
},
};
And the table can be added by the board code as follows:
And the table can be added by the board code as follows::
gpiod_add_lookup_table(&gpios_table);
The driver controlling "foo.0" will then be able to obtain its GPIOs as follows:
The driver controlling "foo.0" will then be able to obtain its GPIOs as follows::
struct gpio_desc *red, *green, *blue, *power;
......
================================
GPIO Descriptor Driver Interface
================================
......@@ -53,9 +54,9 @@ common to each controller of that type:
The code implementing a gpio_chip should support multiple instances of the
controller, possibly using the driver model. That code will configure each
gpio_chip and issue gpiochip_add[_data]() or devm_gpiochip_add_data().
Removing a GPIO controller should be rare; use [devm_]gpiochip_remove() when
it is unavoidable.
gpio_chip and issue ``gpiochip_add[_data]()`` or ``devm_gpiochip_add_data()``.
Removing a GPIO controller should be rare; use ``[devm_]gpiochip_remove()``
when it is unavoidable.
Often a gpio_chip is part of an instance-specific structure with states not
exposed by the GPIO interfaces, such as addressing, power management, and more.
......@@ -115,7 +116,7 @@ GPIOs with open drain/source support
Open drain (CMOS) or open collector (TTL) means the line is not actively driven
high: instead you provide the drain/collector as output, so when the transistor
is not open, it will present a high-impedance (tristate) to the external rail.
is not open, it will present a high-impedance (tristate) to the external rail::
CMOS CONFIGURATION TTL CONFIGURATION
......@@ -148,19 +149,19 @@ level-shift to the higher VDD.
Integrated electronics often have an output driver stage in the form of a CMOS
"totem-pole" with one N-MOS and one P-MOS transistor where one of them drives
the line high and one of them drives the line low. This is called a push-pull
output. The "totem-pole" looks like so:
VDD
|
OD ||--+
+--/ ---o|| P-MOS-FET
| ||--+
IN --+ +----- out
| ||--+
+--/ ----|| N-MOS-FET
OS ||--+
|
GND
output. The "totem-pole" looks like so::
VDD
|
OD ||--+
+--/ ---o|| P-MOS-FET
| ||--+
IN --+ +----- out
| ||--+
+--/ ----|| N-MOS-FET
OS ||--+
|
GND
The desired output signal (e.g. coming directly from some GPIO output register)
arrives at IN. The switches named "OD" and "OS" are normally closed, creating
......@@ -219,8 +220,9 @@ systems simultaneously: gpio and irq.
RT_FULL: a realtime compliant GPIO driver should not use spinlock_t or any
sleepable APIs (like PM runtime) as part of its irq_chip implementation.
- 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()
* 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].
......@@ -232,12 +234,12 @@ GPIO irqchips usually fall in one of two categories:
system interrupt controller. This means that 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:
sequence in its interrupt handler::
static irqreturn_t foo_gpio_irq(int irq, void *data)
chained_irq_enter(...);
generic_handle_irq(...);
chained_irq_exit(...);
static irqreturn_t foo_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: no
......@@ -252,7 +254,7 @@ GPIO irqchips usually fall in one of two categories:
(for example, see [3]).
Know W/A: The generic_handle_irq() is expected to be called with IRQ disabled,
so the IRQ core will complain if it is called from an IRQ handler which is
forced to a thread. The "fake?" raw lock can be used to W/A this problem:
forced to a 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)
......@@ -265,11 +267,11 @@ GPIO irqchips usually fall in one of two categories:
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:
its interrupt handler::
static irqreturn_t gpio_rcar_irq_handler(int irq, void *dev_id)
for each detected GPIO IRQ
generic_handle_irq(...);
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
......@@ -282,11 +284,11 @@ GPIO irqchips usually fall in one of two categories:
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:
this in its interrupt handler::
static irqreturn_t foo_gpio_irq(int irq, void *data)
...
handle_nested_irq(irq);
static irqreturn_t foo_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
......@@ -359,12 +361,12 @@ below exists.
Locking IRQ usage
-----------------
Input GPIOs can be used as IRQ signals. When this happens, a driver is requested
to mark the GPIO as being used as an IRQ:
to mark the GPIO as being used as an IRQ::
int gpiochip_lock_as_irq(struct gpio_chip *chip, unsigned int offset)
This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock
is released:
is released::
void gpiochip_unlock_as_irq(struct gpio_chip *chip, unsigned int offset)
......@@ -408,7 +410,7 @@ Sometimes it is useful to allow a GPIO chip driver to request its own GPIO
descriptors through the gpiolib API. Using gpio_request() for this purpose
does not help since it pins the module to the kernel forever (it calls
try_module_get()). A GPIO driver can use the following functions instead
to request and free descriptors without being pinned to the kernel forever.
to request and free descriptors without being pinned to the kernel forever::
struct gpio_desc *gpiochip_request_own_desc(struct gpio_desc *desc,
const char *label)
......@@ -422,6 +424,6 @@ 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
* [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
============================
Subsystem drivers using GPIO
============================
......
......@@ -2,6 +2,18 @@
General Purpose Input/Output (GPIO)
===================================
Contents:
.. toctree::
:maxdepth: 2
intro
driver
consumer
board
drivers-on-gpio
legacy
Core
====
......@@ -11,15 +23,6 @@ Core
.. kernel-doc:: drivers/gpio/gpiolib.c
:export:
Legacy API
==========
The functions listed in this section are deprecated. The GPIO descriptor based
API described above should be used in new code.
.. kernel-doc:: drivers/gpio/gpiolib-legacy.c
:export:
ACPI support
============
......
============
Introduction
============
GPIO Interfaces
===============
......@@ -9,9 +14,9 @@ Due to the history of GPIO interfaces in the kernel, there are two different
ways to obtain and use GPIOs:
- The descriptor-based interface is the preferred way to manipulate GPIOs,
and is described by all the files in this directory excepted gpio-legacy.txt.
and is described by all the files in this directory excepted gpio-legacy.txt.
- The legacy integer-based interface which is considered deprecated (but still
usable for compatibility reasons) is documented in gpio-legacy.txt.
usable for compatibility reasons) is documented in gpio-legacy.txt.
The remainder of this document applies to the new descriptor-based interface.
gpio-legacy.txt contains the same information applied to the legacy
......
GPIO Interfaces
======================
Legacy GPIO Interfaces
======================
This provides an overview of GPIO access conventions on Linux.
......@@ -129,7 +131,7 @@ The first thing a system should do with a GPIO is allocate it, using
the gpio_request() call; see later.
One of the next things to do with a GPIO, often in board setup code when
setting up a platform_device using the GPIO, is mark its direction:
setting up a platform_device using the GPIO, is mark its direction::
/* set as input or output, returning 0 or negative errno */
int gpio_direction_input(unsigned gpio);
......@@ -164,7 +166,7 @@ Those don't need to sleep, and can safely be done from inside hard
(nonthreaded) IRQ handlers and similar contexts.
Use the following calls to access such GPIOs,
for which gpio_cansleep() will always return false (see below):
for which gpio_cansleep() will always return false (see below)::
/* GPIO INPUT: return zero or nonzero */
int gpio_get_value(unsigned gpio);
......@@ -201,11 +203,11 @@ This requires sleeping, which can't be done from inside IRQ handlers.
Platforms that support this type of GPIO distinguish them from other GPIOs
by returning nonzero from this call (which requires a valid GPIO number,
which should have been previously allocated with gpio_request):
which should have been previously allocated with gpio_request)::
int gpio_cansleep(unsigned gpio);
To access such GPIOs, a different set of accessors is defined:
To access such GPIOs, a different set of accessors is defined::
/* GPIO INPUT: return zero or nonzero, might sleep */
int gpio_get_value_cansleep(unsigned gpio);
......@@ -222,27 +224,27 @@ Other than the fact that these accessors might sleep, and will work
on GPIOs that can't be accessed from hardIRQ handlers, these calls act
the same as the spinlock-safe calls.
** IN ADDITION ** calls to setup and configure such GPIOs must be made
**IN ADDITION** calls to setup and configure such GPIOs must be made
from contexts which may sleep, since they may need to access the GPIO
controller chip too: (These setup calls are usually made from board
setup or driver probe/teardown code, so this is an easy constraint.)
controller chip too (These setup calls are usually made from board