1== 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 ==
100Required properties: See the pin controller driver specific documentation
101
102Optional properties:
103#pinctrl-cells:	Number of pin control cells in addition to the index within the
104		pin controller device instance
105
106pinctrl-use-default: Boolean. Indicates that the OS can use the boot default
107		pin configuration. This allows using an OS that does not have a
108		driver for the pin controller. This property can be set either
109		globally for the pin controller or in child nodes for individual
110		pin group control.
111
112Pin controller devices should contain the pin configuration nodes that client
113devices reference.
114
115For example:
116
117	pincontroller {
118		... /* Standard DT properties for the device itself elided */
119
120		state_0_node_a {
121			...
122		};
123		state_1_node_a {
124			...
125		};
126		state_1_node_b {
127			...
128		};
129	}
130
131The contents of each of those pin configuration child nodes is defined
132entirely by the binding for the individual pin controller device. There
133exists no common standard for this content. The pinctrl framework only
134provides generic helper bindings that the pin controller driver can use.
135
136The pin configuration nodes need not be direct children of the pin controller
137device; they may be grandchildren, for example. Whether this is legal, and
138whether there is any interaction between the child and intermediate parent
139nodes, is again defined entirely by the binding for the individual pin
140controller device.
141
142== Generic pin multiplexing node content ==
143
144See pinmux-node.yaml
145
146== Generic pin configuration node content ==
147
148See pincfg-node.yaml
149