driver-api/gpio/board.rst

2 GPIO Mappings
7 Note that it only applies to the new descriptor-based interface. For a
8 description of the deprecated integer-based GPIO interface please refer to
9 gpio-legacy.txt (actually, there is no real mapping possible with the old
11 corresponding GPIO).
13 All platforms can enable the GPIO library, but if the platform strictly
14 requires GPIO functionality to be present, it needs to select GPIOLIB from its
20 -----------
22 exact way to do it depends on the GPIO controller providing the GPIOs, see the
25 GPIOs 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
32 		led-gpios = <&gpio 15 GPIO_ACTIVE_HIGH>, /* red */
33 			    <&gpio 16 GPIO_ACTIVE_HIGH>, /* green */
34 			    <&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */
36 		power-gpios = <&gpio 1 GPIO_ACTIVE_LOW>;
39 Properties named <function>-gpio are also considered valid and old bindings use
44 "led" function, and GPIO 1 as the "power" GPIO::
54 The led GPIOs will be active high, while the power GPIO will be active low (i.e.
58 the <function>-prefix of the GPIO suffixes ("gpios" or "gpio", automatically
60 "led-gpios" example, use the prefix without the "-" as con_id parameter: "led".
62 Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio")
64 (``snprintf(... "%s-%s", con_id, gpio_suffixes[]``).
67 ----
68 ACPI also supports function names for GPIOs in a similar fashion to DT.
85 			ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
88 					"led-gpios",
96 					"power-gpios",
103 For more information about the ACPI GPIO bindings see
104 Documentation/firmware-guide/acpi/gpio-properties.rst.
107 -------------
111 	#include <linux/gpio/machine.h>
121   - key is either the label of the gpiod_chip instance providing the GPIO, or
122     the GPIO line name
123   - chip_hwnum is the hardware number of the GPIO within the chip, or U16_MAX
124     to indicate that key is a GPIO line name
125   - con_id is the name of the GPIO function from the device point of view. It
127   - idx is the index of the GPIO within the function.
128   - flags is defined to specify the following properties:
129 	* GPIO_ACTIVE_HIGH	- GPIO line is active high
130 	* GPIO_ACTIVE_LOW	- GPIO line is active low
131 	* GPIO_OPEN_DRAIN	- GPIO line is set up as open drain
132 	* GPIO_OPEN_SOURCE	- GPIO line is set up as open source
133 	* GPIO_PERSISTENT	- GPIO line is persistent during
135 	* GPIO_TRANSITORY	- GPIO line is transitory and may loose its
141   1. GPIO line names are not guaranteed to be globally unique, so the first
143   2. GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.
145 A lookup table can then be defined as follows, with an empty entry defining its
148 calls to gpiod_get() with a NULL device.
150 .. code-block:: c
155                         GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH),
156                         GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH),
157                         GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH),
158                         GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW),
177 Since the "led" GPIOs are mapped as active-high, this example will switch their
178 signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped
179 as active-low, its actual signal will be 0 after this code. Contrary to the
180 legacy integer GPIO interface, the active-low property is handled during
181 mapping and is thus transparent to GPIO consumers.
183 A set of functions such as gpiod_set_value() is available to work with
184 the new descriptor-oriented interface.
186 Boards using platform data can also hog GPIO lines by defining GPIO hog tables.
188 .. code-block:: c
191                 GPIO_HOG("gpio.0", 10, "foo", GPIO_ACTIVE_LOW, GPIOD_OUT_HIGH),
199 The line will be hogged as soon as the gpiochip is created or - in case the
200 chip was created earlier - when the hog table is registered.
203 --------------
204 In addition to requesting pins belonging to a function one by one, a device may
207 processing.  If yes, a bitmap is passed over get/set array functions directly
208 between a caller and a respective .get/set_multiple() callback of a GPIO chip.
213 - pin hardware number of array member 0 must also be 0,
214 - pin hardware numbers of consecutive array members which belong to the same