dt: pinctrl: Document device tree binding

The core pin controller bindings define:
* The fact that pin controllers expose pin configurations as nodes in
  device tree.
* That the bindings for those pin configuration nodes is defined by the
  individual pin controller drivers.
* A standardized set of properties for client devices to define numbered
  or named pin configuration states, each referring to some number of the
  afore-mentioned pin configuration nodes.
* That the bindings for the client devices determines the set of numbered
  or named states that must exist.

Signed-off-by: Stephen Warren <swarren@nvidia.com>
Acked-by: Shawn Guo <shawn.guo@linaro.org>
Acked-by: Tony Lindgren <tony@atomide.com>
Acked-by: Linus Walleij <linus.walleij@linaro.org>
Acked-by: Simon Glass <sjg@chromium.org>
Acked-by: Dong Aisheng <dong.aisheng@linaro.org>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
new file mode 100644 (file)
index 0000000..c95ea82
--- /dev/null
+++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt
@@ -0,0 +1,128 @@
+== Introduction ==
+
+Hardware modules that control pin multiplexing or configuration parameters
+such as pull-up/down, tri-state, drive-strength etc are designated as pin
+controllers. Each pin controller must be represented as a node in device tree,
+just like any other hardware module.
+
+Hardware modules whose signals are affected by pin configuration are
+designated client devices. Again, each client device must be represented as a
+node in device tree, just like any other hardware module.
+
+For a client device to operate correctly, certain pin controllers must
+set up certain specific pin configurations. Some client devices need a
+single static pin configuration, e.g. set up during initialization. Others
+need to reconfigure pins at run-time, for example to tri-state pins when the
+device is inactive. Hence, each client device can define a set of named
+states. The number and names of those states is defined by the client device's
+own binding.
+
+The common pinctrl bindings defined in this file provide an infrastructure
+for client device device tree nodes to map those state names to the pin
+configuration used by those states.
+
+Note that pin controllers themselves may also be client devices of themselves.
+For example, a pin controller may set up its own "active" state when the
+driver loads. This would allow representing a board's static pin configuration
+in a single place, rather than splitting it across multiple client device
+nodes. The decision to do this or not somewhat rests with the author of
+individual board device tree files, and any requirements imposed by the
+bindings for the individual client devices in use by that board, i.e. whether
+they require certain specific named states for dynamic pin configuration.
+
+== Pinctrl client devices ==
+
+For each client device individually, every pin state is assigned an integer
+ID. These numbers start at 0, and are contiguous. For each state ID, a unique
+property exists to define the pin configuration. Each state may also be
+assigned a name. When names are used, another property exists to map from
+those names to the integer IDs.
+
+Each client device's own binding determines the set of states the must be
+defined in its device tree node, and whether to define the set of state
+IDs that must be provided, or whether to define the set of state names that
+must be provided.
+
+Required properties:
+pinctrl-0:     List of phandles, each pointing at a pin configuration
+               node. These referenced pin configuration nodes must be child
+               nodes of the pin controller that they configure. Multiple
+               entries may exist in this list so that multiple pin
+               controllers may be configured, or so that a state may be built
+               from multiple nodes for a single pin controller, each
+               contributing part of the overall configuration. See the next
+               section of this document for details of the format of these
+               pin configuration nodes.
+
+               In some cases, it may be useful to define a state, but for it
+               to be empty. This may be required when a common IP block is
+               used in an SoC either without a pin controller, or where the
+               pin controller does not affect the HW module in question. If
+               the binding for that IP block requires certain pin states to
+               exist, they must still be defined, but may be left empty.
+
+Optional properties:
+pinctrl-1:     List of phandles, each pointing at a pin configuration
+               node within a pin controller.
+...
+pinctrl-n:     List of phandles, each pointing at a pin configuration
+               node within a pin controller.
+pinctrl-names: The list of names to assign states. List entry 0 defines the
+               name for integer state ID 0, list entry 1 for state ID 1, and
+               so on.
+
+For example:
+
+       /* For a client device requiring named states */
+       device {
+               pinctrl-names = "active", "idle";
+               pinctrl-0 = <&state_0_node_a>;
+               pinctrl-1 = <&state_1_node_a &state_1_node_b>;
+       };
+
+       /* For the same device if using state IDs */
+       device {
+               pinctrl-0 = <&state_0_node_a>;
+               pinctrl-1 = <&state_1_node_a &state_1_node_b>;
+       };
+
+       /*
+        * For an IP block whose binding supports pin configuration,
+        * but in use on an SoC that doesn't have any pin control hardware
+        */
+       device {
+               pinctrl-names = "active", "idle";
+               pinctrl-0 = <>;
+               pinctrl-1 = <>;
+       };
+
+== Pin controller devices ==
+
+Pin controller devices should contain the pin configuration nodes that client
+devices reference.
+
+For example:
+
+       pincontroller {
+               ... /* Standard DT properties for the device itself elided */
+
+               state_0_node_a {
+                       ...
+               };
+               state_1_node_a {
+                       ...
+               };
+               state_1_node_b {
+                       ...
+               };
+       }
+
+The contents of each of those pin configuration child nodes is defined
+entirely by the binding for the individual pin controller device. There
+exists no common standard for this content.
+
+The pin configuration nodes need not be direct children of the pin controller
+device; they may be grandchildren, for example. Whether this is legal, and
+whether there is any interaction between the child and intermediate parent
+nodes, is again defined entirely by the binding for the individual pin
+controller device.