1== Introduction == 2 3Hardware modules that control pin multiplexing or configuration parameters 4such as pull-up/down, tri-state, drive-strength etc are designated as pin 5controllers. Each pin controller must be represented as a node in device tree, 6just like any other hardware module. 7 8Hardware modules whose signals are affected by pin configuration are 9designated client devices. Again, each client device must be represented as a 10node in device tree, just like any other hardware module. 11 12For a client device to operate correctly, certain pin controllers must 13set up certain specific pin configurations. Some client devices need a 14single static pin configuration, e.g. set up during initialization. Others 15need to reconfigure pins at run-time, for example to tri-state pins when the 16device is inactive. Hence, each client device can define a set of named 17states. The number and names of those states is defined by the client device's 18own binding. 19 20The common pinctrl bindings defined in this file provide an infrastructure 21for client device device tree nodes to map those state names to the pin 22configuration used by those states. 23 24Note that pin controllers themselves may also be client devices of themselves. 25For example, a pin controller may set up its own "active" state when the 26driver loads. This would allow representing a board's static pin configuration 27in a single place, rather than splitting it across multiple client device 28nodes. The decision to do this or not somewhat rests with the author of 29individual board device tree files, and any requirements imposed by the 30bindings for the individual client devices in use by that board, i.e. whether 31they require certain specific named states for dynamic pin configuration. 32 33== Pinctrl client devices == 34 35For each client device individually, every pin state is assigned an integer 36ID. These numbers start at 0, and are contiguous. For each state ID, a unique 37property exists to define the pin configuration. Each state may also be 38assigned a name. When names are used, another property exists to map from 39those names to the integer IDs. 40 41Each client device's own binding determines the set of states that must be 42defined in its device tree node, and whether to define the set of state 43IDs that must be provided, or whether to define the set of state names that 44must be provided. 45 46Required properties: 47pinctrl-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 64Optional properties: 65pinctrl-1: List of phandles, each pointing at a pin configuration 66 node within a pin controller. 67... 68pinctrl-n: List of phandles, each pointing at a pin configuration 69 node within a pin controller. 70pinctrl-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 74For 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 == 100Required properties: See the pin controller driver specific documentation 101 102Optional properties: 103#pinctrl-cells: Number of pin control cells in addition to the index within the 104 pin controller device instance 105 106Pin controller devices should contain the pin configuration nodes that client 107devices reference. 108 109For example: 110 111 pincontroller { 112 ... /* Standard DT properties for the device itself elided */ 113 114 state_0_node_a { 115 ... 116 }; 117 state_1_node_a { 118 ... 119 }; 120 state_1_node_b { 121 ... 122 }; 123 } 124 125The contents of each of those pin configuration child nodes is defined 126entirely by the binding for the individual pin controller device. There 127exists no common standard for this content. The pinctrl framework only 128provides generic helper bindings that the pin controller driver can use. 129 130The pin configuration nodes need not be direct children of the pin controller 131device; they may be grandchildren, for example. Whether this is legal, and 132whether there is any interaction between the child and intermediate parent 133nodes, is again defined entirely by the binding for the individual pin 134controller device. 135 136== Generic pin multiplexing node content == 137 138pin multiplexing nodes: 139 140function - the mux function to select 141groups - the list of groups to select with this function 142 (either this or "pins" must be specified) 143pins - the list of pins to select with this function (either 144 this or "groups" must be specified) 145 146Example: 147 148state_0_node_a { 149 uart0 { 150 function = "uart0"; 151 groups = "u0rxtx", "u0rtscts"; 152 }; 153}; 154state_1_node_a { 155 spi0 { 156 function = "spi0"; 157 groups = "spi0pins"; 158 }; 159}; 160state_2_node_a { 161 function = "i2c0"; 162 pins = "mfio29", "mfio30"; 163}; 164 165Optionally an altenative binding can be used if more suitable depending on the 166pin controller hardware. For hardaware where there is a large number of identical 167pin controller instances, naming each pin and function can easily become 168unmaintainable. This is especially the case if the same controller is used for 169different pins and functions depending on the SoC revision and packaging. 170 171For cases like this, the pin controller driver may use pinctrl-pin-array helper 172binding with a hardware based index and a number of pin configuration values: 173 174pincontroller { 175 ... /* Standard DT properties for the device itself elided */ 176 #pinctrl-cells = <2>; 177 178 state_0_node_a { 179 pinctrl-pin-array = < 180 0 A_DELAY_PS(0) G_DELAY_PS(120) 181 4 A_DELAY_PS(0) G_DELAY_PS(360) 182 ... 183 >; 184 }; 185 ... 186}; 187 188Above #pinctrl-cells specifies the number of value cells in addition to the 189index of the registers. This is similar to the interrupts-extended binding with 190one exception. There is no need to specify the phandle for each entry as that 191is already known as the defined pins are always children of the pin controller 192node. Further having the phandle pointing to another pin controller would not 193currently work as the pinctrl framework uses named modes to group pins for each 194pin control device. 195 196The index for pinctrl-pin-array must relate to the hardware for the pinctrl 197registers, and must not be a virtual index of pin instances. The reason for 198this is to avoid mapping of the index in the dts files and the pin controller 199driver as it can change. 200 201== Generic pin configuration node content == 202 203Many data items that are represented in a pin configuration node are common 204and generic. Pin control bindings should use the properties defined below 205where they are applicable; not all of these properties are relevant or useful 206for all hardware or binding structures. Each individual binding document 207should state which of these generic properties, if any, are used, and the 208structure of the DT nodes that contain these properties. 209 210Supported generic properties are: 211 212pins - the list of pins that properties in the node 213 apply to (either this or "group" has to be 214 specified) 215group - the group to apply the properties to, if the driver 216 supports configuration of whole groups rather than 217 individual pins (either this or "pins" has to be 218 specified) 219bias-disable - disable any pin bias 220bias-high-impedance - high impedance mode ("third-state", "floating") 221bias-bus-hold - latch weakly 222bias-pull-up - pull up the pin 223bias-pull-down - pull down the pin 224bias-pull-pin-default - use pin-default pull state 225drive-push-pull - drive actively high and low 226drive-open-drain - drive with open drain 227drive-open-source - drive with open source 228drive-strength - sink or source at most X mA 229input-enable - enable input on pin (no effect on output) 230input-disable - disable input on pin (no effect on output) 231input-schmitt-enable - enable schmitt-trigger mode 232input-schmitt-disable - disable schmitt-trigger mode 233input-debounce - debounce mode with debound time X 234power-source - select between different power supplies 235low-power-enable - enable low power mode 236low-power-disable - disable low power mode 237output-low - set the pin to output mode with low level 238output-high - set the pin to output mode with high level 239slew-rate - set the slew rate 240 241For example: 242 243state_0_node_a { 244 cts_rxd { 245 pins = "GPIO0_AJ5", "GPIO2_AH4"; /* CTS+RXD */ 246 bias-pull-up; 247 }; 248}; 249state_1_node_a { 250 rts_txd { 251 pins = "GPIO1_AJ3", "GPIO3_AH3"; /* RTS+TXD */ 252 output-high; 253 }; 254}; 255state_2_node_a { 256 foo { 257 group = "foo-group"; 258 bias-pull-up; 259 }; 260}; 261 262Some of the generic properties take arguments. For those that do, the 263arguments are described below. 264 265- pins takes a list of pin names or IDs as a required argument. The specific 266 binding for the hardware defines: 267 - Whether the entries are integers or strings, and their meaning. 268 269- bias-pull-up, -down and -pin-default take as optional argument on hardware 270 supporting it the pull strength in Ohm. bias-disable will disable the pull. 271 272- drive-strength takes as argument the target strength in mA. 273 274- input-debounce takes the debounce time in usec as argument 275 or 0 to disable debouncing 276 277More in-depth documentation on these parameters can be found in 278<include/linux/pinctrl/pinconf-generic.h> 279