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

19 files changed, 357 insertions, 299 deletions

diff --git a/Documentation/devicetree/bindings/gpio/gpio-eic-sprd.txt b/Documentation/devicetree/bindings/gpio/gpio-eic-sprd.txt
new file mode 100644
index 000000000000..93d98d09d92b
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/gpio-eic-sprd.txt
@@ -0,0 +1,97 @@
+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>;
+	};
diff --git a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt
index 0d0158728f89..d2a937682836 100644
--- a/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt
+++ b/Documentation/devicetree/bindings/gpio/gpio-pca953x.txt
@@ -16,6 +16,8 @@ Required properties:
 	nxp,pca9574
 	nxp,pca9575
 	nxp,pca9698
+	nxp,pcal6524
+	nxp,pcal9555a
 	maxim,max7310
 	maxim,max7312
 	maxim,max7313
diff --git a/Documentation/devicetree/bindings/gpio/gpio-sprd.txt b/Documentation/devicetree/bindings/gpio/gpio-sprd.txt
new file mode 100644
index 000000000000..eca97d45388f
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/gpio-sprd.txt
@@ -0,0 +1,28 @@
+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>;
+	};
diff --git a/Documentation/devicetree/bindings/gpio/gpio-tz1090-pdc.txt b/Documentation/devicetree/bindings/gpio/gpio-tz1090-pdc.txt
deleted file mode 100644
index 528f5ef5a893..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-tz1090-pdc.txt
+++ /dev/null
@@ -1,45 +0,0 @@
-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>;
-	};
diff --git a/Documentation/devicetree/bindings/gpio/gpio-tz1090.txt b/Documentation/devicetree/bindings/gpio/gpio-tz1090.txt
deleted file mode 100644
index b05a90e0ab29..000000000000
--- a/Documentation/devicetree/bindings/gpio/gpio-tz1090.txt
+++ /dev/null
@@ -1,88 +0,0 @@
-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>;
-		};
-	};
-
-
diff --git a/Documentation/devicetree/bindings/gpio/gpio.txt b/Documentation/devicetree/bindings/gpio/gpio.txt
index b5de08e3b1a2..a7c31de29362 100644
--- a/Documentation/devicetree/bindings/gpio/gpio.txt
+++ b/Documentation/devicetree/bindings/gpio/gpio.txt
@@ -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",
diff --git a/Documentation/devicetree/bindings/gpio/nintendo,hollywood-gpio.txt b/Documentation/devicetree/bindings/gpio/nintendo,hollywood-gpio.txt
new file mode 100644
index 000000000000..20fc72d9e61e
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/nintendo,hollywood-gpio.txt
@@ -0,0 +1,27 @@
+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>;
+	}
diff --git a/Documentation/devicetree/bindings/gpio/raspberrypi,firmware-gpio.txt b/Documentation/devicetree/bindings/gpio/raspberrypi,firmware-gpio.txt
new file mode 100644
index 000000000000..ce97265e23ba
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/raspberrypi,firmware-gpio.txt
@@ -0,0 +1,30 @@
+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>;
+	 };
+};
diff --git a/Documentation/devicetree/bindings/powerpc/nintendo/wii.txt b/Documentation/devicetree/bindings/powerpc/nintendo/wii.txt
index 36afa322b04b..a3dc4b9fa11a 100644
--- a/Documentation/devicetree/bindings/powerpc/nintendo/wii.txt
+++ b/Documentation/devicetree/bindings/powerpc/nintendo/wii.txt
@@ -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
 
diff --git a/Documentation/gpio/board.txt b/Documentation/driver-api/gpio/board.rst
index 659bb19f5b3c..25d62b2e9fd0 100644
--- a/Documentation/gpio/board.txt
+++ b/Documentation/driver-api/gpio/board.rst
@@ -1,3 +1,4 @@
+=============
 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;
 
