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 (either this or "pins" must be specified) 137 pins - the list of pins to select with this function (either 138 this or "groups" must be specified) 139 140 Example: 141 142 state_0_node_a { 143 uart0 { 144 function = "uart0"; 145 groups = "u0rxtx", "u0rtscts"; 146 }; 147 }; 148 state_1_node_a { 149 spi0 { 150 function = "spi0"; 151 groups = "spi0pins"; 152 }; 153 }; 154 state_2_node_a { 155 function = "i2c0"; 156 pins = "mfio29", "mfio30"; 157 }; 158 159 == Generic pin configuration node content == 160 161 Many data items that are represented in a pin configuration node are common 162 and generic. Pin control bindings should use the properties defined below 163 where they are applicable; not all of these properties are relevant or useful 164 for all hardware or binding structures. Each individual binding document 165 should state which of these generic properties, if any, are used, and the 166 structure of the DT nodes that contain these properties. 167 168 Supported generic properties are: 169 170 pins - the list of pins that properties in the node 171 apply to (either this or "group" has to be 172 specified) 173 group - the group to apply the properties to, if the driver 174 supports configuration of whole groups rather than 175 individual pins (either this or "pins" has to be 176 specified) 177 bias-disable - disable any pin bias 178 bias-high-impedance - high impedance mode ("third-state", "floating") 179 bias-bus-hold - latch weakly 180 bias-pull-up - pull up the pin 181 bias-pull-down - pull down the pin 182 bias-pull-pin-default - use pin-default pull state 183 drive-push-pull - drive actively high and low 184 drive-open-drain - drive with open drain 185 drive-open-source - drive with open source 186 drive-strength - sink or source at most X mA 187 input-enable - enable input on pin (no effect on output) 188 input-disable - disable input on pin (no effect on output) 189 input-schmitt-enable - enable schmitt-trigger mode 190 input-schmitt-disable - disable schmitt-trigger mode 191 input-debounce - debounce mode with debound time X 192 power-source - select between different power supplies 193 low-power-enable - enable low power mode 194 low-power-disable - disable low power mode 195 output-low - set the pin to output mode with low level 196 output-high - set the pin to output mode with high level 197 slew-rate - set the slew rate 198 199 For example: 200 201 state_0_node_a { 202 cts_rxd { 203 pins = "GPIO0_AJ5", "GPIO2_AH4"; /* CTS+RXD */ 204 bias-pull-up; 205 }; 206 }; 207 state_1_node_a { 208 rts_txd { 209 pins = "GPIO1_AJ3", "GPIO3_AH3"; /* RTS+TXD */ 210 output-high; 211 }; 212 }; 213 state_2_node_a { 214 foo { 215 group = "foo-group"; 216 bias-pull-up; 217 }; 218 }; 219 220 Some of the generic properties take arguments. For those that do, the 221 arguments are described below. 222 223 - pins takes a list of pin names or IDs as a required argument. The specific 224 binding for the hardware defines: 225 - Whether the entries are integers or strings, and their meaning. 226 227 - bias-pull-up, -down and -pin-default take as optional argument on hardware 228 supporting it the pull strength in Ohm. bias-disable will disable the pull. 229 230 - drive-strength takes as argument the target strength in mA. 231 232 - input-debounce takes the debounce time in usec as argument 233 or 0 to disable debouncing 234 235 More in-depth documentation on these parameters can be found in 236 <include/linux/pinctrl/pinconf-generic.h> 237
