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. |