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

Pull pin control updates from Linus Walleij:
 "This is the big bulk of pin control changes for the v4.13 series:

  Core:
   - The documentation is moved over to RST.
   - We now have agreed bindings for enabling input and output buffers
     without actually enabling input and/or output on a pin. We are
     chiseling out some details of pin control electronics.

  New drivers:
   - ZTE ZX
   - Renesas RZA1
   - MIPS Ingenic JZ47xx: also switch over existing drivers in the tree
     to use this pin controller and consolidate earlier spread out code.
   - Microschip MCP23S08: this driver is migrated from the GPIO
     subsystem and totally rewritten to use proper pin control. All
     users are switched over.

  New subdrivers:
   - Renesas R8A7743 and R8A7745.
   - Allwinner Sunxi A83T R_PIO.
   - Marvell MVEBU Armada CP110 and AP806.
   - Intel Cannon Lake PCH.
   - Qualcomm IPQ8074.

  Notable improvements:
   - IRQ support on the Marvell MVEBU Armada 37xx.
   - Meson driver supports HDMI CEC, AO, I2S, SPDIF and PWM.
   - Rockchip driver now supports iomux-route switching for RK3228,
     RK3328 and RK3399.
   - Rockchip A10 and A20 are merged into a single driver.
   - STM32 has improved GPIO support.
   - Samsung Exynos drivers are split per ARMv7 and ARMv8.
   - Marvell MVEBU is converted to use regmap for register access.

  Maintenance:
   - Several Renesas SH-PFC refactorings and updates.
   - Serious code size cut for Mediatek MT7623.
   - Misc janitorial and MAINTAINERS fixes"

* tag 'pinctrl-v4.13-1' of git://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-pinctrl: (137 commits)
  pinctrl: samsung: Remove bogus irq_[un]mask from resource management
  pinctrl: rza1: make structures rza1_gpiochip_template and rza1_pinmux_ops static
  pinctrl: rza1: Remove unneeded wrong check for wrong variable
  pinctrl: qcom: Add ipq8074 pinctrl driver
  pinctrl: freescale: imx7d: make of_device_ids const.
  pinctrl: DT: extend the pinmux property to support integers array
  pinctrl: generic: Add output-enable property
  pinctrl: armada-37xx: Fix number of pin in sdio_sb
  pinctrl: armada-37xx: Fix uart2 group selection register mask
  pinctrl: bcm2835: Avoid warning from __irq_do_set_handler
  pinctrl: sh-pfc: r8a7795: Add PWM support
  MAINTAINERS: Add Qualcomm pinctrl drivers section
  arm: dts: dt-bindings: Add Renesas RZ/A1 pinctrl header
  dt-bindings: pinctrl: Add RZ/A1 bindings doc
  pinctrl: Renesas RZ/A1 pin and gpio controller
  pinctrl: sh-pfc: r8a7792: Add SCIF1 and SCIF2 pin groups
  pinctrl.txt: move it to the driver-api book
  pinctrl: ingenic: checking for NULL instead of IS_ERR()
  pinctrl: uniphier: fix WARN_ON() of pingroups dump on LD20
  pinctrl: uniphier: fix WARN_ON() of pingroups dump on LD11
  ...

10 files changed, 1156 insertions, 563 deletions

diff --git a/Documentation/devicetree/bindings/gpio/ingenic,gpio.txt b/Documentation/devicetree/bindings/gpio/ingenic,gpio.txt
new file mode 100644
index 000000000000..7988aeb725f4
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/ingenic,gpio.txt
@@ -0,0 +1,46 @@
+Ingenic jz47xx GPIO controller
+
+That the Ingenic GPIO driver node must be a sub-node of the Ingenic pinctrl
+driver node.
+
+Required properties:
+--------------------
+
+ - compatible: Must contain one of:
+    - "ingenic,jz4740-gpio"
+    - "ingenic,jz4770-gpio"
+    - "ingenic,jz4780-gpio"
+ - reg: The GPIO bank number.
+ - interrupt-controller: Marks the device node as an interrupt controller.
+ - interrupts: Interrupt specifier for the controllers interrupt.
+ - #interrupt-cells: Should be 2. Refer to
+   ../interrupt-controller/interrupts.txt for more details.
+ - 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 specifies GPIO flags, as defined in <dt-bindings/gpio/gpio.h>. Only the
+    GPIO_ACTIVE_HIGH and GPIO_ACTIVE_LOW flags are supported.
+ - gpio-ranges: Range of pins managed by the GPIO controller. Refer to
+   'gpio.txt' in this directory for more details.
+
+Example:
+--------
+
+&pinctrl {
+	#address-cells = <1>;
+	#size-cells = <0>;
+
+	gpa: gpio@0 {
+		compatible = "ingenic,jz4740-gpio";
+		reg = <0>;
+
+		gpio-controller;
+		gpio-ranges = <&pinctrl 0 0 32>;
+		#gpio-cells = <2>;
+
+		interrupt-controller;
+		#interrupt-cells = <2>;
+
+		interrupt-parent = <&intc>;
+		interrupts = <28>;
+	};
+};
diff --git a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt
index b53224473672..6f2ec9af0de2 100644
--- a/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt
+++ b/Documentation/devicetree/bindings/pinctrl/allwinner,sunxi-pinctrl.txt
@@ -20,8 +20,10 @@ Required properties:
   "allwinner,sun9i-a80-pinctrl"
   "allwinner,sun9i-a80-r-pinctrl"
   "allwinner,sun8i-a83t-pinctrl"
+  "allwinner,sun8i-a83t-r-pinctrl"
   "allwinner,sun8i-h3-pinctrl"
   "allwinner,sun8i-h3-r-pinctrl"
+  "allwinner,sun8i-r40-pinctrl"
   "allwinner,sun50i-a64-pinctrl"
   "allwinner,sun50i-a64-r-pinctrl"
   "allwinner,sun50i-h5-pinctrl"
diff --git a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt
new file mode 100644
index 000000000000..ca313a7aeaff
--- /dev/null
+++ b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt
@@ -0,0 +1,41 @@
+Ingenic jz47xx pin controller
+
+Please refer to pinctrl-bindings.txt in this directory for details of the
+common pinctrl bindings used by client devices, including the meaning of the
+phrase "pin configuration node".
+
+For the jz47xx SoCs, pin control is tightly bound with GPIO ports. All pins may
+be used as GPIOs, multiplexed device functions are configured within the
+GPIO port configuration registers and it is typical to refer to pins using the
+naming scheme "PxN" where x is a character identifying the GPIO port with
+which the pin is associated and N is an integer from 0 to 31 identifying the
+pin within that GPIO port. For example PA0 is the first pin in GPIO port A, and
+PB31 is the last pin in GPIO port B. The jz4740 contains 4 GPIO ports, PA to
+PD, for a total of 128 pins. The jz4780 contains 6 GPIO ports, PA to PF, for a
+total of 192 pins.
+
+
+Required properties:
+--------------------
+
+ - compatible: One of:
+    - "ingenic,jz4740-pinctrl"
+    - "ingenic,jz4770-pinctrl"
+    - "ingenic,jz4780-pinctrl"
+ - reg: Address range of the pinctrl registers.
+
+
+GPIO sub-nodes
+--------------
+
+The pinctrl node can have optional sub-nodes for the Ingenic GPIO driver;
+please refer to ../gpio/ingenic,gpio.txt.
+
+
+Example:
+--------
+
+pinctrl: pin-controller@10010000 {
+	compatible = "ingenic,jz4740-pinctrl";
+	reg = <0x10010000 0x400>;
+};
diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
index f01d154090da..62d0f33fa65e 100644
--- a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
+++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
@@ -204,21 +204,22 @@ each single pin the number of required sub-nodes containing "pin" and
 maintain.
 
 For cases like this, the pin controller driver may use the pinmux helper
-property, where the pin identifier is packed with mux configuration settings
-in a single integer.
+property, where the pin identifier is provided with mux configuration settings
+in a pinmux group. A pinmux group consists of the pin identifier and mux
+settings represented as a single integer or an array of integers.
 
-The pinmux property accepts an array of integers, each of them describing
+The pinmux property accepts an array of pinmux groups, each of them describing
 a single pin multiplexing configuration.
 
 pincontroller {
 	state_0_node_a {
-		pinmux = <PIN_ID_AND_MUX>, <PIN_ID_AND_MUX>, ...;
+		pinmux = <PINMUX_GROUP>, <PINMUX_GROUP>, ...;
 	};
 };
 
 Each individual pin controller driver bindings documentation shall specify
-how those values (pin IDs and pin multiplexing configuration) are defined and
-assembled together.
+how pin IDs and pin multiplexing configuration are defined and assembled
+together in a pinmux group.
 
 == Generic pin configuration node content ==
 
@@ -251,14 +252,20 @@ drive-push-pull		- drive actively high and low
 drive-open-drain	- drive with open drain
 drive-open-source	- drive with open source
 drive-strength		- sink or source at most X mA
-input-enable		- enable input on pin (no effect on output)
-input-disable		- disable input on pin (no effect on output)
+input-enable		- enable input on pin (no effect on output, such as
+			  enabling an input buffer)
+input-disable		- disable input on pin (no effect on output, such as
+			  disabling an input buffer)
 input-schmitt-enable	- enable schmitt-trigger mode
 input-schmitt-disable	- disable schmitt-trigger mode
 input-debounce		- debounce mode with debound time X
 power-source		- select between different power supplies
 low-power-enable	- enable low power mode
 low-power-disable	- disable low power mode
+output-disable		- disable output on a pin (such as disable an output
+			  buffer)
+output-enable		- enable output on a pin without actively driving it
+			  (such as enabling an output buffer)
 output-low		- set the pin to output mode with low level
 output-high		- set the pin to output mode with high level
 slew-rate		- set the slew rate
