Commit | Line | Data |
---|---|---|
7a865277 SW |
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 | ||
f5efed80 | 41 | Each client device's own binding determines the set of states that must be |
7a865277 SW |
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. | |
7db9af4b | 129 | |
90d09938 LW |
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 | |
cec65650 AB |
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) | |
90d09938 LW |
139 | |
140 | Example: | |
141 | ||
142 | state_0_node_a { | |
5757bfe5 BS |
143 | uart0 { |
144 | function = "uart0"; | |
145 | groups = "u0rxtx", "u0rtscts"; | |
146 | }; | |
90d09938 LW |
147 | }; |
148 | state_1_node_a { | |
5757bfe5 BS |
149 | spi0 { |
150 | function = "spi0"; | |
151 | groups = "spi0pins"; | |
152 | }; | |
90d09938 | 153 | }; |
cec65650 AB |
154 | state_2_node_a { |
155 | function = "i2c0"; | |
156 | pins = "mfio29", "mfio30"; | |
157 | }; | |
90d09938 | 158 | |
bcd0c8c2 | 159 | == Generic pin configuration node content == |
7db9af4b | 160 | |
bcd0c8c2 SW |
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. | |
7db9af4b | 167 | |
bcd0c8c2 | 168 | Supported generic properties are: |
7db9af4b | 169 | |
87311d04 | 170 | pins - the list of pins that properties in the node |
2cdef8f4 LW |
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) | |
7db9af4b HS |
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 | |
8ba3f4d0 SY |
187 | input-enable - enable input on pin (no effect on output) |
188 | input-disable - disable input on pin (no effect on output) | |
7db9af4b HS |
189 | input-schmitt-enable - enable schmitt-trigger mode |
190 | input-schmitt-disable - disable schmitt-trigger mode | |
7db9af4b | 191 | input-debounce - debounce mode with debound time X |
ca6c5518 | 192 | power-source - select between different power supplies |
9ee1f7d2 HS |
193 | low-power-enable - enable low power mode |
194 | low-power-disable - disable low power mode | |
7db9af4b HS |
195 | output-low - set the pin to output mode with low level |
196 | output-high - set the pin to output mode with high level | |
8ba3f4d0 | 197 | slew-rate - set the slew rate |
7db9af4b | 198 | |
90d09938 LW |
199 | For example: |
200 | ||
201 | state_0_node_a { | |
5757bfe5 BS |
202 | cts_rxd { |
203 | pins = "GPIO0_AJ5", "GPIO2_AH4"; /* CTS+RXD */ | |
204 | bias-pull-up; | |
205 | }; | |
90d09938 LW |
206 | }; |
207 | state_1_node_a { | |
5757bfe5 BS |
208 | rts_txd { |
209 | pins = "GPIO1_AJ3", "GPIO3_AH3"; /* RTS+TXD */ | |
210 | output-high; | |
211 | }; | |
90d09938 | 212 | }; |
2cdef8f4 | 213 | state_2_node_a { |
5757bfe5 BS |
214 | foo { |
215 | group = "foo-group"; | |
216 | bias-pull-up; | |
217 | }; | |
2cdef8f4 | 218 | }; |
90d09938 | 219 | |
bcd0c8c2 SW |
220 | Some of the generic properties take arguments. For those that do, the |
221 | arguments are described below. | |
9ee1f7d2 | 222 | |
87311d04 SW |
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 | ||
70637a6d HS |
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. | |
9ee1f7d2 HS |
229 | |
230 | - drive-strength takes as argument the target strength in mA. | |
231 | ||
256aeb64 HS |
232 | - input-debounce takes the debounce time in usec as argument |
233 | or 0 to disable debouncing | |
9ee1f7d2 | 234 | |
7db9af4b | 235 | More in-depth documentation on these parameters can be found in |
ee76a9ab | 236 | <include/linux/pinctrl/pinconf-generic.h> |