[PATCH 01/13] Documentation: dt/bindings: Document pinctrl-ingenic

[Paul Cercueil]

From: Paul Burton <paul.burton@xxxxxxxxxx>

This commit adds documentation for the devicetree bidings of the
pinctrl-ingenic driver, which handles pin configuration, pin muxing
and GPIOs of the Ingenic SoCs currently supported by the Linux kernel.

Signed-off-by: Paul Cercueil <paul@xxxxxxxxxxxxxxx>
---
 .../bindings/pinctrl/ingenic,pinctrl.txt           | 173 +++++++++++++++++++++
 1 file changed, 173 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt

diff --git a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt
new file mode 100644
index 000000000000..e59f7e7b6a49
--- /dev/null
+++ b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt
@@ -0,0 +1,173 @@
+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.
+
+
+##### Pin controller node #####
+
+Required properties:
+- compatible: One of:
+  - "ingenic,jz4740-pinctrl"
+  - "ingenic,jz4780-pinctrl"
+- #address-cells: Should contain the integer 1.
+- #size-cells: Should contain the integer 1.
+- ranges: Should be empty.
+
+Required sub-nodes:
+  - gpio-chips (see below)
+  - functions (see below)
+
+The pin controller node must have two sub-nodes, 'gpio-chips' and 'functions'.
+
+
+##### 'gpio-chips' sub-node #####
+
+The gpio-chips node will contain sub-nodes that correspond to GPIO controllers
+(one sub-node per GPIO controller).
+
+Required properties:
+- #address-cells: Should contain the integer 1.
+- #size-cells: Should contain the integer 1.
+- ranges: Should be empty.
+
+
+##### 'functions' sub-node #####
+
+The "functions" node will contain sub-nodes that correspond to pin function
+nodes.
+
+Required properties:
+- None.
+
+
+##### GPIO controller node #####
+
+Each subnode of the 'gpio-chips' node is a GPIO controller node.
+
+Required properties:
+- gpio-controller: Identifies this node as a GPIO controller.
+- #gpio-cells: Should contain the integer 2.
+- reg: Should contain the physical address and length of the GPIO controller's
+  configuration registers.
+
+Optional properties:
+- interrupt-controller: The GPIO controllers can optionally configure the
+  GPIOs as interrupt sources. In this case, the 'interrupt-controller'
+  standalone property should be supplied.
+- #interrupt-cells: Required if 'interrupt-controller' is also specified.
+  In that case, it should contain the integer 2.
+- interrupts: Required if 'interrupt-controller' is also specified.
+  In that case, it should contain the IRQ number of this GPIO controller.
+- ingenic,pull-ups: A bit mask identifying the pins associated with this GPIO
+  port which feature a pull-up resistor. The default mask is 0x0.
+- ingenic,pull-downs: A bit mask identifying the pins associated with this GPIO
+  port which feature a pull-down resistor. The default mask is 0x0.
+  Each pin of the jz47xx SoCs may feature a single bias resistor, thus there
+  should be no bits which are set in both ingenic,pull-ups & ingenic,pull-downs.
+
+
+##### Pin function node #####
+
+Each subnode of the 'functions' node is a pin function node.
+
+These subnodes represent a functionality of the SoC which may be exposed
+through one or more groups of pins, represented as subnodes of the pin
+function node. For example a function may be uart0, which may be exposed
+through the group of pins PF0 to PF3.
+
+Required pin function node properties:
+- None.
+
+
+##### Pin group node #####
+
+Each subnode of a pin function node is a pin group node.
+
+Required pin group node properties:
+- ingenic,pins: A set of values representing the pins within this pin group and
+  their configuration. Four values should be provided for each pin:
+  - The phandle of the GPIO controller node for the GPIO port within which the
+    pin is found.
+  - The index of the pin within its GPIO port (an integer in the range 0 to 31
+    inclusive).
+  - The index of the shared function port to be programmed in the GPIO port
+    registers for this pin.
+    Tables of these may be found in the jz4740 and jz4780 programming
+    manuals within the "General-Purpose I/O Ports" -> "Overview" section.
+    The value can either be supplied directly (0 for function 0, 1 for
+    function 1, etc.) or using the macros present in
+    <dt-bindings/pinctrl/ingenic.h>.
+    The special macro JZ_PIN_MODE_GPIO can be used to specify that the pin is
+    to be used as a GPIO. This is useful, for instance, when you just want to
+    set the electrical configuration of a pin used as GPIO.
+  - The phandle of a pin configuration node specifying the electrical
+    configuration that should be applied to the pin.
+
+For example the function 'msc0' may be exposed through 2 different pin groups,
+one in GPIO port A and one in GPIO port E:
+
+  bias-configs {
+    nobias: nobias {
+      bias-disable;
+    };
+  };
+
+  functions {
+    pinfunc_msc0: msc0 {
+      pins_msc0_pa: msc0-pa {
+        ingenic,pins = <&gpa  4 1 &nobias   /* d4 */
+                        &gpa  5 1 &nobias   /* d5 */
+                        &gpa  6 1 &nobias   /* d6 */
+                        &gpa  7 1 &nobias   /* d7 */
+                        &gpa 18 1 &nobias   /* clk */
+                        &gpa 19 1 &nobias   /* cmd */
+                        &gpa 20 1 &nobias   /* d0 */
+                        &gpa 21 1 &nobias   /* d1 */
+                        &gpa 22 1 &nobias   /* d2 */
+                        &gpa 23 1 &nobias   /* d3 */
+                        &gpa 24 1 &nobias>; /* rst */
+      };
+
+      pins_msc0_pe: msc0-pe {
+        ingenic,pins = <&gpe 20 0 &nobias   /* d0 */
+                        &gpe 21 0 &nobias   /* d1 */
+                        &gpe 22 0 &nobias   /* d2 */
+                        &gpe 23 0 &nobias   /* d3 */
+                        &gpe 28 0 &nobias   /* clk */
+                        &gpe 29 0 &nobias>; /* cmd */
+      };
+    };
+  };
+
+
+##### Pin configuration node #####
+
+The pin configuration nodes are referenced by phandle, and can be placed
+anywhere in the device tree (including in the pin controller node, or in a
+sub-node that is not 'gpio-chips' or 'functions').
+
+Pin configuration nodes use generic pinconf properties to specify an electrical
+configuration of a pin. The only configurable property for a pin of the jz47xx
+SoCs is whether to enable its bias resistor. Thus the only supported pinconf
+properties are:
+
+- bias-disable
+- bias-pull-up
+- bias-pull-down
+
+No arguments are supported for any of these properties.
+
+For more information about generic pinconfig properties, see
+Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
-- 
2.11.0