@@ -300,7 +307,7 @@ arguments are described below.
 - pinmux takes a list of pin IDs and mux settings as required argument. The
   specific bindings for the hardware defines:
   - How pin IDs and mux settings are defined and assembled together in a single
-    integer.
+    integer or an array of integers.
 
 - bias-pull-up, -down and -pin-default take as optional argument on hardware
   supporting it the pull strength in Ohm. bias-disable will disable the pull.
diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-zx.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-zx.txt
new file mode 100644
index 000000000000..e219849b21ca
--- /dev/null
+++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-zx.txt
@@ -0,0 +1,85 @@
+* ZTE ZX Pin Controller
+
+The pin controller on ZTE ZX platforms is kinda of hybrid.  It consists of
+a main controller and an auxiliary one.  For example, on ZX296718 SoC, the
+main controller is TOP_PMM and the auxiliary one is AON_IOCFG.  Both
+controllers work together to control pin multiplexing and configuration in
+the way illustrated as below.
+
+
+           GMII_RXD3 ---+
+                        |
+             DVI1_HS ---+----------------------------- GMII_RXD3 (TOP pin)
+                        |
+             BGPIO16 ---+                               ^
+                                                        | pinconf
+                        ^                               |
+                        | pinmux                        |
+                        |                               |
+
+                   TOP_PMM (main)           AON_IOCFG (aux)
+
+                        |                       |       |
+                        |                pinmux |       |
+                        | pinmux                v       |
+                        v                               | pinconf
+                                    KEY_ROW2 ---+       v
+        PORT1_LCD_TE ---+                       |
+                        |            AGPIO10 ---+------ KEY_ROW2 (AON pin)
+          I2S0_DOUT3 ---+                       |
+                        |-----------------------+
+            PWM_OUT3 ---+
+                        |
+             VGA_VS1 ---+
+
+
+For most of pins like GMII_RXD3 in the figure, the pinmux function is
+controlled by TOP_PMM block only, and this type of pins are meant by term
+'TOP pins'.  For pins like KEY_ROW2, the pinmux is controlled by both
+TOP_PMM and AON_IOCFG blocks, as the available multiplexing functions for
+the pin spread in both controllers.  This type of pins are called 'AON pins'.
+Though pinmux implementation is quite different, pinconf is same for both
+types of pins.  Both are controlled by auxiliary controller, i.e. AON_IOCFG
+on ZX296718.
+
+Required properties:
+- compatible: should be "zte,zx296718-pmm".
+- reg: the register physical address and length.
+- zte,auxiliary-controller: phandle to the auxiliary pin controller which
+  implements pinmux for AON pins and pinconf for all pins.
+
+The following pin configuration are supported. Please refer to
+pinctrl-bindings.txt in this directory for more details of the common
+pinctrl bindings used by client devices.
+
+- bias-pull-up
+- bias-pull-down
+- drive-strength
+- input-enable
+- slew-rate
+
+Examples:
+
+iocfg: pin-controller@119000 {
+	compatible = "zte,zx296718-iocfg";
+	reg = <0x119000 0x1000>;
+};
+
+pmm: pin-controller@1462000 {
+	compatible = "zte,zx296718-pmm";
+	reg = <0x1462000 0x1000>;
+	zte,auxiliary-controller = <&iocfg>;
+};
+
+&pmm {
+	vga_pins: vga {
+		pins = "KEY_COL1", "KEY_COL2", "KEY_ROW1", "KEY_ROW2";
+		function = "VGA";
+	};
+};
+
+&vga {
+	pinctrl-names = "default";
+	pinctrl-0 = <&vga_pins>;
+	status = "okay";
+};
diff --git a/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.txt
new file mode 100644
index 000000000000..407b9443629d
--- /dev/null
+++ b/Documentation/devicetree/bindings/pinctrl/qcom,ipq8074-pinctrl.txt
@@ -0,0 +1,172 @@
+Qualcomm Technologies, Inc. IPQ8074 TLMM block
+
+This binding describes the Top Level Mode Multiplexer block found in the
+IPQ8074 platform.
+
+- compatible:
+	Usage: required
+	Value type: <string>
+	Definition: must be "qcom,ipq8074-pinctrl"
+
+- reg:
+	Usage: required
+	Value type: <prop-encoded-array>
+	Definition: the base address and size of the TLMM register space.
+
+- interrupts:
+	Usage: required
+	Value type: <prop-encoded-array>
+	Definition: should specify the TLMM summary IRQ.
+
+- interrupt-controller:
+	Usage: required
+	Value type: <none>
+	Definition: identifies this node as an interrupt controller
+
+- #interrupt-cells:
+	Usage: required
+	Value type: <u32>
+	Definition: must be 2. Specifying the pin number and flags, as defined
+		    in <dt-bindings/interrupt-controller/irq.h>
+
+- gpio-controller:
+	Usage: required
+	Value type: <none>
+	Definition: identifies this node as a gpio controller
+
+- #gpio-cells:
+	Usage: required
+	Value type: <u32>
+	Definition: must be 2. Specifying the pin number and flags, as defined
+		    in <dt-bindings/gpio/gpio.h>
+
+Please refer to ../gpio/gpio.txt and ../interrupt-controller/interrupts.txt for
+a general description of GPIO and interrupt bindings.
+
+Please refer to pinctrl-bindings.txt in this directory for details of the
+common pinctrl bindings used by client devices, including the meaning of the
+phrase "pin configuration node".
+
+The pin configuration nodes act as a container for an arbitrary number of
+subnodes. Each of these subnodes represents some desired configuration for a
+pin, a group, or a list of pins or groups. This configuration can include the
+mux function to select on those pin(s)/group(s), and various pin configuration
+parameters, such as pull-up, drive strength, etc.
+
+
+PIN CONFIGURATION NODES:
+
+The name of each subnode is not important; all subnodes should be enumerated
+and processed purely based on their content.
+
+Each subnode only affects those parameters that are explicitly listed. In
+other words, a subnode that lists a mux function but no pin configuration
+parameters implies no information about any pin configuration parameters.
+Similarly, a pin subnode that describes a pullup parameter implies no
+information about e.g. the mux function.
+
+
+The following generic properties as defined in pinctrl-bindings.txt are valid
+to specify in a pin configuration subnode:
+
+- pins:
+	Usage: required
+	Value type: <string-array>
+	Definition: List of gpio pins affected by the properties specified in
+		    this subnode.  Valid pins are:
+		    gpio0-gpio69
+
+- function:
+	Usage: required
+	Value type: <string>
+	Definition: Specify the alternative function to be configured for the
+		    specified pins. Functions are only valid for gpio pins.
+		    Valid values are:
+		    atest_char, atest_char0, atest_char1, atest_char2,
+		    atest_char3, audio_rxbclk, audio_rxd, audio_rxfsync,
+		    audio_rxmclk, audio_txbclk, audio_txd, audio_txfsync,
+		    audio_txmclk, blsp0_i2c, blsp0_spi, blsp0_uart, blsp1_i2c,
+		    blsp1_spi, blsp1_uart, blsp2_i2c, blsp2_spi, blsp2_uart,
+		    blsp3_i2c, blsp3_spi, blsp3_spi0, blsp3_spi1, blsp3_spi2,
+		    blsp3_spi3, blsp3_uart, blsp4_i2c0, blsp4_i2c1, blsp4_spi0,
+		    blsp4_spi1, blsp4_uart0, blsp4_uart1, blsp5_i2c, blsp5_spi,
+		    blsp5_uart, burn0, burn1, cri_trng, cri_trng0, cri_trng1,
+		    cxc0, cxc1, dbg_out, gcc_plltest, gcc_tlmm, gpio, ldo_en,
+		    ldo_update, led0, led1, led2, mac0_sa0, mac0_sa1, mac1_sa0,
+		    mac1_sa1, mac1_sa2, mac1_sa3, mac2_sa0, mac2_sa1, mdc,
+		    mdio, pcie0_clk, pcie0_rst, pcie0_wake, pcie1_clk,
+		    pcie1_rst, pcie1_wake, pcm_drx, pcm_dtx, pcm_fsync,
+		    pcm_pclk, pcm_zsi0, pcm_zsi1, prng_rosc, pta1_0, pta1_1,
+		    pta1_2, pta2_0, pta2_1, pta2_2, pwm0, pwm1, pwm2, pwm3,
+		    qdss_cti_trig_in_a0, qdss_cti_trig_in_a1,
+		    qdss_cti_trig_in_b0, qdss_cti_trig_in_b1,
+		    qdss_cti_trig_out_a0, qdss_cti_trig_out_a1,
+		    qdss_cti_trig_out_b0, qdss_cti_trig_out_b1,
+		    qdss_traceclk_a, qdss_traceclk_b, qdss_tracectl_a,
+		    qdss_tracectl_b, qdss_tracedata_a, qdss_tracedata_b,
+		    qpic, rx0, rx1, rx2, sd_card, sd_write, tsens_max, wci2a,
+		    wci2b, wci2c, wci2d
+
+- bias-disable:
+	Usage: optional
+	Value type: <none>
+	Definition: The specified pins should be configued as no pull.
+
+- bias-pull-down:
+	Usage: optional
+	Value type: <none>
+	Definition: The specified pins should be configued as pull down.
+
+- bias-pull-up:
+	Usage: optional
+	Value type: <none>
+	Definition: The specified pins should be configued as pull up.
+
+- output-high:
+	Usage: optional
+	Value type: <none>
+	Definition: The specified pins are configured in output mode, driven
+		    high.
+
+- output-low:
+	Usage: optional
+	Value type: <none>
+	Definition: The specified pins are configured in output mode, driven
+		    low.
+
+- drive-strength:
+	Usage: optional
+	Value type: <u32>
+	Definition: Selects the drive strength for the specified pins, in mA.
+		    Valid values are: 2, 4, 6, 8, 10, 12, 14 and 16
+
+Example:
+
+	tlmm: pinctrl@1000000 {
+		compatible = "qcom,ipq8074-pinctrl";
+		reg = <0x1000000 0x300000>;
+		interrupts = <GIC_SPI 208 IRQ_TYPE_LEVEL_HIGH>;
+		gpio-controller;
+		#gpio-cells = <2>;
+		interrupt-controller;
+		#interrupt-cells = <2>;
+
+		uart2: uart2-default {
+			mux {
+				pins = "gpio23", "gpio24";
+				function = "blsp4_uart1";
+			};
+
+			rx {
+				pins = "gpio23";
+				drive-strength = <4>;
+				bias-disable;
+			};
+
+			tx {
+				pins = "gpio24";
+				drive-strength = <2>;
+				bias-pull-up;
+			};
+		};
+	};
diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt
index 13df9498311a..645082f03259 100644
--- a/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt
+++ b/Documentation/devicetree/bindings/pinctrl/renesas,pfc-pinctrl.txt
@@ -13,6 +13,8 @@ Required Properties:
     - "renesas,pfc-emev2": for EMEV2 (EMMA Mobile EV2) compatible pin-controller.
     - "renesas,pfc-r8a73a4": for R8A73A4 (R-Mobile APE6) compatible pin-controller.
     - "renesas,pfc-r8a7740": for R8A7740 (R-Mobile A1) compatible pin-controller.
