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 Required properties: See the pin controller driver specific documentation
 101
 102 Optional properties:
 103 #pinctrl-cells: Number of pin control cells in addition to the index within the
 104                 pin controller device instance
 105
 106 pinctrl-use-default: Boolean. Indicates that the OS can use the boot default
 107                 pin configuration. This allows using an OS that does not have a
 108                 driver for the pin controller. This property can be set either
 109                 globally for the pin controller or in child nodes for individual
 110                 pin group control.
 111
 112 Pin controller devices should contain the pin configuration nodes that client
 113 devices reference.
 114
 115 For example:
 116
 117         pincontroller {
 118                 ... /* Standard DT properties for the device itself elided */
 119
 120                 state_0_node_a {
 121                         ...
 122                 };
 123                 state_1_node_a {
 124                         ...
 125                 };
 126                 state_1_node_b {
 127                         ...
 128                 };
 129         }
 130
 131 The contents of each of those pin configuration child nodes is defined
 132 entirely by the binding for the individual pin controller device. There
 133 exists no common standard for this content. The pinctrl framework only
 134 provides generic helper bindings that the pin controller driver can use.
 135
 136 The pin configuration nodes need not be direct children of the pin controller
 137 device; they may be grandchildren, for example. Whether this is legal, and
 138 whether there is any interaction between the child and intermediate parent
 139 nodes, is again defined entirely by the binding for the individual pin
 140 controller device.
 141
 142 == Generic pin multiplexing node content ==
 143
 144 pin multiplexing nodes:
 145
 146 function                - the mux function to select
 147 groups                  - the list of groups to select with this function
 148                           (either this or "pins" must be specified)
 149 pins                    - the list of pins to select with this function (either
 150                           this or "groups" must be specified)
 151
 152 Example:
 153
 154 state_0_node_a {
 155         uart0 {
 156                 function = "uart0";
 157                 groups = "u0rxtx", "u0rtscts";
 158         };
 159 };
 160 state_1_node_a {
 161         spi0 {
 162                 function = "spi0";
 163                 groups = "spi0pins";
 164         };
 165 };
 166 state_2_node_a {
 167         function = "i2c0";
 168         pins = "mfio29", "mfio30";
 169 };
 170
 171 Optionally an alternative binding can be used if more suitable depending on the
 172 pin controller hardware. For hardware where there is a large number of identical
 173 pin controller instances, naming each pin and function can easily become
 174 unmaintainable. This is especially the case if the same controller is used for
 175 different pins and functions depending on the SoC revision and packaging.
 176
 177 For cases like this, the pin controller driver may use pinctrl-pin-array helper
 178 binding with a hardware based index and a number of pin configuration values:
 179
 180 pincontroller {
 181         ... /* Standard DT properties for the device itself elided */
 182         #pinctrl-cells = <2>;
 183
 184         state_0_node_a {
 185                 pinctrl-pin-array = <
 186                         0 A_DELAY_PS(0) G_DELAY_PS(120)
 187                         4 A_DELAY_PS(0) G_DELAY_PS(360)
 188                         ...
 189                 >;
 190         };
 191         ...
 192 };
 193
 194 Above #pinctrl-cells specifies the number of value cells in addition to the
 195 index of the registers. This is similar to the interrupts-extended binding with
 196 one exception. There is no need to specify the phandle for each entry as that
 197 is already known as the defined pins are always children of the pin controller
 198 node. Further having the phandle pointing to another pin controller would not
 199 currently work as the pinctrl framework uses named modes to group pins for each
 200 pin control device.
 201
 202 The index for pinctrl-pin-array must relate to the hardware for the pinctrl
 203 registers, and must not be a virtual index of pin instances. The reason for
 204 this is to avoid mapping of the index in the dts files and the pin controller
 205 driver as it can change.
 206
 207 For hardware where pin multiplexing configurations have to be specified for
 208 each single pin the number of required sub-nodes containing "pin" and
 209 "function" properties can quickly escalate and become hard to write and
 210 maintain.
 211
 212 For cases like this, the pin controller driver may use the pinmux helper
 213 property, where the pin identifier is provided with mux configuration settings
 214 in a pinmux group. A pinmux group consists of the pin identifier and mux
 215 settings represented as a single integer or an array of integers.
 216
 217 The pinmux property accepts an array of pinmux groups, each of them describing
 218 a single pin multiplexing configuration.
 219
 220 pincontroller {
 221         state_0_node_a {
 222                 pinmux = <PINMUX_GROUP>, <PINMUX_GROUP>, ...;
 223         };
 224 };
 225
 226 Each individual pin controller driver bindings documentation shall specify
 227 how pin IDs and pin multiplexing configuration are defined and assembled
 228 together in a pinmux group.
 229
 230 == Generic pin configuration node content ==
 231
 232 Many data items that are represented in a pin configuration node are common
 233 and generic. Pin control bindings should use the properties defined below
 234 where they are applicable; not all of these properties are relevant or useful
 235 for all hardware or binding structures. Each individual binding document
 236 should state which of these generic properties, if any, are used, and the
 237 structure of the DT nodes that contain these properties.
 238
 239 Supported generic properties are:
 240
 241 pins                    - the list of pins that properties in the node
 242                           apply to (either this, "group" or "pinmux" has to be
 243                           specified)
 244 group                   - the group to apply the properties to, if the driver
 245                           supports configuration of whole groups rather than
 246                           individual pins (either this, "pins" or "pinmux" has
 247                           to be specified)
 248 pinmux                  - the list of numeric pin ids and their mux settings
 249                           that properties in the node apply to (either this,
 250                           "pins" or "groups" have to be specified)
 251 bias-disable            - disable any pin bias
 252 bias-high-impedance     - high impedance mode ("third-state", "floating")
 253 bias-bus-hold           - latch weakly
 254 bias-pull-up            - pull up the pin
 255 bias-pull-down          - pull down the pin
 256 bias-pull-pin-default   - use pin-default pull state
 257 drive-push-pull         - drive actively high and low
 258 drive-open-drain        - drive with open drain
 259 drive-open-source       - drive with open source
 260 drive-strength          - sink or source at most X mA
 261 input-enable            - enable input on pin (no effect on output, such as
 262                           enabling an input buffer)
 263 input-disable           - disable input on pin (no effect on output, such as
 264                           disabling an input buffer)
 265 input-schmitt-enable    - enable schmitt-trigger mode
 266 input-schmitt-disable   - disable schmitt-trigger mode
 267 input-debounce          - debounce mode with debound time X
 268 power-source            - select between different power supplies
 269 low-power-enable        - enable low power mode
 270 low-power-disable       - disable low power mode
 271 output-disable          - disable output on a pin (such as disable an output
 272                           buffer)
 273 output-enable           - enable output on a pin without actively driving it
 274                           (such as enabling an output buffer)
 275 output-low              - set the pin to output mode with low level
 276 output-high             - set the pin to output mode with high level
 277 sleep-hardware-state    - indicate this is sleep related state which will be programmed
 278                           into the registers for the sleep state.
 279 slew-rate               - set the slew rate
 280 skew-delay              - this affects the expected clock skew on input pins
 281                           and the delay before latching a value to an output
 282                           pin. Typically indicates how many double-inverters are
 283                           used to delay the signal.
 284
 285 For example:
 286
 287 state_0_node_a {
 288         cts_rxd {
 289                 pins = "GPIO0_AJ5", "GPIO2_AH4"; /* CTS+RXD */
 290                 bias-pull-up;
 291         };
 292 };
 293 state_1_node_a {
 294         rts_txd {
 295                 pins = "GPIO1_AJ3", "GPIO3_AH3"; /* RTS+TXD */
 296                 output-high;
 297         };
 298 };
 299 state_2_node_a {
 300         foo {
 301                 group = "foo-group";
 302                 bias-pull-up;
 303         };
 304 };
 305 state_3_node_a {
 306         mux {
 307                 pinmux = <GPIOx_PINm_MUXn>, <GPIOx_PINj_MUXk)>;
 308                 input-enable;
 309         };
 310 };
 311
 312 Some of the generic properties take arguments. For those that do, the
 313 arguments are described below.
 314
 315 - pins takes a list of pin names or IDs as a required argument. The specific
 316   binding for the hardware defines:
 317   - Whether the entries are integers or strings, and their meaning.
 318
 319 - pinmux takes a list of pin IDs and mux settings as required argument. The
 320   specific bindings for the hardware defines:
 321   - How pin IDs and mux settings are defined and assembled together in a single
 322     integer or an array of integers.
 323
 324 - bias-pull-up, -down and -pin-default take as optional argument on hardware
 325   supporting it the pull strength in Ohm. bias-disable will disable the pull.
 326
 327 - drive-strength takes as argument the target strength in mA.
 328
 329 - input-debounce takes the debounce time in usec as argument
 330   or 0 to disable debouncing
 331
 332 More in-depth documentation on these parameters can be found in
 333 <include/linux/pinctrl/pinconf-generic.h>