About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

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




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:01 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 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.
129	
130	== Generic pin configuration node content ==
131	
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.
138	
139	Supported generic properties are:
140	
141	pins			- the list of pins that properties in the node
142				  apply to
143	function		- the mux function to select
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-enable		- enable input on pin (no effect on output)
155	input-disable		- disable input on pin (no effect on output)
156	input-schmitt-enable	- enable schmitt-trigger mode
157	input-schmitt-disable	- disable schmitt-trigger mode
158	input-debounce		- debounce mode with debound time X
159	low-power-enable	- enable low power mode
160	low-power-disable	- disable low power mode
161	output-low		- set the pin to output mode with low level
162	output-high		- set the pin to output mode with high level
163	slew-rate		- set the slew rate
164	
165	Some of the generic properties take arguments. For those that do, the
166	arguments are described below.
167	
168	- pins takes a list of pin names or IDs as a required argument. The specific
169	  binding for the hardware defines:
170	  - Whether the entries are integers or strings, and their meaning.
171	
172	- function takes a list of function names/IDs as a required argument. The
173	  specific binding for the hardware defines:
174	  - Whether the entries are integers or strings, and their meaning.
175	  - Whether only a single entry is allowed (which is applied to all entries
176	    in the pins property), or whether there may alternatively be one entry per
177	    entry in the pins property, in which case the list lengths must match, and
178	    for each list index i, the function at list index i is applied to the pin
179	    at list index i.
180	
181	- bias-pull-up, -down and -pin-default take as optional argument on hardware
182	  supporting it the pull strength in Ohm. bias-disable will disable the pull.
183	
184	- drive-strength takes as argument the target strength in mA.
185	
186	- input-debounce takes the debounce time in usec as argument
187	  or 0 to disable debouncing
188	
189	More in-depth documentation on these parameters can be found in
190	<include/linux/pinctrl/pinconfig-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.