+    - "renesas,pfc-r8a7743": for R8A7743 (RZ/G1M) compatible pin-controller.
+    - "renesas,pfc-r8a7745": for R8A7745 (RZ/G1E) compatible pin-controller.
     - "renesas,pfc-r8a7778": for R8A7778 (R-Mobile M1) compatible pin-controller.
     - "renesas,pfc-r8a7779": for R8A7779 (R-Car H1) compatible pin-controller.
     - "renesas,pfc-r8a7790": for R8A7790 (R-Car H2) compatible pin-controller.
diff --git a/Documentation/devicetree/bindings/pinctrl/renesas,rza1-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/renesas,rza1-pinctrl.txt
new file mode 100644
index 000000000000..43e21474528a
--- /dev/null
+++ b/Documentation/devicetree/bindings/pinctrl/renesas,rza1-pinctrl.txt
@@ -0,0 +1,221 @@
+Renesas RZ/A1 combined Pin and GPIO controller
+
+The Renesas SoCs of the RZ/A1 family feature a combined Pin and GPIO controller,
+named "Ports" in the hardware reference manual.
+Pin multiplexing and GPIO configuration is performed on a per-pin basis
+writing configuration values to per-port register sets.
+Each "port" features up to 16 pins, each of them configurable for GPIO
+function (port mode) or in alternate function mode.
+Up to 8 different alternate function modes exist for each single pin.
+
+Pin controller node
+-------------------
+
+Required properties:
+  - compatible
+    this shall be "renesas,r7s72100-ports".
+
+  - reg
+    address base and length of the memory area where the pin controller
+    hardware is mapped to.
+
+Example:
+Pin controller node for RZ/A1H SoC (r7s72100)
+
+pinctrl: pin-controller@fcfe3000 {
+	compatible = "renesas,r7s72100-ports";
+
+	reg = <0xfcfe3000 0x4230>;
+};
+
+Sub-nodes
+---------
+
+The child nodes of the pin controller node describe a pin multiplexing
+function or a GPIO controller alternatively.
+
+- Pin multiplexing sub-nodes:
+  A pin multiplexing sub-node describes how to configure a set of
+  (or a single) pin in some desired alternate function mode.
+  A single sub-node may define several pin configurations.
+  A few alternate function require special pin configuration flags to be
+  supplied along with the alternate function configuration number.
+  The hardware reference manual specifies when a pin function requires
+  "software IO driven" mode to be specified. To do so use the generic
+  properties from the <include/linux/pinctrl/pinconf_generic.h> header file
+  to instruct the pin controller to perform the desired pin configuration
+  operation.
+  Please refer to pinctrl-bindings.txt to get to know more on generic
+  pin properties usage.
+
+  The allowed generic formats for a pin multiplexing sub-node are the
+  following ones:
+
+  node-1 {
+      pinmux = <PIN_ID_AND_MUX>, <PIN_ID_AND_MUX>, ... ;
+      GENERIC_PINCONFIG;
+  };
+
+  node-2 {
+      sub-node-1 {
+          pinmux = <PIN_ID_AND_MUX>, <PIN_ID_AND_MUX>, ... ;
+          GENERIC_PINCONFIG;
+      };
+
+      sub-node-2 {
+          pinmux = <PIN_ID_AND_MUX>, <PIN_ID_AND_MUX>, ... ;
+          GENERIC_PINCONFIG;
+      };
+
+      ...
+
+      sub-node-n {
+          pinmux = <PIN_ID_AND_MUX>, <PIN_ID_AND_MUX>, ... ;
+          GENERIC_PINCONFIG;
+      };
+  };
+
+  Use the second format when pins part of the same logical group need to have
+  different generic pin configuration flags applied.
+
+  Client sub-nodes shall refer to pin multiplexing sub-nodes using the phandle
+  of the most external one.
+
+  Eg.
+
+  client-1 {
+      ...
+      pinctrl-0 = <&node-1>;
+      ...
+  };
+
+  client-2 {
+      ...
+      pinctrl-0 = <&node-2>;
+      ...
+  };
+
+  Required properties:
+    - pinmux:
+      integer array representing pin number and pin multiplexing configuration.
+      When a pin has to be configured in alternate function mode, use this
+      property to identify the pin by its global index, and provide its
+      alternate function configuration number along with it.
+      When multiple pins are required to be configured as part of the same
+      alternate function they shall be specified as members of the same
+      argument list of a single "pinmux" property.
+      Helper macros to ease assembling the pin index from its position
+      (port where it sits on and pin number) and alternate function identifier
+      are provided by the pin controller header file at:
+      <include/dt-bindings/pinctrl/r7s72100-pinctrl.h>
+      Integers values in "pinmux" argument list are assembled as:
+      ((PORT * 16 + PIN) | MUX_FUNC << 16)
+
+  Optional generic properties:
+    - input-enable:
+      enable input bufer for pins requiring software driven IO input
+      operations.
+    - output-high:
+      enable output buffer for pins requiring software driven IO output
+      operations. output-low can be used alternatively, as line value is
+      ignored by the driver.
+
+  The hardware reference manual specifies when a pin has to be configured to
+  work in bi-directional mode and when the IO direction has to be specified
+  by software. Bi-directional pins are managed by the pin controller driver
+  internally, while software driven IO direction has to be explicitly
+  selected when multiple options are available.
+
+  Example:
+  A serial communication interface with a TX output pin and an RX input pin.
+
+  &pinctrl {
+	scif2_pins: serial2 {
+		pinmux = <RZA1_PINMUX(3, 0, 6)>, <RZA1_PINMUX(3, 2, 4)>;
+	};
+  };
+
+  Pin #0 on port #3 is configured as alternate function #6.
+  Pin #2 on port #3 is configured as alternate function #4.
+
+  Example 2:
+  I2c master: both SDA and SCL pins need bi-directional operations
+
+  &pinctrl {
+	i2c2_pins: i2c2 {
+		pinmux = <RZA1_PINMUX(1, 4, 1)>, <RZA1_PINMUX(1, 5, 1)>;
+	};
+  };
+
+  Pin #4 on port #1 is configured as alternate function #1.
+  Pin #5 on port #1 is configured as alternate function #1.
+  Both need to work in bi-directional mode, the driver manages this internally.
+
+  Example 3:
+  Multi-function timer input and output compare pins.
+  Configure TIOC0A as software driven input and TIOC0B as software driven
+  output.
+
+  &pinctrl {
+	tioc0_pins: tioc0 {
+		tioc0_input_pins {
+			pinumx = <RZA1_PINMUX(4, 0, 2)>;
+			input-enable;
+		};
+
+		tioc0_output_pins {
+			pinmux = <RZA1_PINMUX(4, 1, 1)>;
+			output-enable;
+		};
+	};
+  };
+
+  &tioc0 {
+	...
+	pinctrl-0 = <&tioc0_pins>;
+	...
+  };
+
+  Pin #0 on port #4 is configured as alternate function #2 with IO direction
+  specified by software as input.
+  Pin #1 on port #4 is configured as alternate function #1 with IO direction
+  specified by software as output.
+
+- GPIO controller sub-nodes:
+  Each port of the r7s72100 pin controller hardware is itself a GPIO controller.
+  Different SoCs have different numbers of available pins per port, but
+  generally speaking, each of them can be configured in GPIO ("port") mode
+  on this hardware.
+  Describe GPIO controllers using sub-nodes with the following properties.
+
+  Required properties:
+    - gpio-controller
+      empty property as defined by the GPIO bindings documentation.
+    - #gpio-cells
+      number of cells required to identify and configure a GPIO.
+      Shall be 2.
+    - gpio-ranges
+      Describes a GPIO controller specifying its specific pin base, the pin
+      base in the global pin numbering space, and the number of controlled
+      pins, as defined by the GPIO bindings documentation. Refer to
+      Documentation/devicetree/bindings/gpio/gpio.txt file for a more detailed
+      description.
+
+  Example:
+  A GPIO controller node, controlling 16 pins indexed from 0.
+  The GPIO controller base in the global pin indexing space is pin 48, thus
+  pins [0 - 15] on this controller map to pins [48 - 63] in the global pin
+  indexing space.
+
+  port3: gpio-3 {
+	gpio-controller;
+	#gpio-cells = <2>;
+	gpio-ranges = <&pinctrl 0 48 16>;
+  };
+
+  A device node willing to use pins controlled by this GPIO controller, shall
+  refer to it as follows:
+
+  led1 {
+	gpios = <&port3 10 GPIO_ACTIVE_LOW>;
+  };
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 3cf1acebc4ee..7c94ab50afed 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -43,6 +43,7 @@ available subsections can be seen below.
    80211/index
    uio-howto
    firmware/index
