About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / devicetree / bindings / gpio




Custom Search

Based on kernel version 3.15.4. Page generated on 2014-07-07 09:00 EST.

1	Specifying GPIO information for devices
2	============================================
3	
4	1) gpios property
5	-----------------
6	
7	Nodes that makes use of GPIOs should specify them using one or more
8	properties, each containing a 'gpio-list':
9	
10		gpio-list ::= <single-gpio> [gpio-list]
11		single-gpio ::= <gpio-phandle> <gpio-specifier>
12		gpio-phandle : phandle to gpio controller node
13		gpio-specifier : Array of #gpio-cells specifying specific gpio
14				 (controller specific)
15	
16	GPIO properties should be named "[<name>-]gpios". The exact
17	meaning of each gpios property must be documented in the device tree
18	binding for each device.
19	
20	For example, the following could be used to describe GPIO pins used
21	as chip select lines; with chip selects 0, 1 and 3 populated, and chip
22	select 2 left empty:
23	
24		gpio1: gpio1 {
25			gpio-controller
26			 #gpio-cells = <2>;
27		};
28		gpio2: gpio2 {
29			gpio-controller
30			 #gpio-cells = <1>;
31		};
32		[...]
33		 chipsel-gpios = <&gpio1 12 0>,
34				 <&gpio1 13 0>,
35				 <0>, /* holes are permitted, means no GPIO 2 */
36				 <&gpio2 2>;
37	
38	Note that gpio-specifier length is controller dependent.  In the
39	above example, &gpio1 uses 2 cells to specify a gpio, while &gpio2
40	only uses one.
41	
42	gpio-specifier may encode: bank, pin position inside the bank,
43	whether pin is open-drain and whether pin is logically inverted.
44	Exact meaning of each specifier cell is controller specific, and must
45	be documented in the device tree binding for the device.
46	
47	Example of a node using GPIOs:
48	
49		node {
50			gpios = <&qe_pio_e 18 0>;
51		};
52	
53	In this example gpio-specifier is "18 0" and encodes GPIO pin number,
54	and GPIO flags as accepted by the "qe_pio_e" gpio-controller.
55	
56	1.1) GPIO specifier best practices
57	----------------------------------
58	
59	A gpio-specifier should contain a flag indicating the GPIO polarity; active-
60	high or active-low. If it does, the follow best practices should be followed:
61	
62	The gpio-specifier's polarity flag should represent the physical level at the
63	GPIO controller that achieves (or represents, for inputs) a logically asserted
64	value at the device. The exact definition of logically asserted should be
65	defined by the binding for the device. If the board inverts the signal between
66	the GPIO controller and the device, then the gpio-specifier will represent the
67	opposite physical level than the signal at the device's pin.
68	
69	When the device's signal polarity is configurable, the binding for the
70	device must either:
71	
72	a) Define a single static polarity for the signal, with the expectation that
73	any software using that binding would statically program the device to use
74	that signal polarity.
75	
76	The static choice of polarity may be either:
77	
78	a1) (Preferred) Dictated by a binding-specific DT property.
79	
80	or:
81	
82	a2) Defined statically by the DT binding itself.
83	
84	In particular, the polarity cannot be derived from the gpio-specifier, since
85	that would prevent the DT from separately representing the two orthogonal
86	concepts of configurable signal polarity in the device, and possible board-
87	level signal inversion.
88	
89	or:
90	
91	b) Pick a single option for device signal polarity, and document this choice
92	in the binding. The gpio-specifier should represent the polarity of the signal
93	(at the GPIO controller) assuming that the device is configured for this
94	particular signal polarity choice. If software chooses to program the device
95	to generate or receive a signal of the opposite polarity, software will be
96	responsible for correctly interpreting (inverting) the GPIO signal at the GPIO
97	controller.
98	
99	2) gpio-controller nodes
100	------------------------
101	
102	Every GPIO controller node must contain both an empty "gpio-controller"
103	property, and a #gpio-cells integer property, which indicates the number of
104	cells in a gpio-specifier.
105	
106	Example of two SOC GPIO banks defined as gpio-controller nodes:
107	
108		qe_pio_a: gpio-controller@1400 {
109			compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank";
110			reg = <0x1400 0x18>;
111			gpio-controller;
112			#gpio-cells = <2>;
113		};
114	
115		qe_pio_e: gpio-controller@1460 {
116			compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
117			reg = <0x1460 0x18>;
118			gpio-controller;
119			#gpio-cells = <2>;
120		};
121	
122	2.1) gpio- and pin-controller interaction
123	-----------------------------------------
124	
125	Some or all of the GPIOs provided by a GPIO controller may be routed to pins
126	on the package via a pin controller. This allows muxing those pins between
127	GPIO and other functions.
128	
129	It is useful to represent which GPIOs correspond to which pins on which pin
130	controllers. The gpio-ranges property described below represents this, and
131	contains information structures as follows:
132	
133		gpio-range-list ::= <single-gpio-range> [gpio-range-list]
134		single-gpio-range ::= <numeric-gpio-range> | <named-gpio-range>
135		numeric-gpio-range ::=
136				<pinctrl-phandle> <gpio-base> <pinctrl-base> <count>
137		named-gpio-range ::= <pinctrl-phandle> <gpio-base> '<0 0>'
138		gpio-phandle : phandle to pin controller node.
139		gpio-base : Base GPIO ID in the GPIO controller
140		pinctrl-base : Base pinctrl pin ID in the pin controller
141		count : The number of GPIOs/pins in this range
142	
143	The "pin controller node" mentioned above must conform to the bindings
144	described in ../pinctrl/pinctrl-bindings.txt.
145	
146	In case named gpio ranges are used (ranges with both <pinctrl-base> and
147	<count> set to 0), the property gpio-ranges-group-names contains one string
148	for every single-gpio-range in gpio-ranges:
149		gpiorange-names-list ::= <gpiorange-name> [gpiorange-names-list]
150		gpiorange-name : Name of the pingroup associated to the GPIO range in
151				the respective pin controller.
152	
153	Elements of gpiorange-names-list corresponding to numeric ranges contain
154	the empty string. Elements of gpiorange-names-list corresponding to named
155	ranges contain the name of a pin group defined in the respective pin
156	controller. The number of pins/GPIOs in the range is the number of pins in
157	that pin group.
158	
159	Previous versions of this binding required all pin controller nodes that
160	were referenced by any gpio-ranges property to contain a property named
161	#gpio-range-cells with value <3>. This requirement is now deprecated.
162	However, that property may still exist in older device trees for
163	compatibility reasons, and would still be required even in new device
164	trees that need to be compatible with older software.
165	
166	Example 1:
167	
168		qe_pio_e: gpio-controller@1460 {
169			#gpio-cells = <2>;
170			compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
171			reg = <0x1460 0x18>;
172			gpio-controller;
173			gpio-ranges = <&pinctrl1 0 20 10>, <&pinctrl2 10 50 20>;
174		};
175	
176	Here, a single GPIO controller has GPIOs 0..9 routed to pin controller
177	pinctrl1's pins 20..29, and GPIOs 10..19 routed to pin controller pinctrl2's
178	pins 50..59.
179	
180	Example 2:
181	
182		gpio_pio_i: gpio-controller@14B0 {
183			#gpio-cells = <2>;
184			compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
185			reg = <0x1480 0x18>;
186			gpio-controller;
187			gpio-ranges =			<&pinctrl1 0 20 10>,
188							<&pinctrl2 10 0 0>,
189							<&pinctrl1 15 0 10>,
190							<&pinctrl2 25 0 0>;
191			gpio-ranges-group-names =	"",
192							"foo",
193							"",
194							"bar";
195		};
196	
197	Here, three GPIO ranges are defined wrt. two pin controllers. pinctrl1 GPIO
198	ranges are defined using pin numbers whereas the GPIO ranges wrt. pinctrl2
199	are named "foo" and "bar".
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.