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 | ||
41 | Each client device's own binding determines the set of states the 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. | |
7db9af4b | 129 | |
bcd0c8c2 | 130 | == Generic pin configuration node content == |
7db9af4b | 131 | |
bcd0c8c2 SW |
132 | Many data items that are represented in a pin configuration node are common |
133 | and generic. Pin control bindings should use the properties defined below | |
134 | where they are applicable; not all of these properties are relevant or useful | |
135 | for all hardware or binding structures. Each individual binding document | |
136 | should state which of these generic properties, if any, are used, and the | |
137 | structure of the DT nodes that contain these properties. | |
7db9af4b | 138 | |
bcd0c8c2 | 139 | Supported generic properties are: |
7db9af4b | 140 | |
87311d04 SW |
141 | pins - the list of pins that properties in the node |
142 | apply to | |
143 | function - the mux function to select | |
7db9af4b HS |
144 | bias-disable - disable any pin bias |
145 | bias-high-impedance - high impedance mode ("third-state", "floating") | |
146 | bias-bus-hold - latch weakly | |
147 | bias-pull-up - pull up the pin | |
148 | bias-pull-down - pull down the pin | |
149 | bias-pull-pin-default - use pin-default pull state | |
150 | drive-push-pull - drive actively high and low | |
151 | drive-open-drain - drive with open drain | |
152 | drive-open-source - drive with open source | |
153 | drive-strength - sink or source at most X mA | |
154 | input-schmitt-enable - enable schmitt-trigger mode | |
155 | input-schmitt-disable - disable schmitt-trigger mode | |
7db9af4b | 156 | input-debounce - debounce mode with debound time X |
9ee1f7d2 HS |
157 | low-power-enable - enable low power mode |
158 | low-power-disable - disable low power mode | |
7db9af4b HS |
159 | output-low - set the pin to output mode with low level |
160 | output-high - set the pin to output mode with high level | |
161 | ||
bcd0c8c2 SW |
162 | Some of the generic properties take arguments. For those that do, the |
163 | arguments are described below. | |
9ee1f7d2 | 164 | |
87311d04 SW |
165 | - pins takes a list of pin names or IDs as a required argument. The specific |
166 | binding for the hardware defines: | |
167 | - Whether the entries are integers or strings, and their meaning. | |
168 | ||
169 | - function takes a list of function names/IDs as a required argument. The | |
170 | specific binding for the hardware defines: | |
171 | - Whether the entries are integers or strings, and their meaning. | |
172 | - Whether only a single entry is allowed (which is applied to all entries | |
173 | in the pins property), or whether there may alternatively be one entry per | |
174 | entry in the pins property, in which case the list lengths must match, and | |
175 | for each list index i, the function at list index i is applied to the pin | |
176 | at list index i. | |
177 | ||
70637a6d HS |
178 | - bias-pull-up, -down and -pin-default take as optional argument on hardware |
179 | supporting it the pull strength in Ohm. bias-disable will disable the pull. | |
9ee1f7d2 HS |
180 | |
181 | - drive-strength takes as argument the target strength in mA. | |
182 | ||
256aeb64 HS |
183 | - input-debounce takes the debounce time in usec as argument |
184 | or 0 to disable debouncing | |
9ee1f7d2 | 185 | |
7db9af4b HS |
186 | More in-depth documentation on these parameters can be found in |
187 | <include/linux/pinctrl/pinconfig-generic.h> |