+   pinctl
    misc_devices
 
 .. only::  subproject and html
diff --git a/Documentation/pinctrl.txt b/Documentation/driver-api/pinctl.rst
index f2af35f6d6b2..48f15b4f9d3e 100644
--- a/Documentation/pinctrl.txt
+++ b/Documentation/driver-api/pinctl.rst
@@ -1,4 +1,7 @@
+===============================
 PINCTRL (PIN CONTROL) subsystem
+===============================
+
 This document outlines the pin control subsystem in Linux
 
 This subsystem deals with:
@@ -33,7 +36,7 @@ When a PIN CONTROLLER is instantiated, it will register a descriptor to the
 pin control framework, and this descriptor contains an array of pin descriptors
 describing the pins handled by this specific pin controller.
 
-Here is an example of a PGA (Pin Grid Array) chip seen from underneath:
+Here is an example of a PGA (Pin Grid Array) chip seen from underneath::
 
         A   B   C   D   E   F   G   H
 
@@ -54,39 +57,40 @@ Here is an example of a PGA (Pin Grid Array) chip seen from underneath:
    1    o   o   o   o   o   o   o   o
 
 To register a pin controller and name all the pins on this package we can do
-this in our driver:
-
-#include <linux/pinctrl/pinctrl.h>
-
-const struct pinctrl_pin_desc foo_pins[] = {
-      PINCTRL_PIN(0, "A8"),
-      PINCTRL_PIN(1, "B8"),
-      PINCTRL_PIN(2, "C8"),
-      ...
-      PINCTRL_PIN(61, "F1"),
-      PINCTRL_PIN(62, "G1"),
-      PINCTRL_PIN(63, "H1"),
-};
+this in our driver::
 
-static struct pinctrl_desc foo_desc = {
-	.name = "foo",
-	.pins = foo_pins,
-	.npins = ARRAY_SIZE(foo_pins),
-	.owner = THIS_MODULE,
-};
+	#include <linux/pinctrl/pinctrl.h>
 
-int __init foo_probe(void)
-{
-	int error;
+	const struct pinctrl_pin_desc foo_pins[] = {
+		PINCTRL_PIN(0, "A8"),
+		PINCTRL_PIN(1, "B8"),
+		PINCTRL_PIN(2, "C8"),
+		...
+		PINCTRL_PIN(61, "F1"),
+		PINCTRL_PIN(62, "G1"),
+		PINCTRL_PIN(63, "H1"),
+	};
+
+	static struct pinctrl_desc foo_desc = {
+		.name = "foo",
+		.pins = foo_pins,
+		.npins = ARRAY_SIZE(foo_pins),
+		.owner = THIS_MODULE,
+	};
+
+	int __init foo_probe(void)
+	{
+		int error;
 
-	struct pinctrl_dev *pctl;
+		struct pinctrl_dev *pctl;
 
-	error = pinctrl_register_and_init(&foo_desc, <PARENT>, NULL, &pctl);
-	if (error)
-		return error;
+		error = pinctrl_register_and_init(&foo_desc, <PARENT>,
+						  NULL, &pctl);
+		if (error)
+			return error;
 
-	return pinctrl_enable(pctl);
-}
+		return pinctrl_enable(pctl);
+	}
 
 To enable the pinctrl subsystem and the subgroups for PINMUX and PINCONF and
 selected drivers, you need to select them from your machine's Kconfig entry,
@@ -105,7 +109,7 @@ the pin controller.
 
 For a padring with 467 pads, as opposed to actual pins, I used an enumeration
 like this, walking around the edge of the chip, which seems to be industry
-standard too (all these pads had names, too):
+standard too (all these pads had names, too)::
 
 
      0 ..... 104
@@ -128,64 +132,64 @@ on { 0, 8, 16, 24 }, and a group of pins dealing with an I2C interface on pins
 on { 24, 25 }.
 
 These two groups are presented to the pin control subsystem by implementing
-some generic pinctrl_ops like this:
-
-#include <linux/pinctrl/pinctrl.h>
-
-struct foo_group {
-	const char *name;
-	const unsigned int *pins;
-	const unsigned num_pins;
-};
-
-static const unsigned int spi0_pins[] = { 0, 8, 16, 24 };
-static const unsigned int i2c0_pins[] = { 24, 25 };
-
-static const struct foo_group foo_groups[] = {
-	{
-		.name = "spi0_grp",
-		.pins = spi0_pins,
-		.num_pins = ARRAY_SIZE(spi0_pins),
-	},
+some generic pinctrl_ops like this::
+
+	#include <linux/pinctrl/pinctrl.h>
+
+	struct foo_group {
+		const char *name;
+		const unsigned int *pins;
+		const unsigned num_pins;
+	};
+
+	static const unsigned int spi0_pins[] = { 0, 8, 16, 24 };
+	static const unsigned int i2c0_pins[] = { 24, 25 };
+
+	static const struct foo_group foo_groups[] = {
+		{
+			.name = "spi0_grp",
+			.pins = spi0_pins,
+			.num_pins = ARRAY_SIZE(spi0_pins),
+		},
+		{
+			.name = "i2c0_grp",
+			.pins = i2c0_pins,
+			.num_pins = ARRAY_SIZE(i2c0_pins),
+		},
+	};
+
+
+	static int foo_get_groups_count(struct pinctrl_dev *pctldev)
 	{
-		.name = "i2c0_grp",
-		.pins = i2c0_pins,
-		.num_pins = ARRAY_SIZE(i2c0_pins),
-	},
-};
-
-
-static int foo_get_groups_count(struct pinctrl_dev *pctldev)
-{
-	return ARRAY_SIZE(foo_groups);
-}
+		return ARRAY_SIZE(foo_groups);
+	}
 
-static const char *foo_get_group_name(struct pinctrl_dev *pctldev,
-				       unsigned selector)
-{
-	return foo_groups[selector].name;
-}
+	static const char *foo_get_group_name(struct pinctrl_dev *pctldev,
+					unsigned selector)
+	{
+		return foo_groups[selector].name;
+	}
 
-static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector,
-			       const unsigned **pins,
-			       unsigned *num_pins)
-{
-	*pins = (unsigned *) foo_groups[selector].pins;
-	*num_pins = foo_groups[selector].num_pins;
-	return 0;
-}
+	static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector,
+				const unsigned **pins,
+				unsigned *num_pins)
+	{
+		*pins = (unsigned *) foo_groups[selector].pins;
+		*num_pins = foo_groups[selector].num_pins;
+		return 0;
+	}
 
-static struct pinctrl_ops foo_pctrl_ops = {
-	.get_groups_count = foo_get_groups_count,
-	.get_group_name = foo_get_group_name,
-	.get_group_pins = foo_get_group_pins,
-};
+	static struct pinctrl_ops foo_pctrl_ops = {
+		.get_groups_count = foo_get_groups_count,
+		.get_group_name = foo_get_group_name,
+		.get_group_pins = foo_get_group_pins,
+	};
 
 
-static struct pinctrl_desc foo_desc = {
-       ...
-       .pctlops = &foo_pctrl_ops,
-};
+	static struct pinctrl_desc foo_desc = {
+	...
+	.pctlops = &foo_pctrl_ops,
+	};
 
 The pin control subsystem will call the .get_groups_count() function to
 determine the total number of legal selectors, then it will call the other functions
@@ -213,62 +217,62 @@ The format and meaning of the configuration parameter, PLATFORM_X_PULL_UP
 above, is entirely defined by the pin controller driver.
 
 The pin configuration driver implements callbacks for changing pin
-configuration in the pin controller ops like this:
+configuration in the pin controller ops like this::
 
-#include <linux/pinctrl/pinctrl.h>
-#include <linux/pinctrl/pinconf.h>
-#include "platform_x_pindefs.h"
+	#include <linux/pinctrl/pinctrl.h>
+	#include <linux/pinctrl/pinconf.h>
+	#include "platform_x_pindefs.h"
 
-static int foo_pin_config_get(struct pinctrl_dev *pctldev,
-		    unsigned offset,
-		    unsigned long *config)
-{
-	struct my_conftype conf;
+	static int foo_pin_config_get(struct pinctrl_dev *pctldev,
+			unsigned offset,
+			unsigned long *config)
+	{
+		struct my_conftype conf;
 
-	... Find setting for pin @ offset ...
+		... Find setting for pin @ offset ...
 
-	*config = (unsigned long) conf;
-}
+		*config = (unsigned long) conf;
+	}
 
-static int foo_pin_config_set(struct pinctrl_dev *pctldev,
-		    unsigned offset,
-		    unsigned long config)
-{
-	struct my_conftype *conf = (struct my_conftype *) config;
+	static int foo_pin_config_set(struct pinctrl_dev *pctldev,
+			unsigned offset,
+			unsigned long config)
+	{
+		struct my_conftype *conf = (struct my_conftype *) config;
 
-	switch (conf) {
-		case PLATFORM_X_PULL_UP:
-		...
+		switch (conf) {
+			case PLATFORM_X_PULL_UP:
+			...
+			}
 		}
 	}
-}
 
