dts: Bring in pinctrl device tree binding
authorSimon Glass <sjg@chromium.org>
Fri, 22 Jan 2016 02:43:28 +0000 (19:43 -0700)
committerSimon Glass <sjg@chromium.org>
Fri, 22 Jan 2016 03:42:34 +0000 (20:42 -0700)
Add this binding file since we now use it in U-Boot.

Signed-off-by: Simon Glass <sjg@chromium.org>
doc/device-tree-bindings/pinctrl/pinctrl-bindings.txt [new file with mode: 0644]

diff --git a/doc/device-tree-bindings/pinctrl/pinctrl-bindings.txt b/doc/device-tree-bindings/pinctrl/pinctrl-bindings.txt
new file mode 100644 (file)
index 0000000..b73c96d
--- /dev/null
@@ -0,0 +1,236 @@
+== 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 that 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.
+
+== Generic pin multiplexing node content ==
+
+pin multiplexing nodes:
+
+function               - the mux function to select
+groups                 - the list of groups to select with this function
+                         (either this or "pins" must be specified)
+pins                   - the list of pins to select with this function (either
+                         this or "groups" must be specified)
+
+Example:
+
+state_0_node_a {
+       uart0 {
+               function = "uart0";
+               groups = "u0rxtx", "u0rtscts";
+       };
+};
+state_1_node_a {
+       spi0 {
+               function = "spi0";
+               groups = "spi0pins";
+       };
+};
+state_2_node_a {
+       function = "i2c0";
+       pins = "mfio29", "mfio30";
+};
+
+== Generic pin configuration node content ==
+
+Many data items that are represented in a pin configuration node are common
+and generic. Pin control bindings should use the properties defined below
+where they are applicable; not all of these properties are relevant or useful
+for all hardware or binding structures. Each individual binding document
+should state which of these generic properties, if any, are used, and the
+structure of the DT nodes that contain these properties.
+
+Supported generic properties are:
+
+pins                   - the list of pins that properties in the node
+                         apply to (either this or "group" has to be
+                         specified)
+group                  - the group to apply the properties to, if the driver
+                         supports configuration of whole groups rather than
+                         individual pins (either this or "pins" has to be
+                         specified)
+bias-disable           - disable any pin bias
+bias-high-impedance    - high impedance mode ("third-state", "floating")
+bias-bus-hold          - latch weakly
+bias-pull-up           - pull up the pin
+bias-pull-down         - pull down the pin
+bias-pull-pin-default  - use pin-default pull state
+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-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-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
+
+For example:
+
+state_0_node_a {
+       cts_rxd {
+               pins = "GPIO0_AJ5", "GPIO2_AH4"; /* CTS+RXD */
+               bias-pull-up;
+       };
+};
+state_1_node_a {
+       rts_txd {
+               pins = "GPIO1_AJ3", "GPIO3_AH3"; /* RTS+TXD */
+               output-high;
+       };
+};
+state_2_node_a {
+       foo {
+               group = "foo-group";
+               bias-pull-up;
+       };
+};
+
+Some of the generic properties take arguments. For those that do, the
+arguments are described below.
+
+- pins takes a list of pin names or IDs as a required argument. The specific
+  binding for the hardware defines:
+  - Whether the entries are integers or strings, and their meaning.
+
+- 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.
+
+- drive-strength takes as argument the target strength in mA.
+
+- input-debounce takes the debounce time in usec as argument
+  or 0 to disable debouncing
+
+More in-depth documentation on these parameters can be found in
+<include/linux/pinctrl/pinconf-generic.h>