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
9legacy.rst (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, PullUp, 0, 0, IoRestrictionOutputOnly,
75				"\\_SB.GPI0", 0, ResourceConsumer) { 15 } // red
76			GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly,
77				"\\_SB.GPI0", 0, ResourceConsumer) { 16 } // green
78			GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly,
79				"\\_SB.GPI0", 0, ResourceConsumer) { 17 } // blue
80			GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionOutputOnly,
81				"\\_SB.GPI0", 0, ResourceConsumer) { 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 () { "power-gpios", Package () { ^FOO, 3, 0, 0 } },
96			}
97		})
98	}
99
100For more information about the ACPI GPIO bindings see
101Documentation/firmware-guide/acpi/gpio-properties.rst.
102
103Platform Data
104-------------
105Finally, GPIOs can be bound to devices and functions using platform data. Board
106files that desire to do so need to include the following header::
107
108	#include <linux/gpio/machine.h>
109
110GPIOs are mapped by the means of tables of lookups, containing instances of the
111gpiod_lookup structure. Two macros are defined to help declaring such mappings::
112
113	GPIO_LOOKUP(key, chip_hwnum, con_id, flags)
114	GPIO_LOOKUP_IDX(key, chip_hwnum, con_id, idx, flags)
115
116where
117
118  - key is either the label of the gpiod_chip instance providing the GPIO, or
119    the GPIO line name
120  - chip_hwnum is the hardware number of the GPIO within the chip, or U16_MAX
121    to indicate that key is a GPIO line name
122  - con_id is the name of the GPIO function from the device point of view. It
123	can be NULL, in which case it will match any function.
124  - idx is the index of the GPIO within the function.
125  - flags is defined to specify the following properties:
126	* GPIO_ACTIVE_HIGH	- GPIO line is active high
127	* GPIO_ACTIVE_LOW	- GPIO line is active low
128	* GPIO_OPEN_DRAIN	- GPIO line is set up as open drain
129	* GPIO_OPEN_SOURCE	- GPIO line is set up as open source
130	* GPIO_PERSISTENT	- GPIO line is persistent during
131				  suspend/resume and maintains its value
132	* GPIO_TRANSITORY	- GPIO line is transitory and may loose its
133				  electrical state during suspend/resume
134
135In the future, these flags might be extended to support more properties.
136
137Note that:
138  1. GPIO line names are not guaranteed to be globally unique, so the first
139     match found will be used.
140  2. GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.
141
142A lookup table can then be defined as follows, with an empty entry defining its
143end. The 'dev_id' field of the table is the identifier of the device that will
144make use of these GPIOs. It can be NULL, in which case it will be matched for
145calls to gpiod_get() with a NULL device.
146
147.. code-block:: c
148
149        struct gpiod_lookup_table gpios_table = {
150                .dev_id = "foo.0",
151                .table = {
152                        GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH),
153                        GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH),
154                        GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH),
155                        GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW),
156                        { },
157                },
158        };
159
160And the table can be added by the board code as follows::
161
162	gpiod_add_lookup_table(&gpios_table);
163
164The driver controlling "foo.0" will then be able to obtain its GPIOs as follows::
165
166	struct gpio_desc *red, *green, *blue, *power;
167
168	red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
169	green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
170	blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
171
172	power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
173
174Since the "led" GPIOs are mapped as active-high, this example will switch their
175signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped
176as active-low, its actual signal will be 0 after this code. Contrary to the
177legacy integer GPIO interface, the active-low property is handled during
178mapping and is thus transparent to GPIO consumers.
179
180A set of functions such as gpiod_set_value() is available to work with
181the new descriptor-oriented interface.
182
183Boards using platform data can also hog GPIO lines by defining GPIO hog tables.
184
185.. code-block:: c
186
187        struct gpiod_hog gpio_hog_table[] = {
188                GPIO_HOG("gpio.0", 10, "foo", GPIO_ACTIVE_LOW, GPIOD_OUT_HIGH),
189                { }
190        };
191
192And the table can be added to the board code as follows::
193
194        gpiod_add_hogs(gpio_hog_table);
195
196The line will be hogged as soon as the gpiochip is created or - in case the
197chip was created earlier - when the hog table is registered.
198
199Arrays of pins
200--------------
201In addition to requesting pins belonging to a function one by one, a device may
202also request an array of pins assigned to the function.  The way those pins are
203mapped to the device determines if the array qualifies for fast bitmap
204processing.  If yes, a bitmap is passed over get/set array functions directly
205between a caller and a respective .get/set_multiple() callback of a GPIO chip.
206
207In order to qualify for fast bitmap processing, the array must meet the
208following requirements:
209
210- pin hardware number of array member 0 must also be 0,
211- pin hardware numbers of consecutive array members which belong to the same
212  chip as member 0 does must also match their array indexes.
213
214Otherwise fast bitmap processing path is not used in order to avoid consecutive
215pins which belong to the same chip but are not in hardware order being processed
216separately.
217
218If the array applies for fast bitmap processing path, pins which belong to
219different chips than member 0 does, as well as those with indexes different from
220their hardware pin numbers, are excluded from the fast path, both input and
221output.  Moreover, open drain and open source pins are excluded from fast bitmap
222output processing.
223