-static int foo_pin_config_group_get (struct pinctrl_dev *pctldev,
-		    unsigned selector,
-		    unsigned long *config)
-{
-	...
-}
+	static int foo_pin_config_group_get (struct pinctrl_dev *pctldev,
+			unsigned selector,
+			unsigned long *config)
+	{
+		...
+	}
 
-static int foo_pin_config_group_set (struct pinctrl_dev *pctldev,
-		    unsigned selector,
-		    unsigned long config)
-{
-	...
-}
+	static int foo_pin_config_group_set (struct pinctrl_dev *pctldev,
+			unsigned selector,
+			unsigned long config)
+	{
+		...
+	}
 
-static struct pinconf_ops foo_pconf_ops = {
-	.pin_config_get = foo_pin_config_get,
-	.pin_config_set = foo_pin_config_set,
-	.pin_config_group_get = foo_pin_config_group_get,
-	.pin_config_group_set = foo_pin_config_group_set,
-};
+	static struct pinconf_ops foo_pconf_ops = {
+		.pin_config_get = foo_pin_config_get,
+		.pin_config_set = foo_pin_config_set,
+		.pin_config_group_get = foo_pin_config_group_get,
+		.pin_config_group_set = foo_pin_config_group_set,
+	};
 
-/* Pin config operations are handled by some pin controller */
-static struct pinctrl_desc foo_desc = {
-	...
-	.confops = &foo_pconf_ops,
-};
+	/* Pin config operations are handled by some pin controller */
+	static struct pinctrl_desc foo_desc = {
+		...
+		.confops = &foo_pconf_ops,
+	};
 
 Since some controllers have special logic for handling entire groups of pins
 they can exploit the special whole-group pin control function. The
@@ -296,35 +300,35 @@ controller handles control of a certain GPIO pin. Since a single pin controller
 may be muxing several GPIO ranges (typically SoCs that have one set of pins,
 but internally several GPIO silicon blocks, each modelled as a struct
 gpio_chip) any number of GPIO ranges can be added to a pin controller instance
-like this:
-
-struct gpio_chip chip_a;
-struct gpio_chip chip_b;
-
-static struct pinctrl_gpio_range gpio_range_a = {
-	.name = "chip a",
-	.id = 0,
-	.base = 32,
-	.pin_base = 32,
-	.npins = 16,
-	.gc = &chip_a;
-};
-
-static struct pinctrl_gpio_range gpio_range_b = {
-	.name = "chip b",
-	.id = 0,
-	.base = 48,
-	.pin_base = 64,
-	.npins = 8,
-	.gc = &chip_b;
-};
-
-{
-	struct pinctrl_dev *pctl;
-	...
-	pinctrl_add_gpio_range(pctl, &gpio_range_a);
-	pinctrl_add_gpio_range(pctl, &gpio_range_b);
-}
+like this::
+
+	struct gpio_chip chip_a;
+	struct gpio_chip chip_b;
+
+	static struct pinctrl_gpio_range gpio_range_a = {
+		.name = "chip a",
+		.id = 0,
+		.base = 32,
+		.pin_base = 32,
+		.npins = 16,
+		.gc = &chip_a;
+	};
+
+	static struct pinctrl_gpio_range gpio_range_b = {
+		.name = "chip b",
+		.id = 0,
+		.base = 48,
+		.pin_base = 64,
+		.npins = 8,
+		.gc = &chip_b;
+	};
+
+	{
+		struct pinctrl_dev *pctl;
+		...
+		pinctrl_add_gpio_range(pctl, &gpio_range_a);
+		pinctrl_add_gpio_range(pctl, &gpio_range_b);
+	}
 
 So this complex system has one pin controller handling two different
 GPIO chips. "chip a" has 16 pins and "chip b" has 8 pins. The "chip a" and
@@ -348,25 +352,26 @@ chip b:
 
 The above examples assume the mapping between the GPIOs and pins is
 linear. If the mapping is sparse or haphazard, an array of arbitrary pin
-numbers can be encoded in the range like this:
+numbers can be encoded in the range like this::
 
-static const unsigned range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 };
+	static const unsigned range_pins[] = { 14, 1, 22, 17, 10, 8, 6, 2 };
 
-static struct pinctrl_gpio_range gpio_range = {
-	.name = "chip",
-	.id = 0,
-	.base = 32,
-	.pins = &range_pins,
-	.npins = ARRAY_SIZE(range_pins),
-	.gc = &chip;
-};
+	static struct pinctrl_gpio_range gpio_range = {
+		.name = "chip",
+		.id = 0,
+		.base = 32,
+		.pins = &range_pins,
+		.npins = ARRAY_SIZE(range_pins),
+		.gc = &chip;
+	};
 
 In this case the pin_base property will be ignored. If the name of a pin
 group is known, the pins and npins elements of the above structure can be
 initialised using the function pinctrl_get_group_pins(), e.g. for pin
-group "foo":
+group "foo"::
 
-pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins, &gpio_range.npins);
+	pinctrl_get_group_pins(pctl, "foo", &gpio_range.pins,
+			       &gpio_range.npins);
 
 When GPIO-specific functions in the pin control subsystem are called, these
 ranges will be used to look up the appropriate pin controller by inspecting
@@ -405,7 +410,7 @@ we usually mean a way of soldering or wiring the package into an electronic
 system, even though the framework makes it possible to also change the function
 at runtime.
 
-Here is an example of a PGA (Pin Grid Array) chip seen from underneath:
+Here is an example of a PGA (Pin Grid Array) chip seen from underneath::
 
         A   B   C   D   E   F   G   H
       +---+
@@ -519,12 +524,12 @@ Definitions:
   In the example case we can define that this particular machine shall
   use device spi0 with pinmux function fspi0 group gspi0 and i2c0 on function
   fi2c0 group gi2c0, on the primary pin controller, we get mappings
-  like these:
+  like these::
 
