About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / devicetree / bindings / pinctrl / pinctrl-bindings.txt




Custom Search

Based on kernel version 4.13.3. Page generated on 2017-09-23 13:55 EST.

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 that 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	Required properties: See the pin controller driver specific documentation
101	
102	Optional properties:
103	#pinctrl-cells:	Number of pin control cells in addition to the index within the
104			pin controller device instance
105	
106	Pin controller devices should contain the pin configuration nodes that client
107	devices reference.
108	
109	For example:
110	
111		pincontroller {
112			... /* Standard DT properties for the device itself elided */
113	
114			state_0_node_a {
115				...
116			};
117			state_1_node_a {
118				...
119			};
120			state_1_node_b {
121				...
122			};
123		}
124	
125	The contents of each of those pin configuration child nodes is defined
126	entirely by the binding for the individual pin controller device. There
127	exists no common standard for this content. The pinctrl framework only
128	provides generic helper bindings that the pin controller driver can use.
129	
130	The pin configuration nodes need not be direct children of the pin controller
131	device; they may be grandchildren, for example. Whether this is legal, and
132	whether there is any interaction between the child and intermediate parent
133	nodes, is again defined entirely by the binding for the individual pin
134	controller device.
135	
136	== Generic pin multiplexing node content ==
137	
138	pin multiplexing nodes:
139	
140	function		- the mux function to select
141	groups			- the list of groups to select with this function
142				  (either this or "pins" must be specified)
143	pins			- the list of pins to select with this function (either
144				  this or "groups" must be specified)
145	
146	Example:
147	
148	state_0_node_a {
149		uart0 {
150			function = "uart0";
151			groups = "u0rxtx", "u0rtscts";
152		};
153	};
154	state_1_node_a {
155		spi0 {
156			function = "spi0";
157			groups = "spi0pins";
158		};
159	};
160	state_2_node_a {
161		function = "i2c0";
162		pins = "mfio29", "mfio30";
163	};
164	
165	Optionally an alternative binding can be used if more suitable depending on the
166	pin controller hardware. For hardware where there is a large number of identical
167	pin controller instances, naming each pin and function can easily become
168	unmaintainable. This is especially the case if the same controller is used for
169	different pins and functions depending on the SoC revision and packaging.
170	
171	For cases like this, the pin controller driver may use pinctrl-pin-array helper
172	binding with a hardware based index and a number of pin configuration values:
173	
174	pincontroller {
175		... /* Standard DT properties for the device itself elided */
176		#pinctrl-cells = <2>;
177	
178		state_0_node_a {
179			pinctrl-pin-array = <
180				0 A_DELAY_PS(0) G_DELAY_PS(120)
181				4 A_DELAY_PS(0) G_DELAY_PS(360)
182				...
183			>;
184		};
185		...
186	};
187	
188	Above #pinctrl-cells specifies the number of value cells in addition to the
189	index of the registers. This is similar to the interrupts-extended binding with
190	one exception. There is no need to specify the phandle for each entry as that
191	is already known as the defined pins are always children of the pin controller
192	node. Further having the phandle pointing to another pin controller would not
193	currently work as the pinctrl framework uses named modes to group pins for each
194	pin control device.
195	
196	The index for pinctrl-pin-array must relate to the hardware for the pinctrl
197	registers, and must not be a virtual index of pin instances. The reason for
198	this is to avoid mapping of the index in the dts files and the pin controller
199	driver as it can change.
200	
201	For hardware where pin multiplexing configurations have to be specified for
202	each single pin the number of required sub-nodes containing "pin" and
203	"function" properties can quickly escalate and become hard to write and
204	maintain.
205	
206	For cases like this, the pin controller driver may use the pinmux helper
207	property, where the pin identifier is provided with mux configuration settings
208	in a pinmux group. A pinmux group consists of the pin identifier and mux
209	settings represented as a single integer or an array of integers.
210	
211	The pinmux property accepts an array of pinmux groups, each of them describing
212	a single pin multiplexing configuration.
213	
214	pincontroller {
215		state_0_node_a {
216			pinmux = <PINMUX_GROUP>, <PINMUX_GROUP>, ...;
217		};
218	};
219	
220	Each individual pin controller driver bindings documentation shall specify
221	how pin IDs and pin multiplexing configuration are defined and assembled
222	together in a pinmux group.
223	
224	== Generic pin configuration node content ==
225	
226	Many data items that are represented in a pin configuration node are common
227	and generic. Pin control bindings should use the properties defined below
228	where they are applicable; not all of these properties are relevant or useful
229	for all hardware or binding structures. Each individual binding document
230	should state which of these generic properties, if any, are used, and the
231	structure of the DT nodes that contain these properties.
232	
233	Supported generic properties are:
234	
235	pins			- the list of pins that properties in the node
236				  apply to (either this, "group" or "pinmux" has to be
237				  specified)
238	group			- the group to apply the properties to, if the driver
239				  supports configuration of whole groups rather than
240				  individual pins (either this, "pins" or "pinmux" has
241				  to be specified)
242	pinmux			- the list of numeric pin ids and their mux settings
243				  that properties in the node apply to (either this,
244				  "pins" or "groups" have to be specified)
245	bias-disable		- disable any pin bias
246	bias-high-impedance	- high impedance mode ("third-state", "floating")
247	bias-bus-hold		- latch weakly
248	bias-pull-up		- pull up the pin
249	bias-pull-down		- pull down the pin
250	bias-pull-pin-default	- use pin-default pull state
251	drive-push-pull		- drive actively high and low
252	drive-open-drain	- drive with open drain
253	drive-open-source	- drive with open source
254	drive-strength		- sink or source at most X mA
255	input-enable		- enable input on pin (no effect on output, such as
256				  enabling an input buffer)
257	input-disable		- disable input on pin (no effect on output, such as
258				  disabling an input buffer)
259	input-schmitt-enable	- enable schmitt-trigger mode
260	input-schmitt-disable	- disable schmitt-trigger mode
261	input-debounce		- debounce mode with debound time X
262	power-source		- select between different power supplies
263	low-power-enable	- enable low power mode
264	low-power-disable	- disable low power mode
265	output-disable		- disable output on a pin (such as disable an output
266				  buffer)
267	output-enable		- enable output on a pin without actively driving it
268				  (such as enabling an output buffer)
269	output-low		- set the pin to output mode with low level
270	output-high		- set the pin to output mode with high level
271	slew-rate		- set the slew rate
272	
273	For example:
274	
275	state_0_node_a {
276		cts_rxd {
277			pins = "GPIO0_AJ5", "GPIO2_AH4"; /* CTS+RXD */
278			bias-pull-up;
279		};
280	};
281	state_1_node_a {
282		rts_txd {
283			pins = "GPIO1_AJ3", "GPIO3_AH3"; /* RTS+TXD */
284			output-high;
285		};
286	};
287	state_2_node_a {
288		foo {
289			group = "foo-group";
290			bias-pull-up;
291		};
292	};
293	state_3_node_a {
294		mux {
295			pinmux = <GPIOx_PINm_MUXn>, <GPIOx_PINj_MUXk)>;
296			input-enable;
297		};
298	};
299	
300	Some of the generic properties take arguments. For those that do, the
301	arguments are described below.
302	
303	- pins takes a list of pin names or IDs as a required argument. The specific
304	  binding for the hardware defines:
305	  - Whether the entries are integers or strings, and their meaning.
306	
307	- pinmux takes a list of pin IDs and mux settings as required argument. The
308	  specific bindings for the hardware defines:
309	  - How pin IDs and mux settings are defined and assembled together in a single
310	    integer or an array of integers.
311	
312	- bias-pull-up, -down and -pin-default take as optional argument on hardware
313	  supporting it the pull strength in Ohm. bias-disable will disable the pull.
314	
315	- drive-strength takes as argument the target strength in mA.
316	
317	- input-debounce takes the debounce time in usec as argument
318	  or 0 to disable debouncing
319	
320	More in-depth documentation on these parameters can be found in
321	<include/linux/pinctrl/pinconf-generic.h>
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.