diff --git a/Documentation/gpio/consumer.txt b/Documentation/driver-api/gpio/consumer.rst
index d53e5b5cfc9c..c71a50d85b50 100644
--- a/Documentation/gpio/consumer.txt
+++ b/Documentation/driver-api/gpio/consumer.rst
@@ -1,3 +1,4 @@
+==================================
 GPIO Descriptor Consumer Interface
 ==================================
 
@@ -30,10 +31,10 @@ warnings. These stubs are used for two use cases:
   be met with console warnings that may be perceived as intimidating.
 
 All the functions that work with the descriptor-based GPIO interface are
-prefixed with gpiod_. The gpio_ prefix is used for the legacy interface. No
-other function in the kernel should use these prefixes. The use of the legacy
-functions is strongly discouraged, new code should use <linux/gpio/consumer.h>
-and descriptors exclusively.
+prefixed with ``gpiod_``. The ``gpio_`` prefix is used for the legacy
+interface. No other function in the kernel should use these prefixes. The use
+of the legacy functions is strongly discouraged, new code should use
+<linux/gpio/consumer.h> and descriptors exclusively.
 
 
 Obtaining and Disposing GPIOs
@@ -43,13 +44,13 @@ With the descriptor-based interface, GPIOs are identified with an opaque,
 non-forgeable handler that must be obtained through a call to one of the
 gpiod_get() functions. Like many other kernel subsystems, gpiod_get() takes the
 device that will use the GPIO and the function the requested GPIO is supposed to