-  {
-    {"map-spi0", spi0, pinctrl0, fspi0, gspi0},
-    {"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0}
-  }
+	{
+		{"map-spi0", spi0, pinctrl0, fspi0, gspi0},
+		{"map-i2c0", i2c0, pinctrl0, fi2c0, gi2c0}
+	}
 
   Every map must be assigned a state name, pin controller, device and
   function. The group is not compulsory - if it is omitted the first group
@@ -578,155 +583,155 @@ some certain registers to activate a certain mux setting for a certain pin.
 
 A simple driver for the above example will work by setting bits 0, 1, 2, 3 or 4
 into some register named MUX to select a certain function with a certain
-group of pins would work something like this:
-
-#include <linux/pinctrl/pinctrl.h>
-#include <linux/pinctrl/pinmux.h>
-
-struct foo_group {
-	const char *name;
-	const unsigned int *pins;
-	const unsigned num_pins;
-};
-
-static const unsigned spi0_0_pins[] = { 0, 8, 16, 24 };
-static const unsigned spi0_1_pins[] = { 38, 46, 54, 62 };
-static const unsigned i2c0_pins[] = { 24, 25 };
-static const unsigned mmc0_1_pins[] = { 56, 57 };
-static const unsigned mmc0_2_pins[] = { 58, 59 };
-static const unsigned mmc0_3_pins[] = { 60, 61, 62, 63 };
-
-static const struct foo_group foo_groups[] = {
-	{
-		.name = "spi0_0_grp",
-		.pins = spi0_0_pins,
-		.num_pins = ARRAY_SIZE(spi0_0_pins),
-	},
+group of pins would work something like this::
+
+	#include <linux/pinctrl/pinctrl.h>
+	#include <linux/pinctrl/pinmux.h>
+
+	struct foo_group {
+		const char *name;
+		const unsigned int *pins;
+		const unsigned num_pins;
+	};
+
+	static const unsigned spi0_0_pins[] = { 0, 8, 16, 24 };
+	static const unsigned spi0_1_pins[] = { 38, 46, 54, 62 };
+	static const unsigned i2c0_pins[] = { 24, 25 };
+	static const unsigned mmc0_1_pins[] = { 56, 57 };
+	static const unsigned mmc0_2_pins[] = { 58, 59 };
+	static const unsigned mmc0_3_pins[] = { 60, 61, 62, 63 };
+
+	static const struct foo_group foo_groups[] = {
+		{
+			.name = "spi0_0_grp",
+			.pins = spi0_0_pins,
+			.num_pins = ARRAY_SIZE(spi0_0_pins),
+		},
+		{
+			.name = "spi0_1_grp",
+			.pins = spi0_1_pins,
+			.num_pins = ARRAY_SIZE(spi0_1_pins),
+		},
+		{
+			.name = "i2c0_grp",
+			.pins = i2c0_pins,
+			.num_pins = ARRAY_SIZE(i2c0_pins),
+		},
+		{
+			.name = "mmc0_1_grp",
+			.pins = mmc0_1_pins,
+			.num_pins = ARRAY_SIZE(mmc0_1_pins),
+		},
+		{
+			.name = "mmc0_2_grp",
+			.pins = mmc0_2_pins,
+			.num_pins = ARRAY_SIZE(mmc0_2_pins),
+		},
+		{
+			.name = "mmc0_3_grp",
+			.pins = mmc0_3_pins,
+			.num_pins = ARRAY_SIZE(mmc0_3_pins),
+		},
+	};
+
+
+	static int foo_get_groups_count(struct pinctrl_dev *pctldev)
 	{
-		.name = "spi0_1_grp",
-		.pins = spi0_1_pins,
-		.num_pins = ARRAY_SIZE(spi0_1_pins),
-	},
-	{
-		.name = "i2c0_grp",
-		.pins = i2c0_pins,
-		.num_pins = ARRAY_SIZE(i2c0_pins),
-	},
+		return ARRAY_SIZE(foo_groups);
+	}
+
+	static const char *foo_get_group_name(struct pinctrl_dev *pctldev,
+					unsigned selector)
 	{
-		.name = "mmc0_1_grp",
-		.pins = mmc0_1_pins,
-		.num_pins = ARRAY_SIZE(mmc0_1_pins),
-	},
+		return foo_groups[selector].name;
+	}
+
+	static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector,
+				unsigned ** const pins,
+				unsigned * const num_pins)
 	{
-		.name = "mmc0_2_grp",
-		.pins = mmc0_2_pins,
-		.num_pins = ARRAY_SIZE(mmc0_2_pins),
-	},
+		*pins = (unsigned *) foo_groups[selector].pins;
+		*num_pins = foo_groups[selector].num_pins;
+		return 0;
+	}
+
+	static struct pinctrl_ops foo_pctrl_ops = {
+		.get_groups_count = foo_get_groups_count,
+		.get_group_name = foo_get_group_name,
+		.get_group_pins = foo_get_group_pins,
+	};
+
+	struct foo_pmx_func {
+		const char *name;
+		const char * const *groups;
+		const unsigned num_groups;
+	};
+
+	static const char * const spi0_groups[] = { "spi0_0_grp", "spi0_1_grp" };
+	static const char * const i2c0_groups[] = { "i2c0_grp" };
+	static const char * const mmc0_groups[] = { "mmc0_1_grp", "mmc0_2_grp",
+						"mmc0_3_grp" };
+
+	static const struct foo_pmx_func foo_functions[] = {
+		{
+			.name = "spi0",
+			.groups = spi0_groups,
+			.num_groups = ARRAY_SIZE(spi0_groups),
+		},
+		{
+			.name = "i2c0",
+			.groups = i2c0_groups,
+			.num_groups = ARRAY_SIZE(i2c0_groups),
+		},
+		{
+			.name = "mmc0",
+			.groups = mmc0_groups,
+			.num_groups = ARRAY_SIZE(mmc0_groups),
+		},
+	};
+
+	static int foo_get_functions_count(struct pinctrl_dev *pctldev)
 	{
-		.name = "mmc0_3_grp",
-		.pins = mmc0_3_pins,
-		.num_pins = ARRAY_SIZE(mmc0_3_pins),
-	},
-};
-
-
-static int foo_get_groups_count(struct pinctrl_dev *pctldev)
-{
-	return ARRAY_SIZE(foo_groups);
-}
-
-static const char *foo_get_group_name(struct pinctrl_dev *pctldev,
-				       unsigned selector)
-{
-	return foo_groups[selector].name;
-}
-
-static int foo_get_group_pins(struct pinctrl_dev *pctldev, unsigned selector,
-			       unsigned ** const pins,
-			       unsigned * const num_pins)
-{
-	*pins = (unsigned *) foo_groups[selector].pins;
-	*num_pins = foo_groups[selector].num_pins;
-	return 0;
-}
-
-static struct pinctrl_ops foo_pctrl_ops = {
-	.get_groups_count = foo_get_groups_count,
-	.get_group_name = foo_get_group_name,
-	.get_group_pins = foo_get_group_pins,
-};
-
-struct foo_pmx_func {
-	const char *name;
-	const char * const *groups;
-	const unsigned num_groups;
-};
-
-static const char * const spi0_groups[] = { "spi0_0_grp", "spi0_1_grp" };
-static const char * const i2c0_groups[] = { "i2c0_grp" };
-static const char * const mmc0_groups[] = { "mmc0_1_grp", "mmc0_2_grp",
-					"mmc0_3_grp" };
-
-static const struct foo_pmx_func foo_functions[] = {
+		return ARRAY_SIZE(foo_functions);
+	}
+
+	static const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector)
 	{
-		.name = "spi0",
-		.groups = spi0_groups,
-		.num_groups = ARRAY_SIZE(spi0_groups),
-	},
+		return foo_functions[selector].name;
+	}
+
+	static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned selector,
+				const char * const **groups,
+				unsigned * const num_groups)
 	{
-		.name = "i2c0",
-		.groups = i2c0_groups,
-		.num_groups = ARRAY_SIZE(i2c0_groups),
-	},
+		*groups = foo_functions[selector].groups;
+		*num_groups = foo_functions[selector].num_groups;
+		return 0;
+	}
+
+	static int foo_set_mux(struct pinctrl_dev *pctldev, unsigned selector,
+			unsigned group)
 	{
-		.name = "mmc0",
-		.groups = mmc0_groups,
-		.num_groups = ARRAY_SIZE(mmc0_groups),
-	},
-};
-
-static int foo_get_functions_count(struct pinctrl_dev *pctldev)
-{
-	return ARRAY_SIZE(foo_functions);
-}
-
-static const char *foo_get_fname(struct pinctrl_dev *pctldev, unsigned selector)
-{
-	return foo_functions[selector].name;
-}
-
-static int foo_get_groups(struct pinctrl_dev *pctldev, unsigned selector,
-			  const char * const **groups,
-			  unsigned * const num_groups)
-{
-	*groups = foo_functions[selector].groups;
-	*num_groups = foo_functions[selector].num_groups;
-	return 0;
-}
-
-static int foo_set_mux(struct pinctrl_dev *pctldev, unsigned selector,
-		unsigned group)
-{
-	u8 regbit = (1 << selector + group);
-
-	writeb((readb(MUX)|regbit), MUX)
-	return 0;
-}
-
-static struct pinmux_ops foo_pmxops = {
-	.get_functions_count = foo_get_functions_count,
-	.get_function_name = foo_get_fname,
-	.get_function_groups = foo_get_groups,
-	.set_mux = foo_set_mux,
-	.strict = true,
-};
-
-/* Pinmux operations are handled by some pin controller */
-static struct pinctrl_desc foo_desc = {
-	...
-	.pctlops = &foo_pctrl_ops,
-	.pmxops = &foo_pmxops,
-};
+		u8 regbit = (1 << selector + group);
+
+		writeb((readb(MUX)|regbit), MUX)
+		return 0;
+	}
+
+	static struct pinmux_ops foo_pmxops = {
+		.get_functions_count = foo_get_functions_count,
+		.get_function_name = foo_get_fname,
+		.get_function_groups = foo_get_groups,
+		.set_mux = foo_set_mux,
+		.strict = true,
+	};
+
+	/* Pinmux operations are handled by some pin controller */
+	static struct pinctrl_desc foo_desc = {
+		...
+		.pctlops = &foo_pctrl_ops,
+		.pmxops = &foo_pmxops,
+	};
 
 In the example activating muxing 0 and 1 at the same time setting bits
 0 and 1, uses one pin in common so they would collide.
@@ -809,9 +814,9 @@ for a device.
 
 The GPIO portions of a pin and its relation to a certain pin controller
 configuration and muxing logic can be constructed in several ways. Here
-are two examples:
+are two examples::
 
-(A)
+     (A)
                        pin config
                        logic regs
                        |               +- SPI
@@ -840,7 +845,9 @@ simultaneous access to the same pin from GPIO and pin multiplexing
 consumers on hardware of this type. The pinctrl driver should set this flag
 accordingly.
 
-(B)
+::
+
+     (B)
 
                        pin config
                        logic regs
@@ -911,52 +918,55 @@ has to be handled by the <linux/gpio.h> interface. Instead view this as
 a certain pin config setting. Look in e.g. <linux/pinctrl/pinconf-generic.h>
 and you find this in the documentation:
 
-  PIN_CONFIG_OUTPUT: this will configure the pin in output, use argument
+  PIN_CONFIG_OUTPUT:
+     this will configure the pin in output, use argument
      1 to indicate high level, argument 0 to indicate low level.
 
 So it is perfectly possible to push a pin into "GPIO mode" and drive the
 line low as part of the usual pin control map. So for example your UART
-driver may look like this:
+driver may look like this::
 
-#include <linux/pinctrl/consumer.h>
+	#include <linux/pinctrl/consumer.h>
 
-struct pinctrl          *pinctrl;
-struct pinctrl_state    *pins_default;
-struct pinctrl_state    *pins_sleep;
+	struct pinctrl          *pinctrl;
+	struct pinctrl_state    *pins_default;
+	struct pinctrl_state    *pins_sleep;
 
-pins_default = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_DEFAULT);
-pins_sleep = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_SLEEP);
+	pins_default = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_DEFAULT);
+	pins_sleep = pinctrl_lookup_state(uap->pinctrl, PINCTRL_STATE_SLEEP);
 
-/* Normal mode */
-retval = pinctrl_select_state(pinctrl, pins_default);
-/* Sleep mode */
-retval = pinctrl_select_state(pinctrl, pins_sleep);
+	/* Normal mode */
+	retval = pinctrl_select_state(pinctrl, pins_default);
+	/* Sleep mode */
+	retval = pinctrl_select_state(pinctrl, pins_sleep);
 
 And your machine configuration may look like this:
 --------------------------------------------------
 
