Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt

   1 == Introduction ==
   2
   3 Hardware modules that control pin multiplexing or configuration parameters
   4 such as pull-up/down, tri-state, drive-strength etc are designated as pin
   5 controllers. Each pin controller must be represented as a node in device tree,
   6 just like any other hardware module.
   7
   8 Hardware modules whose signals are affected by pin configuration are
   9 designated client devices. Again, each client device must be represented as a
  10 node in device tree, just like any other hardware module.
  11
  12 For a client device to operate correctly, certain pin controllers must
  13 set up certain specific pin configurations. Some client devices need a
  14 single static pin configuration, e.g. set up during initialization. Others
  15 need to reconfigure pins at run-time, for example to tri-state pins when the
  16 device is inactive. Hence, each client device can define a set of named
  17 states. The number and names of those states is defined by the client device's
  18 own binding.
  19
  20 The common pinctrl bindings defined in this file provide an infrastructure
  21 for client device device tree nodes to map those state names to the pin
  22 configuration used by those states.
  23
  24 Note that pin controllers themselves may also be client devices of themselves.
  25 For example, a pin controller may set up its own "active" state when the
  26 driver loads. This would allow representing a board's static pin configuration
  27 in a single place, rather than splitting it across multiple client device
  28 nodes. The decision to do this or not somewhat rests with the author of
  29 individual board device tree files, and any requirements imposed by the
  30 bindings for the individual client devices in use by that board, i.e. whether
  31 they require certain specific named states for dynamic pin configuration.
  32
  33 == Pinctrl client devices ==
  34
  35 For each client device individually, every pin state is assigned an integer
  36 ID. These numbers start at 0, and are contiguous. For each state ID, a unique
  37 property exists to define the pin configuration. Each state may also be
  38 assigned a name. When names are used, another property exists to map from
  39 those names to the integer IDs.
  40
  41 Each client device's own binding determines the set of states that must be
  42 defined in its device tree node, and whether to define the set of state
  43 IDs that must be provided, or whether to define the set of state names that
  44 must be provided.
  45
  46 Required properties:
  47 pinctrl-0:      List of phandles, each pointing at a pin configuration
  48                 node. These referenced pin configuration nodes must be child
  49                 nodes of the pin controller that they configure. Multiple
  50                 entries may exist in this list so that multiple pin
  51                 controllers may be configured, or so that a state may be built
  52                 from multiple nodes for a single pin controller, each
  53                 contributing part of the overall configuration. See the next
  54                 section of this document for details of the format of these
  55                 pin configuration nodes.
  56
  57                 In some cases, it may be useful to define a state, but for it
  58                 to be empty. This may be required when a common IP block is
  59                 used in an SoC either without a pin controller, or where the
  60                 pin controller does not affect the HW module in question. If
  61                 the binding for that IP block requires certain pin states to
  62                 exist, they must still be defined, but may be left empty.
  63
  64 Optional properties:
  65 pinctrl-1:      List of phandles, each pointing at a pin configuration
  66                 node within a pin controller.
  67 ...
  68 pinctrl-n:      List of phandles, each pointing at a pin configuration
  69                 node within a pin controller.
  70 pinctrl-names:  The list of names to assign states. List entry 0 defines the
  71                 name for integer state ID 0, list entry 1 for state ID 1, and
  72                 so on.
  73
  74 For example:
  75
  76         /* For a client device requiring named states */
  77         device {
  78                 pinctrl-names = "active", "idle";
  79                 pinctrl-0 = <&state_0_node_a>;
  80                 pinctrl-1 = <&state_1_node_a &state_1_node_b>;
  81         };
  82
  83         /* For the same device if using state IDs */
  84         device {
  85                 pinctrl-0 = <&state_0_node_a>;
  86                 pinctrl-1 = <&state_1_node_a &state_1_node_b>;
  87         };
  88
  89         /*
  90          * For an IP block whose binding supports pin configuration,
  91          * but in use on an SoC that doesn't have any pin control hardware
  92          */
  93         device {
  94                 pinctrl-names = "active", "idle";
  95                 pinctrl-0 = <>;
  96                 pinctrl-1 = <>;
  97         };
  98
  99 == Pin controller devices ==
 100
 101 Pin controller devices should contain the pin configuration nodes that client
 102 devices reference.
 103
 104 For example:
 105
 106         pincontroller {
 107                 ... /* Standard DT properties for the device itself elided */
 108
 109                 state_0_node_a {
 110                         ...
 111                 };
 112                 state_1_node_a {
 113                         ...
 114                 };
 115                 state_1_node_b {
 116                         ...
 117                 };
 118         }
 119
 120 The contents of each of those pin configuration child nodes is defined
 121 entirely by the binding for the individual pin controller device. There
 122 exists no common standard for this content.
 123
 124 The pin configuration nodes need not be direct children of the pin controller
 125 device; they may be grandchildren, for example. Whether this is legal, and
 126 whether there is any interaction between the child and intermediate parent
 127 nodes, is again defined entirely by the binding for the individual pin
 128 controller device.
 129
 130 == Generic pin multiplexing node content ==
 131
 132 pin multiplexing nodes:
 133
 134 function                - the mux function to select
 135 groups                  - the list of groups to select with this function
 136
 137 Example:
 138
 139 state_0_node_a {
 140         uart0 {
 141                 function = "uart0";
 142                 groups = "u0rxtx", "u0rtscts";
 143         };
 144 };
 145 state_1_node_a {
 146         spi0 {
 147                 function = "spi0";
 148                 groups = "spi0pins";
 149         };
 150 };
 151
 152 == Generic pin configuration node content ==
 153
 154 Many data items that are represented in a pin configuration node are common
 155 and generic. Pin control bindings should use the properties defined below
 156 where they are applicable; not all of these properties are relevant or useful
 157 for all hardware or binding structures. Each individual binding document
 158 should state which of these generic properties, if any, are used, and the
 159 structure of the DT nodes that contain these properties.
 160
 161 Supported generic properties are:
 162
 163 pins                    - the list of pins that properties in the node
 164                           apply to (either this or "group" has to be
 165                           specified)
 166 group                   - the group to apply the properties to, if the driver
 167                           supports configuration of whole groups rather than
 168                           individual pins (either this or "pins" has to be
 169                           specified)
 170 bias-disable            - disable any pin bias
 171 bias-high-impedance     - high impedance mode ("third-state", "floating")
 172 bias-bus-hold           - latch weakly
 173 bias-pull-up            - pull up the pin
 174 bias-pull-down          - pull down the pin
 175 bias-pull-pin-default   - use pin-default pull state
 176 drive-push-pull         - drive actively high and low
 177 drive-open-drain        - drive with open drain
 178 drive-open-source       - drive with open source
 179 drive-strength          - sink or source at most X mA
 180 input-enable            - enable input on pin (no effect on output)
 181 input-disable           - disable input on pin (no effect on output)
 182 input-schmitt-enable    - enable schmitt-trigger mode
 183 input-schmitt-disable   - disable schmitt-trigger mode
 184 input-debounce          - debounce mode with debound time X
 185 power-source            - select between different power supplies
 186 low-power-enable        - enable low power mode
 187 low-power-disable       - disable low power mode
 188 output-low              - set the pin to output mode with low level
 189 output-high             - set the pin to output mode with high level
 190 slew-rate               - set the slew rate
 191
 192 For example:
 193
 194 state_0_node_a {
 195         cts_rxd {
 196                 pins = "GPIO0_AJ5", "GPIO2_AH4"; /* CTS+RXD */
 197                 bias-pull-up;
 198         };
 199 };
 200 state_1_node_a {
 201         rts_txd {
 202                 pins = "GPIO1_AJ3", "GPIO3_AH3"; /* RTS+TXD */
 203                 output-high;
 204         };
 205 };
 206 state_2_node_a {
 207         foo {
 208                 group = "foo-group";
 209                 bias-pull-up;
 210         };
 211 };
 212
 213 Some of the generic properties take arguments. For those that do, the
 214 arguments are described below.
 215
 216 - pins takes a list of pin names or IDs as a required argument. The specific
 217   binding for the hardware defines:
 218   - Whether the entries are integers or strings, and their meaning.
 219
 220 - bias-pull-up, -down and -pin-default take as optional argument on hardware
 221   supporting it the pull strength in Ohm. bias-disable will disable the pull.
 222
 223 - drive-strength takes as argument the target strength in mA.
 224
 225 - input-debounce takes the debounce time in usec as argument
 226   or 0 to disable debouncing
 227
 228 More in-depth documentation on these parameters can be found in
 229 <include/linux/pinctrl/pinconf-generic.h>