-fulfill:
+fulfill::
 
 	struct gpio_desc *gpiod_get(struct device *dev, const char *con_id,
 				    enum gpiod_flags flags)
 
 If a function is implemented by using several GPIOs together (e.g. a simple LED
-device that displays digits), an additional index argument can be specified:
+device that displays digits), an additional index argument can be specified::
 
 	struct gpio_desc *gpiod_get_index(struct device *dev,
 					  const char *con_id, unsigned int idx,
@@ -84,7 +85,7 @@ occurred while trying to acquire it. This is useful to discriminate between mere
 errors and an absence of GPIO for optional GPIO parameters. For the common
 pattern where a GPIO is optional, the gpiod_get_optional() and
 gpiod_get_index_optional() functions can be used. These functions return NULL
-instead of -ENOENT if no GPIO has been assigned to the requested function:
+instead of -ENOENT if no GPIO has been assigned to the requested function::
 
 	struct gpio_desc *gpiod_get_optional(struct device *dev,
 					     const char *con_id,
@@ -101,14 +102,14 @@ This is helpful to driver authors, since they do not need to special case
 -ENOSYS return codes.  System integrators should however be careful to enable
 gpiolib on systems that need it.
 
-For a function using multiple GPIOs all of those can be obtained with one call:
+For a function using multiple GPIOs all of those can be obtained with one call::
 
 	struct gpio_descs *gpiod_get_array(struct device *dev,
 					   const char *con_id,
 					   enum gpiod_flags flags)
 
 This function returns a struct gpio_descs which contains an array of
-descriptors:
+descriptors::
 
 	struct gpio_descs {
 		unsigned int ndescs;
@@ -116,13 +117,13 @@ descriptors:
 	}
 
 The following function returns NULL instead of -ENOENT if no GPIOs have been
-assigned to the requested function:
+assigned to the requested function::
 
 	struct gpio_descs *gpiod_get_array_optional(struct device *dev,
 						    const char *con_id,
 						    enum gpiod_flags flags)
 
-Device-managed variants of these functions are also defined:
+Device-managed variants of these functions are also defined::
 
 	struct gpio_desc *devm_gpiod_get(struct device *dev, const char *con_id,
 					 enum gpiod_flags flags)
@@ -149,11 +150,11 @@ Device-managed variants of these functions are also defined:
 							 const char *con_id,
 							 enum gpiod_flags flags)
 
-A GPIO descriptor can be disposed of using the gpiod_put() function:
+A GPIO descriptor can be disposed of using the gpiod_put() function::
 
 	void gpiod_put(struct gpio_desc *desc)
 
-For an array of GPIOs this function can be used:
+For an array of GPIOs this function can be used::
 
 	void gpiod_put_array(struct gpio_descs *descs)
 
@@ -161,7 +162,7 @@ It is strictly forbidden to use a descriptor after calling these functions.
 It is also not allowed to individually release descriptors (using gpiod_put())
 from an array acquired with gpiod_get_array().
 
-The device-managed variants are, unsurprisingly:
+The device-managed variants are, unsurprisingly::
 
 	void devm_gpiod_put(struct device *dev, struct gpio_desc *desc)
 
@@ -175,7 +176,7 @@ Setting Direction
 -----------------
 The first thing a driver must do with a GPIO is setting its direction. If no
 direction-setting flags have been given to gpiod_get*(), this is done by
-invoking one of the gpiod_direction_*() functions:
+invoking one of the gpiod_direction_*() functions::
 
 	int gpiod_direction_input(struct gpio_desc *desc)
 	int gpiod_direction_output(struct gpio_desc *desc, int value)
@@ -189,7 +190,7 @@ of early board setup.
 For output GPIOs, the value provided becomes the initial output value. This
 helps avoid signal glitching during system startup.
 
-A driver can also query the current direction of a GPIO:
+A driver can also query the current direction of a GPIO::
 
 	int gpiod_get_direction(const struct gpio_desc *desc)
 
@@ -206,7 +207,7 @@ Most GPIO controllers can be accessed with memory read/write instructions. Those
 don't need to sleep, and can safely be done from inside hard (non-threaded) IRQ
 handlers and similar contexts.
 
-Use the following calls to access GPIOs from an atomic context:
+Use the following calls to access GPIOs from an atomic context::
 
 	int gpiod_get_value(const struct gpio_desc *desc);
 	void gpiod_set_value(struct gpio_desc *desc, int value);
@@ -231,11 +232,11 @@ head of a queue to transmit a command and get its response. 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:
+returning nonzero from this call::
 
 	int gpiod_cansleep(const struct gpio_desc *desc)
 
-To access such GPIOs, a different set of accessors is defined:
+To access such GPIOs, a different set of accessors is defined::
 
 	int gpiod_get_value_cansleep(const struct gpio_desc *desc)
 	void gpiod_set_value_cansleep(struct gpio_desc *desc, int value)
@@ -271,23 +272,23 @@ As an example, if the active low property for a dedicated GPIO is set, and the
 gpiod_set_(array)_value_xxx() passes "asserted" ("1"), the physical line level
 will be driven low.
 
-To summarize:
-
-Function (example)                 line property          physical line
-gpiod_set_raw_value(desc, 0);      don't care             low
-gpiod_set_raw_value(desc, 1);      don't care             high
-gpiod_set_value(desc, 0);          default (active high)  low
-gpiod_set_value(desc, 1);          default (active high)  high
-gpiod_set_value(desc, 0);          active low             high
-gpiod_set_value(desc, 1);          active low             low
-gpiod_set_value(desc, 0);          default (active high)  low
-gpiod_set_value(desc, 1);          default (active high)  high
-gpiod_set_value(desc, 0);          open drain             low
-gpiod_set_value(desc, 1);          open drain             high impedance
-gpiod_set_value(desc, 0);          open source            high impedance
-gpiod_set_value(desc, 1);          open source            high
-
-It is possible to override these semantics using the *set_raw/'get_raw functions
+To summarize::
+
+  Function (example)                 line property          physical line
+  gpiod_set_raw_value(desc, 0);      don't care             low
+  gpiod_set_raw_value(desc, 1);      don't care             high
+  gpiod_set_value(desc, 0);          default (active high)  low
+  gpiod_set_value(desc, 1);          default (active high)  high
+  gpiod_set_value(desc, 0);          active low             high
+  gpiod_set_value(desc, 1);          active low             low
+  gpiod_set_value(desc, 0);          default (active high)  low
+  gpiod_set_value(desc, 1);          default (active high)  high
+  gpiod_set_value(desc, 0);          open drain             low
+  gpiod_set_value(desc, 1);          open drain             high impedance
+  gpiod_set_value(desc, 0);          open source            high impedance
+  gpiod_set_value(desc, 1);          open source            high
+
+It is possible to override these semantics using the set_raw/get_raw functions
 but it should be avoided as much as possible, especially by system-agnostic drivers
 which should not need to care about the actual physical line level and worry about
 the logical value instead.
@@ -300,7 +301,7 @@ their device will actually receive, no matter what lies between it and the GPIO
 line.
 
 The following set of calls ignore the active-low or open drain property of a GPIO and
-work on the raw line value:
+work on the raw line value::
 
 	int gpiod_get_raw_value(const struct gpio_desc *desc)
 	void gpiod_set_raw_value(struct gpio_desc *desc, int value)
@@ -308,7 +309,7 @@ work on the raw line value:
 	void gpiod_set_raw_value_cansleep(struct gpio_desc *desc, int value)
 	int gpiod_direction_output_raw(struct gpio_desc *desc, int value)
 
-The active low state of a GPIO can also be queried using the following call:
+The active low state of a GPIO can also be queried using the following call::
 
 	int gpiod_is_active_low(const struct gpio_desc *desc)
 
@@ -318,7 +319,7 @@ should not have to care about the physical line level or open drain semantics.
 
 Access multiple GPIOs with a single function call
 -------------------------------------------------
-The following functions get or set the values of an array of GPIOs:
+The following functions get or set the values of an array of GPIOs::
 
 	int gpiod_get_array_value(unsigned int array_size,
 				  struct gpio_desc **desc_array,
@@ -361,7 +362,7 @@ The functions take three arguments:
 The descriptor array can be obtained using the gpiod_get_array() function
 or one of its variants. If the group of descriptors returned by that function
 matches the desired group of GPIOs, those GPIOs can be accessed by simply using
-the struct gpio_descs returned by gpiod_get_array():
+the struct gpio_descs returned by gpiod_get_array()::
 
 	struct gpio_descs *my_gpio_descs = gpiod_get_array(...);
 	gpiod_set_array_value(my_gpio_descs->ndescs, my_gpio_descs->desc,
@@ -384,7 +385,7 @@ values are stored in value_array rather than passed back as return value.
 GPIOs mapped to IRQs
 --------------------
 GPIO lines can quite often be used as IRQs. You can get the IRQ number
-corresponding to a given GPIO using the following call:
+corresponding to a given GPIO using the following call::
 
 	int gpiod_to_irq(const struct gpio_desc *desc)
 
@@ -424,7 +425,7 @@ Interacting With the Legacy GPIO Subsystem
 Many kernel subsystems still handle GPIOs using the legacy integer-based
 interface. Although it is strongly encouraged to upgrade them to the safer
 descriptor-based API, the following two functions allow you to convert a GPIO
-descriptor into the GPIO integer namespace and vice-versa:
+descriptor into the GPIO integer namespace and vice-versa::
 
 	int desc_to_gpio(const struct gpio_desc *desc)
 	struct gpio_desc *gpio_to_desc(unsigned gpio)
diff --git a/Documentation/gpio/driver.txt b/Documentation/driver-api/gpio/driver.rst
index 3392a0fd4c23..505ee906d7d9 100644
--- a/Documentation/gpio/driver.txt
+++ b/Documentation/driver-api/gpio/driver.rst
@@ -1,3 +1,4 @@
+================================
 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
diff --git a/Documentation/gpio/drivers-on-gpio.txt b/Documentation/driver-api/gpio/drivers-on-gpio.rst
index a2ccbab12eb7..019483868977 100644
--- a/Documentation/gpio/drivers-on-gpio.txt
+++ b/Documentation/driver-api/gpio/drivers-on-gpio.rst
@@ -1,3 +1,4 @@
+============================
 Subsystem drivers using GPIO
 ============================
 
diff --git a/Documentation/driver-api/gpio.rst b/Documentation/driver-api/gpio/index.rst
index 6dd4aa647f27..6a374ded1287 100644
--- a/Documentation/driver-api/gpio.rst
+++ b/Documentation/driver-api/gpio/index.rst
@@ -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
 ============
 
diff --git a/Documentation/gpio/gpio.txt b/Documentation/driver-api/gpio/intro.rst
index cd9b356e88cd..74591489d0b5 100644
--- a/Documentation/gpio/gpio.txt
+++ b/Documentation/driver-api/gpio/intro.rst
@@ -1,3 +1,8 @@
+============
+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
diff --git a/Documentation/gpio/gpio-legacy.txt b/Documentation/driver-api/gpio/legacy.rst
index 8356d0e78f67..5e9421e05f1d 100644
--- a/Documentation/gpio/gpio-legacy.txt
+++ b/Documentation/driver-api/gpio/legacy.rst
@@ -1,4 +1,6 @@
-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
+setup or driver probe/teardown code, so this is an easy constraint.)::
 
-	gpio_direction_input()
-	gpio_direction_output()
-	gpio_request()
+                gpio_direction_input()
+                gpio_direction_output()
+                gpio_request()
 
-## 	gpio_request_one()
-##	gpio_request_array()
-## 	gpio_free_array()
+        ## 	gpio_request_one()
+        ##	gpio_request_array()
+        ## 	gpio_free_array()
 
-	gpio_free()
-	gpio_set_debounce()
+                gpio_free()
+                gpio_set_debounce()
 
 
 
 Claiming and Releasing GPIOs
 ----------------------------
-To help catch system configuration errors, two calls are defined.
+To help catch system configuration errors, two calls are defined::
 
 	/* request GPIO, returning 0 or negative errno.
 	 * non-null labels may be useful for diagnostics.
@@ -296,7 +298,7 @@ Also note that it's your responsibility to have stopped using a GPIO
 before you free it.
 
 Considering in most cases GPIOs are actually configured right after they
-are claimed, three additional calls are defined:
+are claimed, three additional calls are defined::
 
 	/* request a single GPIO, with initial configuration specified by
 	 * 'flags', identical to gpio_request() wrt other arguments and
@@ -347,7 +349,7 @@ to make the pin LOW. The pin is make to HIGH by driving value 1 in output mode.
 In the future, these flags can be extended to support more properties.
 
 Further more, to ease the claim/release of multiple GPIOs, 'struct gpio' is
-introduced to encapsulate all three fields as:
+introduced to encapsulate all three fields as::
 
 	struct gpio {
 		unsigned	gpio;
@@ -355,7 +357,7 @@ introduced to encapsulate all three fields as:
 		const char	*label;
 	};
 
-A typical example of usage:
+A typical example of usage::
 
 	static struct gpio leds_gpios[] = {
 		{ 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* default to ON */
@@ -380,7 +382,7 @@ GPIOs mapped to IRQs
 --------------------
 GPIO numbers are unsigned integers; so are IRQ numbers.  These make up
 two logically distinct namespaces (GPIO 0 need not use IRQ 0).  You can
-map between them using calls like:
+map between them using calls like::
 
 	/* map GPIO numbers to IRQ numbers */
 	int gpio_to_irq(unsigned gpio);
@@ -446,12 +448,12 @@ A GPIO controller on a SOC might be tightly coupled with the pinctrl
 subsystem, in the sense that the pins can be used by other functions
 together with an optional gpio feature. We have already covered the
 case where e.g. a GPIO controller need to reserve a pin or set the
-direction of a pin by calling any of:
+direction of a pin by calling any of::
 
-pinctrl_gpio_request()
-pinctrl_gpio_free()
-pinctrl_gpio_direction_input()
-pinctrl_gpio_direction_output()
+  pinctrl_gpio_request()
+  pinctrl_gpio_free()
+  pinctrl_gpio_direction_input()
+  pinctrl_gpio_direction_output()
 
 But how does the pin control subsystem cross-correlate the GPIO
 numbers (which are a global business) to a certain pin on a certain
@@ -565,7 +567,7 @@ If neither of these options are selected, the platform does not support
 GPIOs through GPIO-lib and the code cannot be enabled by the user.
 
 Trivial implementations of those functions can directly use framework
-code, which always dispatches through the gpio_chip:
+code, which always dispatches through the gpio_chip::
 
   #define gpio_get_value	__gpio_get_value
   #define gpio_set_value	__gpio_set_value
@@ -731,7 +733,7 @@ the correct GPIO number to use for a given signal.
 Exporting from Kernel code
 --------------------------
 Kernel code can explicitly manage exports of GPIOs which have already been
-requested using gpio_request():
+requested using gpio_request()::
 
 	/* export the GPIO to userspace */
 	int gpio_export(unsigned gpio, bool direction_may_change);
@@ -756,3 +758,13 @@ After the GPIO has been exported, gpio_export_link() allows creating
 symlinks from elsewhere in sysfs to the GPIO sysfs node.  Drivers can
 use this to provide the interface under their own device in sysfs with
 a descriptive name.
+
+
+API Reference
+=============
+
+The functions listed in this section are deprecated. The GPIO descriptor based
+API should be used in new code.
+
+.. kernel-doc:: drivers/gpio/gpiolib-legacy.c
+   :export:
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index e9b41b1634f3..6d8352c0f354 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -44,7 +44,7 @@ available subsections can be seen below.
    uio-howto
    firmware/index
    pinctl
-   gpio
+   gpio/index
    misc_devices
    dmaengine/index
    slimbus
diff --git a/Documentation/gpio/00-INDEX b/Documentation/gpio/00-INDEX
index 179beb234f98..17e19a68058f 100644
--- a/Documentation/gpio/00-INDEX
+++ b/Documentation/gpio/00-INDEX
@@ -1,17 +1,4 @@
 00-INDEX
 	- This file
-gpio.txt
-	- Introduction to GPIOs and their kernel interfaces
-consumer.txt
-	- How to obtain and use GPIOs in a driver
-driver.txt
-	- How to write a GPIO driver
-drivers-on-gpio.txt:
-	- Drivers in other subsystems that can use GPIO to provide more
-	  complex functionality.
-board.txt
-	- How to assign GPIOs to a consumer device and a function
 sysfs.txt
 	- Information about the GPIO sysfs interface
-gpio-legacy.txt
-	- Historical documentation of the deprecated GPIO integer interface
diff --git a/Documentation/gpio/sysfs.txt b/Documentation/gpio/sysfs.txt
index 6cdeab8650cd..58eeab81f349 100644
--- a/Documentation/gpio/sysfs.txt
+++ b/Documentation/gpio/sysfs.txt
@@ -32,9 +32,8 @@ standard kernels won't know about. And for some tasks, simple userspace
 GPIO drivers could be all that the system really needs.
 
 DO NOT ABUSE SYSFS TO CONTROL HARDWARE THAT HAS PROPER KERNEL DRIVERS.
-PLEASE READ THE DOCUMENT NAMED "drivers-on-gpio.txt" IN THIS DOCUMENTATION
-DIRECTORY TO AVOID REINVENTING KERNEL WHEELS IN USERSPACE. I MEAN IT.
-REALLY.
+PLEASE READ THE DOCUMENT AT Documentation/driver-api/gpio/drivers-on-gpio.rst
+TO AVOID REINVENTING KERNEL WHEELS IN USERSPACE. I MEAN IT. REALLY.
 
 Paths in Sysfs
 --------------