-static unsigned long uart_default_mode[] = {
-    PIN_CONF_PACKED(PIN_CONFIG_DRIVE_PUSH_PULL, 0),
-};
-
-static unsigned long uart_sleep_mode[] = {
-    PIN_CONF_PACKED(PIN_CONFIG_OUTPUT, 0),
-};
-
-static struct pinctrl_map pinmap[] __initdata = {
-    PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
-                      "u0_group", "u0"),
-    PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
-                        "UART_TX_PIN", uart_default_mode),
-    PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
-                      "u0_group", "gpio-mode"),
-    PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
-                        "UART_TX_PIN", uart_sleep_mode),
-};
-
-foo_init(void) {
-    pinctrl_register_mappings(pinmap, ARRAY_SIZE(pinmap));
-}
+::
+
+	static unsigned long uart_default_mode[] = {
+		PIN_CONF_PACKED(PIN_CONFIG_DRIVE_PUSH_PULL, 0),
+	};
+
+	static unsigned long uart_sleep_mode[] = {
+		PIN_CONF_PACKED(PIN_CONFIG_OUTPUT, 0),
+	};
+
+	static struct pinctrl_map pinmap[] __initdata = {
+		PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
+			"u0_group", "u0"),
+		PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_DEFAULT, "pinctrl-foo",
+				"UART_TX_PIN", uart_default_mode),
+		PIN_MAP_MUX_GROUP("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
+			"u0_group", "gpio-mode"),
+		PIN_MAP_CONFIGS_PIN("uart", PINCTRL_STATE_SLEEP, "pinctrl-foo",
+				"UART_TX_PIN", uart_sleep_mode),
+	};
+
+	foo_init(void) {
+		pinctrl_register_mappings(pinmap, ARRAY_SIZE(pinmap));
+	}
 
 Here the pins we want to control are in the "u0_group" and there is some
 function called "u0" that can be enabled on this group of pins, and then
@@ -985,7 +995,7 @@ API.
 
 
 Board/machine configuration
-==================================
+===========================
 
 Boards and machines define how a certain complete running system is put
 together, including how GPIOs and devices are muxed, how regulators are
@@ -994,33 +1004,33 @@ part of this.
 
 A pin controller configuration for a machine looks pretty much like a simple
 regulator configuration, so for the example array above we want to enable i2c
-and spi on the second function mapping:
-
-#include <linux/pinctrl/machine.h>
-
-static const struct pinctrl_map mapping[] __initconst = {
-	{
-		.dev_name = "foo-spi.0",
-		.name = PINCTRL_STATE_DEFAULT,
-		.type = PIN_MAP_TYPE_MUX_GROUP,
-		.ctrl_dev_name = "pinctrl-foo",
-		.data.mux.function = "spi0",
-	},
-	{
-		.dev_name = "foo-i2c.0",
-		.name = PINCTRL_STATE_DEFAULT,
-		.type = PIN_MAP_TYPE_MUX_GROUP,
-		.ctrl_dev_name = "pinctrl-foo",
-		.data.mux.function = "i2c0",
-	},
-	{
-		.dev_name = "foo-mmc.0",
-		.name = PINCTRL_STATE_DEFAULT,
-		.type = PIN_MAP_TYPE_MUX_GROUP,
-		.ctrl_dev_name = "pinctrl-foo",
-		.data.mux.function = "mmc0",
-	},
-};
+and spi on the second function mapping::
+
+	#include <linux/pinctrl/machine.h>
+
+	static const struct pinctrl_map mapping[] __initconst = {
+		{
+			.dev_name = "foo-spi.0",
+			.name = PINCTRL_STATE_DEFAULT,
+			.type = PIN_MAP_TYPE_MUX_GROUP,
+			.ctrl_dev_name = "pinctrl-foo",
+			.data.mux.function = "spi0",
+		},
+		{
+			.dev_name = "foo-i2c.0",
+			.name = PINCTRL_STATE_DEFAULT,
+			.type = PIN_MAP_TYPE_MUX_GROUP,
+			.ctrl_dev_name = "pinctrl-foo",
+			.data.mux.function = "i2c0",
+		},
+		{
+			.dev_name = "foo-mmc.0",
+			.name = PINCTRL_STATE_DEFAULT,
+			.type = PIN_MAP_TYPE_MUX_GROUP,
+			.ctrl_dev_name = "pinctrl-foo",
+			.data.mux.function = "mmc0",
+		},
+	};
 
 The dev_name here matches to the unique device name that can be used to look
 up the device struct (just like with clockdev or regulators). The function name
@@ -1029,76 +1039,81 @@ must match a function provided by the pinmux driver handling this pin range.
 As you can see we may have several pin controllers on the system and thus
 we need to specify which one of them contains the functions we wish to map.
 
-You register this pinmux mapping to the pinmux subsystem by simply:
+You register this pinmux mapping to the pinmux subsystem by simply::
 
        ret = pinctrl_register_mappings(mapping, ARRAY_SIZE(mapping));
 
 Since the above construct is pretty common there is a helper macro to make
 it even more compact which assumes you want to use pinctrl-foo and position
-0 for mapping, for example:
+0 for mapping, for example::
 
-static struct pinctrl_map mapping[] __initdata = {
-	PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT, "pinctrl-foo", NULL, "i2c0"),
-};
+	static struct pinctrl_map mapping[] __initdata = {
+		PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT,
+				  "pinctrl-foo", NULL, "i2c0"),
+	};
 
 The mapping table may also contain pin configuration entries. It's common for
 each pin/group to have a number of configuration entries that affect it, so
 the table entries for configuration reference an array of config parameters
-and values. An example using the convenience macros is shown below:
-
-static unsigned long i2c_grp_configs[] = {
-	FOO_PIN_DRIVEN,
-	FOO_PIN_PULLUP,
-};
-
-static unsigned long i2c_pin_configs[] = {
-	FOO_OPEN_COLLECTOR,
-	FOO_SLEW_RATE_SLOW,
-};
-
-static struct pinctrl_map mapping[] __initdata = {
-	PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0", "i2c0"),
-	PIN_MAP_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0", i2c_grp_configs),
-	PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0scl", i2c_pin_configs),
-	PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", "i2c0sda", i2c_pin_configs),
-};
+and values. An example using the convenience macros is shown below::
+
+	static unsigned long i2c_grp_configs[] = {
+		FOO_PIN_DRIVEN,
+		FOO_PIN_PULLUP,
+	};
+
+	static unsigned long i2c_pin_configs[] = {
+		FOO_OPEN_COLLECTOR,
+		FOO_SLEW_RATE_SLOW,
+	};
+
+	static struct pinctrl_map mapping[] __initdata = {
+		PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,
+				  "pinctrl-foo", "i2c0", "i2c0"),
+		PIN_MAP_CONFIGS_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT,
+				      "pinctrl-foo", "i2c0", i2c_grp_configs),
+		PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,
+				    "pinctrl-foo", "i2c0scl", i2c_pin_configs),
+		PIN_MAP_CONFIGS_PIN("foo-i2c.0", PINCTRL_STATE_DEFAULT,
+				    "pinctrl-foo", "i2c0sda", i2c_pin_configs),
+	};
 
 Finally, some devices expect the mapping table to contain certain specific
 named states. When running on hardware that doesn't need any pin controller
 configuration, the mapping table must still contain those named states, in
 order to explicitly indicate that the states were provided and intended to
 be empty. Table entry macro PIN_MAP_DUMMY_STATE serves the purpose of defining
-a named state without causing any pin controller to be programmed:
+a named state without causing any pin controller to be programmed::
 
-static struct pinctrl_map mapping[] __initdata = {
-	PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT),
-};
+	static struct pinctrl_map mapping[] __initdata = {
+		PIN_MAP_DUMMY_STATE("foo-i2c.0", PINCTRL_STATE_DEFAULT),
+	};
 
 
 Complex mappings
 ================
 
 As it is possible to map a function to different groups of pins an optional
-.group can be specified like this:
-
-...
-{
-	.dev_name = "foo-spi.0",
-	.name = "spi0-pos-A",
-	.type = PIN_MAP_TYPE_MUX_GROUP,
-	.ctrl_dev_name = "pinctrl-foo",
-	.function = "spi0",
-	.group = "spi0_0_grp",
-},
-{
-	.dev_name = "foo-spi.0",
-	.name = "spi0-pos-B",
-	.type = PIN_MAP_TYPE_MUX_GROUP,
-	.ctrl_dev_name = "pinctrl-foo",
-	.function = "spi0",
-	.group = "spi0_1_grp",
-},
-...
+.group can be specified like this::
+
+	...
+	{
+		.dev_name = "foo-spi.0",
+		.name = "spi0-pos-A",
+		.type = PIN_MAP_TYPE_MUX_GROUP,
+		.ctrl_dev_name = "pinctrl-foo",
+		.function = "spi0",
+		.group = "spi0_0_grp",
+	},
+	{
+		.dev_name = "foo-spi.0",
+		.name = "spi0-pos-B",
+		.type = PIN_MAP_TYPE_MUX_GROUP,
+		.ctrl_dev_name = "pinctrl-foo",
+		.function = "spi0",
+		.group = "spi0_1_grp",
+	},
+	...
 
 This example mapping is used to switch between two positions for spi0 at
 runtime, as described further below under the heading "Runtime pinmuxing".
