1 == Introduction == 1 == Introduction ==
2 2
3 Hardware modules that control pin multiplexing 3 Hardware modules that control pin multiplexing or configuration parameters
4 such as pull-up/down, tri-state, drive-strengt 4 such as pull-up/down, tri-state, drive-strength etc are designated as pin
5 controllers. Each pin controller must be repre 5 controllers. Each pin controller must be represented as a node in device tree,
6 just like any other hardware module. 6 just like any other hardware module.
7 7
8 Hardware modules whose signals are affected by 8 Hardware modules whose signals are affected by pin configuration are
9 designated client devices. Again, each client 9 designated client devices. Again, each client device must be represented as a
10 node in device tree, just like any other hardw 10 node in device tree, just like any other hardware module.
11 11
12 For a client device to operate correctly, cert 12 For a client device to operate correctly, certain pin controllers must
13 set up certain specific pin configurations. So 13 set up certain specific pin configurations. Some client devices need a
14 single static pin configuration, e.g. set up d 14 single static pin configuration, e.g. set up during initialization. Others
15 need to reconfigure pins at run-time, for exam 15 need to reconfigure pins at run-time, for example to tri-state pins when the
16 device is inactive. Hence, each client device 16 device is inactive. Hence, each client device can define a set of named
17 states. The number and names of those states i 17 states. The number and names of those states is defined by the client device's
18 own binding. 18 own binding.
19 19
20 The common pinctrl bindings defined in this fi 20 The common pinctrl bindings defined in this file provide an infrastructure
21 for client device device tree nodes to map tho 21 for client device device tree nodes to map those state names to the pin
22 configuration used by those states. 22 configuration used by those states.
23 23
24 Note that pin controllers themselves may also 24 Note that pin controllers themselves may also be client devices of themselves.
25 For example, a pin controller may set up its o 25 For example, a pin controller may set up its own "active" state when the
26 driver loads. This would allow representing a 26 driver loads. This would allow representing a board's static pin configuration
27 in a single place, rather than splitting it ac 27 in a single place, rather than splitting it across multiple client device
28 nodes. The decision to do this or not somewhat 28 nodes. The decision to do this or not somewhat rests with the author of
29 individual board device tree files, and any re 29 individual board device tree files, and any requirements imposed by the
30 bindings for the individual client devices in 30 bindings for the individual client devices in use by that board, i.e. whether
31 they require certain specific named states for 31 they require certain specific named states for dynamic pin configuration.
32 32
33 == Pinctrl client devices == 33 == Pinctrl client devices ==
34 34
35 For each client device individually, every pin 35 For each client device individually, every pin state is assigned an integer
36 ID. These numbers start at 0, and are contiguo 36 ID. These numbers start at 0, and are contiguous. For each state ID, a unique
37 property exists to define the pin configuratio 37 property exists to define the pin configuration. Each state may also be
38 assigned a name. When names are used, another 38 assigned a name. When names are used, another property exists to map from
39 those names to the integer IDs. 39 those names to the integer IDs.
40 40
41 Each client device's own binding determines th 41 Each client device's own binding determines the set of states that must be
42 defined in its device tree node, and whether t 42 defined in its device tree node, and whether to define the set of state
43 IDs that must be provided, or whether to defin 43 IDs that must be provided, or whether to define the set of state names that
44 must be provided. 44 must be provided.
45 45
46 Required properties: 46 Required properties:
47 pinctrl-0: List of phandles, each pointin 47 pinctrl-0: List of phandles, each pointing at a pin configuration
48 node. These referenced pin con 48 node. These referenced pin configuration nodes must be child
49 nodes of the pin controller th 49 nodes of the pin controller that they configure. Multiple
50 entries may exist in this list 50 entries may exist in this list so that multiple pin
51 controllers may be configured, 51 controllers may be configured, or so that a state may be built
52 from multiple nodes for a sing 52 from multiple nodes for a single pin controller, each
53 contributing part of the overa 53 contributing part of the overall configuration. See the next
54 section of this document for d 54 section of this document for details of the format of these
55 pin configuration nodes. 55 pin configuration nodes.
56 56
57 In some cases, it may be usefu 57 In some cases, it may be useful to define a state, but for it
58 to be empty. This may be requi 58 to be empty. This may be required when a common IP block is
59 used in an SoC either without 59 used in an SoC either without a pin controller, or where the
60 pin controller does not affect 60 pin controller does not affect the HW module in question. If
61 the binding for that IP block 61 the binding for that IP block requires certain pin states to
62 exist, they must still be defi 62 exist, they must still be defined, but may be left empty.
63 63
64 Optional properties: 64 Optional properties:
65 pinctrl-1: List of phandles, each pointin 65 pinctrl-1: List of phandles, each pointing at a pin configuration
66 node within a pin controller. 66 node within a pin controller.
67 ... 67 ...
68 pinctrl-n: List of phandles, each pointin 68 pinctrl-n: List of phandles, each pointing at a pin configuration
69 node within a pin controller. 69 node within a pin controller.
70 pinctrl-names: The list of names to assign st 70 pinctrl-names: The list of names to assign states. List entry 0 defines the
71 name for integer state ID 0, l 71 name for integer state ID 0, list entry 1 for state ID 1, and
72 so on. 72 so on.
73 73
74 For example: 74 For example:
75 75
76 /* For a client device requiring named 76 /* For a client device requiring named states */
77 device { 77 device {
78 pinctrl-names = "active", "idl 78 pinctrl-names = "active", "idle";
79 pinctrl-0 = <&state_0_node_a>; 79 pinctrl-0 = <&state_0_node_a>;
80 pinctrl-1 = <&state_1_node_a>, !! 80 pinctrl-1 = <&state_1_node_a &state_1_node_b>;
81 }; 81 };
82 82
83 /* For the same device if using state 83 /* For the same device if using state IDs */
84 device { 84 device {
85 pinctrl-0 = <&state_0_node_a>; 85 pinctrl-0 = <&state_0_node_a>;
86 pinctrl-1 = <&state_1_node_a>, !! 86 pinctrl-1 = <&state_1_node_a &state_1_node_b>;
87 }; 87 };
88 88
89 /* 89 /*
90 * For an IP block whose binding suppo 90 * For an IP block whose binding supports pin configuration,
91 * but in use on an SoC that doesn't h 91 * but in use on an SoC that doesn't have any pin control hardware
92 */ 92 */
93 device { 93 device {
94 pinctrl-names = "active", "idl 94 pinctrl-names = "active", "idle";
95 pinctrl-0 = <>; 95 pinctrl-0 = <>;
96 pinctrl-1 = <>; 96 pinctrl-1 = <>;
97 }; 97 };
98 98
99 == Pin controller devices == 99 == Pin controller devices ==
>> 100 Required properties: See the pin controller driver specific documentation
100 101
101 See pinctrl.yaml !! 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.
102 141
103 == Generic pin multiplexing node content == 142 == Generic pin multiplexing node content ==
104 143
105 See pinmux-node.yaml !! 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.
106 229
107 == Generic pin configuration node content == 230 == Generic pin configuration node content ==
108 231
109 See pincfg-node.yaml !! 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 drive-strength-microamp - sink or source at most X uA
>> 262 input-enable - enable input on pin (no effect on output, such as
>> 263 enabling an input buffer)
>> 264 input-disable - disable input on pin (no effect on output, such as
>> 265 disabling an input buffer)
>> 266 input-schmitt-enable - enable schmitt-trigger mode
>> 267 input-schmitt-disable - disable schmitt-trigger mode
>> 268 input-debounce - debounce mode with debound time X
>> 269 power-source - select between different power supplies
>> 270 low-power-enable - enable low power mode
>> 271 low-power-disable - disable low power mode
>> 272 output-disable - disable output on a pin (such as disable an output
>> 273 buffer)
>> 274 output-enable - enable output on a pin without actively driving it
>> 275 (such as enabling an output buffer)
>> 276 output-low - set the pin to output mode with low level
>> 277 output-high - set the pin to output mode with high level
>> 278 sleep-hardware-state - indicate this is sleep related state which will be programmed
>> 279 into the registers for the sleep state.
>> 280 slew-rate - set the slew rate
>> 281 skew-delay - this affects the expected clock skew on input pins
>> 282 and the delay before latching a value to an output
>> 283 pin. Typically indicates how many double-inverters are
>> 284 used to delay the signal.
>> 285
>> 286 For example:
>> 287
>> 288 state_0_node_a {
>> 289 cts_rxd {
>> 290 pins = "GPIO0_AJ5", "GPIO2_AH4"; /* CTS+RXD */
>> 291 bias-pull-up;
>> 292 };
>> 293 };
>> 294 state_1_node_a {
>> 295 rts_txd {
>> 296 pins = "GPIO1_AJ3", "GPIO3_AH3"; /* RTS+TXD */
>> 297 output-high;
>> 298 };
>> 299 };
>> 300 state_2_node_a {
>> 301 foo {
>> 302 group = "foo-group";
>> 303 bias-pull-up;
>> 304 };
>> 305 };
>> 306 state_3_node_a {
>> 307 mux {
>> 308 pinmux = <GPIOx_PINm_MUXn>, <GPIOx_PINj_MUXk)>;
>> 309 input-enable;
>> 310 };
>> 311 };
>> 312
>> 313 Some of the generic properties take arguments. For those that do, the
>> 314 arguments are described below.
>> 315
>> 316 - pins takes a list of pin names or IDs as a required argument. The specific
>> 317 binding for the hardware defines:
>> 318 - Whether the entries are integers or strings, and their meaning.
>> 319
>> 320 - pinmux takes a list of pin IDs and mux settings as required argument. The
>> 321 specific bindings for the hardware defines:
>> 322 - How pin IDs and mux settings are defined and assembled together in a single
>> 323 integer or an array of integers.
>> 324
>> 325 - bias-pull-up, -down and -pin-default take as optional argument on hardware
>> 326 supporting it the pull strength in Ohm. bias-disable will disable the pull.
>> 327
>> 328 - drive-strength takes as argument the target strength in mA.
>> 329
>> 330 - drive-strength-microamp takes as argument the target strength in uA.
>> 331
>> 332 - input-debounce takes the debounce time in usec as argument
>> 333 or 0 to disable debouncing
>> 334
>> 335 More in-depth documentation on these parameters can be found in
>> 336 <include/linux/pinctrl/pinconf-generic.h>
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.