1=============
2GPIO Mappings
3=============
4
5This document explains how GPIOs can be assigned to given devices and functions.
6
7Note that it only applies to the new descriptor-based interface. For a
8description of the deprecated integer-based GPIO interface please refer to
9gpio-legacy.txt (actually, there is no real mapping possible with the old
10interface; you just fetch an integer from somewhere and request the
11corresponding GPIO).
12
13All platforms can enable the GPIO library, but if the platform strictly
14requires GPIO functionality to be present, it needs to select GPIOLIB from its
15Kconfig. Then, how GPIOs are mapped depends on what the platform uses to
16describe its hardware layout. Currently, mappings can be defined through device
17tree, ACPI, and platform data.
18
19Device Tree
20-----------
21GPIOs can easily be mapped to devices and functions in the device tree. The
22exact way to do it depends on the GPIO controller providing the GPIOs, see the
23device tree bindings for your controller.
24
25GPIOs mappings are defined in the consumer device's node, in a property named
26<function>-gpios, where <function> is the function the driver will request
27through gpiod_get(). For example::
28
29	foo_device {
30		compatible = "acme,foo";
31		...
32		led-gpios = <&gpio 15 GPIO_ACTIVE_HIGH>, /* red */
33			    <&gpio 16 GPIO_ACTIVE_HIGH>, /* green */
34			    <&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */
35
36		power-gpios = <&gpio 1 GPIO_ACTIVE_LOW>;
37	};
38
39Properties named <function>-gpio are also considered valid and old bindings use
40it but are only supported for compatibility reasons and should not be used for
41newer bindings since it has been deprecated.
42
43This property will make GPIOs 15, 16 and 17 available to the driver under the
44"led" function, and GPIO 1 as the "power" GPIO::
45
46	struct gpio_desc *red, *green, *blue, *power;
47
48	red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
49	green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
50	blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
51
52	power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
53
54The led GPIOs will be active high, while the power GPIO will be active low (i.e.
55gpiod_is_active_low(power) will be true).
56
57The second parameter of the gpiod_get() functions, the con_id string, has to be
58the <function>-prefix of the GPIO suffixes ("gpios" or "gpio", automatically
59looked up by the gpiod functions internally) used in the device tree. With above
60"led-gpios" example, use the prefix without the "-" as con_id parameter: "led".
61
62Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio")
63with the string passed in con_id to get the resulting string
64(``snprintf(... "%s-%s", con_id, gpio_suffixes[]``).
65
66ACPI
67----
68ACPI also supports function names for GPIOs in a similar fashion to DT.
69The above DT example can be converted to an equivalent ACPI description
70with the help of _DSD (Device Specific Data), introduced in ACPI 5.1::
71
72	Device (FOO) {
73		Name (_CRS, ResourceTemplate () {
74			GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
75				"\\_SB.GPI0") {15} // red
76			GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
77				"\\_SB.GPI0") {16} // green
78			GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
79				"\\_SB.GPI0") {17} // blue
80			GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
81				"\\_SB.GPI0") {1} // power
82		})
83
84		Name (_DSD, Package () {
85			ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
86			Package () {
87				Package () {
88					"led-gpios",
89					Package () {
90						^FOO, 0, 0, 1,
91						^FOO, 1, 0, 1,
92						^FOO, 2, 0, 1,
93					}
94				},
95				Package () {
96					"power-gpios",
97					Package () {^FOO, 3, 0, 0},
98				},
99			}
100		})
101	}
102
103For more information about the ACPI GPIO bindings see
104Documentation/firmware-guide/acpi/gpio-properties.rst.
105
106Platform Data
107-------------
108Finally, GPIOs can be bound to devices and functions using platform data. Board
109files that desire to do so need to include the following header::
110
111	#include <linux/gpio/machine.h>
112
113GPIOs are mapped by the means of tables of lookups, containing instances of the
114gpiod_lookup structure. Two macros are defined to help declaring such mappings::
115
116	GPIO_LOOKUP(chip_label, chip_hwnum, con_id, flags)
117	GPIO_LOOKUP_IDX(chip_label, chip_hwnum, con_id, idx, flags)
118
119where
120
121  - chip_label is the label of the gpiod_chip instance providing the GPIO
122  - chip_hwnum is the hardware number of the GPIO within the chip
123  - con_id is the name of the GPIO function from the device point of view. It
124	can be NULL, in which case it will match any function.
125  - idx is the index of the GPIO within the function.
126  - flags is defined to specify the following properties:
127	* GPIO_ACTIVE_HIGH	- GPIO line is active high
128	* GPIO_ACTIVE_LOW	- GPIO line is active low
129	* GPIO_OPEN_DRAIN	- GPIO line is set up as open drain
130	* GPIO_OPEN_SOURCE	- GPIO line is set up as open source
131	* GPIO_PERSISTENT	- GPIO line is persistent during
132				  suspend/resume and maintains its value
133	* GPIO_TRANSITORY	- GPIO line is transitory and may loose its
134				  electrical state during suspend/resume
135
136In the future, these flags might be extended to support more properties.
137
138Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.
139
140A lookup table can then be defined as follows, with an empty entry defining its
141end. The 'dev_id' field of the table is the identifier of the device that will
142make use of these GPIOs. It can be NULL, in which case it will be matched for
143calls to gpiod_get() with a NULL device.
144
145.. code-block:: c
146
147        struct gpiod_lookup_table gpios_table = {
148                .dev_id = "foo.0",
149                .table = {
150                        GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH),
151                        GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH),
152                        GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH),
153                        GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW),
154                        { },
155                },
156        };
157
158And the table can be added by the board code as follows::
159
160	gpiod_add_lookup_table(&gpios_table);
161
162The driver controlling "foo.0" will then be able to obtain its GPIOs as follows::
163
164	struct gpio_desc *red, *green, *blue, *power;
165
166	red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
167	green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
168	blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
169
170	power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
171
172Since the "led" GPIOs are mapped as active-high, this example will switch their
173signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped
174as active-low, its actual signal will be 0 after this code. Contrary to the
175legacy integer GPIO interface, the active-low property is handled during
176mapping and is thus transparent to GPIO consumers.
177
178A set of functions such as gpiod_set_value() is available to work with
179the new descriptor-oriented interface.
180
181Boards using platform data can also hog GPIO lines by defining GPIO hog tables.
182
183.. code-block:: c
184
185        struct gpiod_hog gpio_hog_table[] = {
186                GPIO_HOG("gpio.0", 10, "foo", GPIO_ACTIVE_LOW, GPIOD_OUT_HIGH),
187                { }
188        };
189
190And the table can be added to the board code as follows::
191
192        gpiod_add_hogs(gpio_hog_table);
193
194The line will be hogged as soon as the gpiochip is created or - in case the
195chip was created earlier - when the hog table is registered.
196
197Arrays of pins
198--------------
199In addition to requesting pins belonging to a function one by one, a device may
200also request an array of pins assigned to the function.  The way those pins are
201mapped to the device determines if the array qualifies for fast bitmap
202processing.  If yes, a bitmap is passed over get/set array functions directly
203between a caller and a respective .get/set_multiple() callback of a GPIO chip.
204
205In order to qualify for fast bitmap processing, the array must meet the
206following requirements:
207
208- pin hardware number of array member 0 must also be 0,
209- pin hardware numbers of consecutive array members which belong to the same
210  chip as member 0 does must also match their array indexes.
211
212Otherwise fast bitmap processing path is not used in order to avoid consecutive
213pins which belong to the same chip but are not in hardware order being processed
214separately.
215
216If the array applies for fast bitmap processing path, pins which belong to
217different chips than member 0 does, as well as those with indexes different from
218their hardware pin numbers, are excluded from the fast path, both input and
219output.  Moreover, open drain and open source pins are excluded from fast bitmap
220output processing.
221