@@ -1107,67 +1122,67 @@ Further it is possible for one named state to affect the muxing of several
 groups of pins, say for example in the mmc0 example above, where you can
 additively expand the mmc0 bus from 2 to 4 to 8 pins. If we want to use all
 three groups for a total of 2+2+4 = 8 pins (for an 8-bit MMC bus as is the
-case), we define a mapping like this:
-
-...
-{
-	.dev_name = "foo-mmc.0",
-	.name = "2bit"
-	.type = PIN_MAP_TYPE_MUX_GROUP,
-	.ctrl_dev_name = "pinctrl-foo",
-	.function = "mmc0",
-	.group = "mmc0_1_grp",
-},
-{
-	.dev_name = "foo-mmc.0",
-	.name = "4bit"
-	.type = PIN_MAP_TYPE_MUX_GROUP,
-	.ctrl_dev_name = "pinctrl-foo",
-	.function = "mmc0",
-	.group = "mmc0_1_grp",
-},
-{
-	.dev_name = "foo-mmc.0",
-	.name = "4bit"
-	.type = PIN_MAP_TYPE_MUX_GROUP,
-	.ctrl_dev_name = "pinctrl-foo",
-	.function = "mmc0",
-	.group = "mmc0_2_grp",
-},
-{
-	.dev_name = "foo-mmc.0",
-	.name = "8bit"
-	.type = PIN_MAP_TYPE_MUX_GROUP,
-	.ctrl_dev_name = "pinctrl-foo",
-	.function = "mmc0",
-	.group = "mmc0_1_grp",
-},
-{
-	.dev_name = "foo-mmc.0",
-	.name = "8bit"
-	.type = PIN_MAP_TYPE_MUX_GROUP,
-	.ctrl_dev_name = "pinctrl-foo",
-	.function = "mmc0",
-	.group = "mmc0_2_grp",
-},
-{
-	.dev_name = "foo-mmc.0",
-	.name = "8bit"
-	.type = PIN_MAP_TYPE_MUX_GROUP,
-	.ctrl_dev_name = "pinctrl-foo",
-	.function = "mmc0",
-	.group = "mmc0_3_grp",
-},
-...
+case), we define a mapping like this::
+
+	...
+	{
+		.dev_name = "foo-mmc.0",
+		.name = "2bit"
+		.type = PIN_MAP_TYPE_MUX_GROUP,
+		.ctrl_dev_name = "pinctrl-foo",
+		.function = "mmc0",
+		.group = "mmc0_1_grp",
+	},
+	{
+		.dev_name = "foo-mmc.0",
+		.name = "4bit"
+		.type = PIN_MAP_TYPE_MUX_GROUP,
+		.ctrl_dev_name = "pinctrl-foo",
+		.function = "mmc0",
+		.group = "mmc0_1_grp",
+	},
+	{
+		.dev_name = "foo-mmc.0",
+		.name = "4bit"
+		.type = PIN_MAP_TYPE_MUX_GROUP,
+		.ctrl_dev_name = "pinctrl-foo",
+		.function = "mmc0",
+		.group = "mmc0_2_grp",
+	},
+	{
+		.dev_name = "foo-mmc.0",
+		.name = "8bit"
+		.type = PIN_MAP_TYPE_MUX_GROUP,
+		.ctrl_dev_name = "pinctrl-foo",
+		.function = "mmc0",
+		.group = "mmc0_1_grp",
+	},
+	{
+		.dev_name = "foo-mmc.0",
+		.name = "8bit"
+		.type = PIN_MAP_TYPE_MUX_GROUP,
+		.ctrl_dev_name = "pinctrl-foo",
+		.function = "mmc0",
+		.group = "mmc0_2_grp",
+	},
+	{
+		.dev_name = "foo-mmc.0",
+		.name = "8bit"
+		.type = PIN_MAP_TYPE_MUX_GROUP,
+		.ctrl_dev_name = "pinctrl-foo",
+		.function = "mmc0",
+		.group = "mmc0_3_grp",
+	},
+	...
 
 The result of grabbing this mapping from the device with something like
-this (see next paragraph):
+this (see next paragraph)::
 
 	p = devm_pinctrl_get(dev);
 	s = pinctrl_lookup_state(p, "8bit");
 	ret = pinctrl_select_state(p, s);
 
-or more simply:
+or more simply::
 
 	p = devm_pinctrl_get_select(dev, "8bit");
 
@@ -1205,39 +1220,39 @@ PINCTRL_STATE_SLEEP at runtime, re-biasing or even re-muxing pins to save
 current in sleep mode.
 
 A driver may request a certain control state to be activated, usually just the
-default state like this:
+default state like this::
 
-#include <linux/pinctrl/consumer.h>
+	#include <linux/pinctrl/consumer.h>
 
-struct foo_state {
-       struct pinctrl *p;
-       struct pinctrl_state *s;
-       ...
-};
+	struct foo_state {
+	struct pinctrl *p;
+	struct pinctrl_state *s;
+	...
+	};
 
-foo_probe()
-{
-	/* Allocate a state holder named "foo" etc */
-	struct foo_state *foo = ...;
+	foo_probe()
+	{
+		/* Allocate a state holder named "foo" etc */
+		struct foo_state *foo = ...;
 
-	foo->p = devm_pinctrl_get(&device);
-	if (IS_ERR(foo->p)) {
-		/* FIXME: clean up "foo" here */
-		return PTR_ERR(foo->p);
-	}
+		foo->p = devm_pinctrl_get(&device);
+		if (IS_ERR(foo->p)) {
+			/* FIXME: clean up "foo" here */
+			return PTR_ERR(foo->p);
+		}
 
-	foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT);
-	if (IS_ERR(foo->s)) {
-		/* FIXME: clean up "foo" here */
-		return PTR_ERR(s);
-	}
+		foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT);
+		if (IS_ERR(foo->s)) {
+			/* FIXME: clean up "foo" here */
+			return PTR_ERR(s);
+		}
 
-	ret = pinctrl_select_state(foo->s);
-	if (ret < 0) {
-		/* FIXME: clean up "foo" here */
-		return ret;
+		ret = pinctrl_select_state(foo->s);
+		if (ret < 0) {
+			/* FIXME: clean up "foo" here */
+			return ret;
+		}
 	}
-}
 
 This get/lookup/select/put sequence can just as well be handled by bus drivers
 if you don't want each and every driver to handle it and you know the
@@ -1299,16 +1314,16 @@ Drivers needing both pin control and GPIOs
 Again, it is discouraged to let drivers lookup and select pin control states
 themselves, but again sometimes this is unavoidable.
 
-So say that your driver is fetching its resources like this:
+So say that your driver is fetching its resources like this::
 
-#include <linux/pinctrl/consumer.h>
-#include <linux/gpio.h>
+	#include <linux/pinctrl/consumer.h>
+	#include <linux/gpio.h>
 
-struct pinctrl *pinctrl;
-int gpio;
+	struct pinctrl *pinctrl;
+	int gpio;
 
-pinctrl = devm_pinctrl_get_select_default(&dev);
-gpio = devm_gpio_request(&dev, 14, "foo");
+	pinctrl = devm_pinctrl_get_select_default(&dev);
+	gpio = devm_gpio_request(&dev, 14, "foo");
 
 Here we first request a certain pin state and then request GPIO 14 to be
 used. If you're using the subsystems orthogonally like this, you should
@@ -1347,21 +1362,22 @@ lookup_state() and select_state() on it immediately after the pin control
 device has been registered.
 
 This occurs for mapping table entries where the client device name is equal
-to the pin controller device name, and the state name is PINCTRL_STATE_DEFAULT.
+to the pin controller device name, and the state name is PINCTRL_STATE_DEFAULT::
 
-{
-	.dev_name = "pinctrl-foo",
-	.name = PINCTRL_STATE_DEFAULT,
-	.type = PIN_MAP_TYPE_MUX_GROUP,
-	.ctrl_dev_name = "pinctrl-foo",
-	.function = "power_func",
-},
+	{
+		.dev_name = "pinctrl-foo",
+		.name = PINCTRL_STATE_DEFAULT,
+		.type = PIN_MAP_TYPE_MUX_GROUP,
+		.ctrl_dev_name = "pinctrl-foo",
+		.function = "power_func",
+	},
 
 Since it may be common to request the core to hog a few always-applicable
 mux settings on the primary pin controller, there is a convenience macro for
-this:
+this::
 
-PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */, "power_func")
+	PIN_MAP_MUX_GROUP_HOG_DEFAULT("pinctrl-foo", NULL /* group */,
+				      "power_func")
 
 This gives the exact same result as the above construction.
 
@@ -1378,45 +1394,45 @@ function, but with different named in the mapping as described under
 
 This snippet first initializes a state object for both groups (in foo_probe()),
 then muxes the function in the pins defined by group A, and finally muxes it in
-on the pins defined by group B:
+on the pins defined by group B::
 
-#include <linux/pinctrl/consumer.h>
+	#include <linux/pinctrl/consumer.h>
 
-struct pinctrl *p;
-struct pinctrl_state *s1, *s2;
+	struct pinctrl *p;
+	struct pinctrl_state *s1, *s2;
 
-foo_probe()
-{
-	/* Setup */
-	p = devm_pinctrl_get(&device);
-	if (IS_ERR(p))
-		...
+	foo_probe()
+	{
+		/* Setup */
+		p = devm_pinctrl_get(&device);
+		if (IS_ERR(p))
+			...
+
+		s1 = pinctrl_lookup_state(foo->p, "pos-A");
+		if (IS_ERR(s1))
+			...
+
+		s2 = pinctrl_lookup_state(foo->p, "pos-B");
+		if (IS_ERR(s2))
+			...
+	}
 
-	s1 = pinctrl_lookup_state(foo->p, "pos-A");
-	if (IS_ERR(s1))
+	foo_switch()
+	{
+		/* Enable on position A */
+		ret = pinctrl_select_state(s1);
+		if (ret < 0)
 		...
 
-	s2 = pinctrl_lookup_state(foo->p, "pos-B");
-	if (IS_ERR(s2))
 		...
-}
-
-foo_switch()
-{
-	/* Enable on position A */
-	ret = pinctrl_select_state(s1);
-	if (ret < 0)
-	    ...
-
-	...
 
-	/* Enable on position B */
-	ret = pinctrl_select_state(s2);
-	if (ret < 0)
-	    ...
+		/* Enable on position B */
+		ret = pinctrl_select_state(s2);
+		if (ret < 0)
+		...
 
-	...
-}
+		...
+	}
 
 The above has to be done from process context. The reservation of the pins
 will be done when the state is activated, so in effect one specific pin