blob: b73c96d24f59247da9d0ecbe51225e6f54271619 [file] [log] [blame]
Simon Glass61101e02016-01-21 19:43:28 -07001== 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 ==
100
101Pin controller devices should contain the pin configuration nodes that client
102devices reference.
103
104For 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
120The contents of each of those pin configuration child nodes is defined
121entirely by the binding for the individual pin controller device. There
122exists no common standard for this content.
123
124The pin configuration nodes need not be direct children of the pin controller
125device; they may be grandchildren, for example. Whether this is legal, and
126whether there is any interaction between the child and intermediate parent
127nodes, is again defined entirely by the binding for the individual pin
128controller device.
129
130== Generic pin multiplexing node content ==
131
132pin multiplexing nodes:
133
134function - the mux function to select
135groups - the list of groups to select with this function
136 (either this or "pins" must be specified)
137pins - the list of pins to select with this function (either
138 this or "groups" must be specified)
139
140Example:
141
142state_0_node_a {
143 uart0 {
144 function = "uart0";
145 groups = "u0rxtx", "u0rtscts";
146 };
147};
148state_1_node_a {
149 spi0 {
150 function = "spi0";
151 groups = "spi0pins";
152 };
153};
154state_2_node_a {
155 function = "i2c0";
156 pins = "mfio29", "mfio30";
157};
158
159== Generic pin configuration node content ==
160
161Many data items that are represented in a pin configuration node are common
162and generic. Pin control bindings should use the properties defined below
163where they are applicable; not all of these properties are relevant or useful
164for all hardware or binding structures. Each individual binding document
165should state which of these generic properties, if any, are used, and the
166structure of the DT nodes that contain these properties.
167
168Supported generic properties are:
169
170pins - the list of pins that properties in the node
171 apply to (either this or "group" has to be
172 specified)
173group - 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)
177bias-disable - disable any pin bias
178bias-high-impedance - high impedance mode ("third-state", "floating")
179bias-bus-hold - latch weakly
180bias-pull-up - pull up the pin
181bias-pull-down - pull down the pin
182bias-pull-pin-default - use pin-default pull state
183drive-push-pull - drive actively high and low
184drive-open-drain - drive with open drain
185drive-open-source - drive with open source
186drive-strength - sink or source at most X mA
187input-enable - enable input on pin (no effect on output)
188input-disable - disable input on pin (no effect on output)
189input-schmitt-enable - enable schmitt-trigger mode
190input-schmitt-disable - disable schmitt-trigger mode
191input-debounce - debounce mode with debound time X
192power-source - select between different power supplies
193low-power-enable - enable low power mode
194low-power-disable - disable low power mode
195output-low - set the pin to output mode with low level
196output-high - set the pin to output mode with high level
197slew-rate - set the slew rate
198
199For example:
200
201state_0_node_a {
202 cts_rxd {
203 pins = "GPIO0_AJ5", "GPIO2_AH4"; /* CTS+RXD */
204 bias-pull-up;
205 };
206};
207state_1_node_a {
208 rts_txd {
209 pins = "GPIO1_AJ3", "GPIO3_AH3"; /* RTS+TXD */
210 output-high;
211 };
212};
213state_2_node_a {
214 foo {
215 group = "foo-group";
216 bias-pull-up;
217 };
218};
219
220Some of the generic properties take arguments. For those that do, the
221arguments 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
235More in-depth documentation on these parameters can be found in
236<include/linux/pinctrl/pinconf-generic.h>