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
