About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / gpio / board.txt




Custom Search

Based on kernel version 4.7.2. Page generated on 2016-08-22 22:46 EST.

1	GPIO Mappings
2	=============
3	
4	This document explains how GPIOs can be assigned to given devices and functions.
5	Note that it only applies to the new descriptor-based interface. For a
6	description of the deprecated integer-based GPIO interface please refer to
7	gpio-legacy.txt (actually, there is no real mapping possible with the old
8	interface; you just fetch an integer from somewhere and request the
9	corresponding GPIO.
10	
11	Platforms that make use of GPIOs must select ARCH_REQUIRE_GPIOLIB (if GPIO usage
12	is mandatory) or ARCH_WANT_OPTIONAL_GPIOLIB (if GPIO support can be omitted) in
13	their Kconfig. Then, how GPIOs are mapped depends on what the platform uses to
14	describe its hardware layout. Currently, mappings can be defined through device
15	tree, ACPI, and platform data.
16	
17	Device Tree
18	-----------
19	GPIOs can easily be mapped to devices and functions in the device tree. The
20	exact way to do it depends on the GPIO controller providing the GPIOs, see the
21	device tree bindings for your controller.
22	
23	GPIOs mappings are defined in the consumer device's node, in a property named
24	<function>-gpios, where <function> is the function the driver will request
25	through gpiod_get(). For example:
26	
27		foo_device {
28			compatible = "acme,foo";
29			...
30			led-gpios = <&gpio 15 GPIO_ACTIVE_HIGH>, /* red */
31				    <&gpio 16 GPIO_ACTIVE_HIGH>, /* green */
32				    <&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */
33	
34			power-gpios = <&gpio 1 GPIO_ACTIVE_LOW>;
35		};
36	
37	Properties named <function>-gpio are also considered valid and old bindings use
38	it but are only supported for compatibility reasons and should not be used for
39	newer bindings since it has been deprecated.
40	
41	This property will make GPIOs 15, 16 and 17 available to the driver under the
42	"led" function, and GPIO 1 as the "power" GPIO:
43	
44		struct gpio_desc *red, *green, *blue, *power;
45	
46		red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
47		green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
48		blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
49	
50		power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
51	
52	The led GPIOs will be active-high, while the power GPIO will be active-low (i.e.
53	gpiod_is_active_low(power) will be true).
54	
55	The second parameter of the gpiod_get() functions, the con_id string, has to be
56	the <function>-prefix of the GPIO suffixes ("gpios" or "gpio", automatically
57	looked up by the gpiod functions internally) used in the device tree. With above
58	"led-gpios" example, use the prefix without the "-" as con_id parameter: "led".
59	
60	Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio")
61	with the string passed in con_id to get the resulting string
62	(snprintf(... "%s-%s", con_id, gpio_suffixes[]).
63	
64	ACPI
65	----
66	ACPI also supports function names for GPIOs in a similar fashion to DT.
67	The above DT example can be converted to an equivalent ACPI description
68	with the help of _DSD (Device Specific Data), introduced in ACPI 5.1:
69	
70		Device (FOO) {
71			Name (_CRS, ResourceTemplate () {
72				GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
73					"\\_SB.GPI0") {15} // red
74				GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
75					"\\_SB.GPI0") {16} // green
76				GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
77					"\\_SB.GPI0") {17} // blue
78				GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
79					"\\_SB.GPI0") {1} // power
80			})
81	
82			Name (_DSD, Package () {
83				ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
84				Package () {
85					Package () {
86						"led-gpios",
87						Package () {
88							^FOO, 0, 0, 1,
89							^FOO, 1, 0, 1,
90							^FOO, 2, 0, 1,
91						}
92					},
93					Package () {
94						"power-gpios",
95						Package () {^FOO, 3, 0, 0},
96					},
97				}
98			})
99		}
100	
101	For more information about the ACPI GPIO bindings see
102	Documentation/acpi/gpio-properties.txt.
103	
104	Platform Data
105	-------------
106	Finally, GPIOs can be bound to devices and functions using platform data. Board
107	files that desire to do so need to include the following header:
108	
109		#include <linux/gpio/machine.h>
110	
111	GPIOs are mapped by the means of tables of lookups, containing instances of the
112	gpiod_lookup structure. Two macros are defined to help declaring such mappings:
113	
114		GPIO_LOOKUP(chip_label, chip_hwnum, con_id, flags)
115		GPIO_LOOKUP_IDX(chip_label, chip_hwnum, con_id, idx, flags)
116	
117	where
118	
119	  - chip_label is the label of the gpiod_chip instance providing the GPIO
120	  - chip_hwnum is the hardware number of the GPIO within the chip
121	  - con_id is the name of the GPIO function from the device point of view. It
122		can be NULL, in which case it will match any function.
123	  - idx is the index of the GPIO within the function.
124	  - flags is defined to specify the following properties:
125		* GPIOF_ACTIVE_LOW	- to configure the GPIO as active-low
126		* GPIOF_OPEN_DRAIN	- GPIO pin is open drain type.
127		* GPIOF_OPEN_SOURCE	- GPIO pin is open source type.
128	
129	In the future, these flags might be extended to support more properties.
130	
131	Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.
132	
133	A lookup table can then be defined as follows, with an empty entry defining its
134	end. The 'dev_id' field of the table is the identifier of the device that will
135	make use of these GPIOs. It can be NULL, in which case it will be matched for
136	calls to gpiod_get() with a NULL device.
137	
138	struct gpiod_lookup_table gpios_table = {
139		.dev_id = "foo.0",
140		.table = {
141			GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH),
142			GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH),
143			GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH),
144			GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW),
145			{ },
146		},
147	};
148	
149	And the table can be added by the board code as follows:
150	
151		gpiod_add_lookup_table(&gpios_table);
152	
153	The driver controlling "foo.0" will then be able to obtain its GPIOs as follows:
154	
155		struct gpio_desc *red, *green, *blue, *power;
156	
157		red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
158		green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
159		blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
160	
161		power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
162	
163	Since the "led" GPIOs are mapped as active-high, this example will switch their
164	signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped
165	as active-low, its actual signal will be 0 after this code. Contrary to the legacy
166	integer GPIO interface, the active-low property is handled during mapping and is
167	thus transparent to GPIO consumers.
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.