driver-api/gpio/board.rst

5 This document explains how GPIOs can be assigned to given devices and functions.
9 Kconfig. Then, how GPIOs are mapped depends on what the platform uses to
14 -----------
15 GPIOs can easily be mapped to devices and functions in the device tree. The
16 exact way to do it depends on the GPIO controller providing the GPIOs, see the
19 GPIOs mappings are defined in the consumer device's node, in a property named
20 <function>-gpios, where <function> is the function the driver will request
26 		led-gpios = <&gpio 15 GPIO_ACTIVE_HIGH>, /* red */
30 		power-gpios = <&gpio 1 GPIO_ACTIVE_LOW>;
33 Properties named <function>-gpio are also considered valid and old bindings use
37 This property will make GPIOs 15, 16 and 17 available to the driver under the
38 "led" function, and GPIO 1 as the "power" GPIO::
40 	struct gpio_desc *red, *green, *blue, *power;
46 	power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
48 The led GPIOs will be active high, while the power GPIO will be active low (i.e.
49 gpiod_is_active_low(power) will be true).
52 the <function>-prefix of the GPIO suffixes ("gpios" or "gpio", automatically
54 "led-gpios" example, use the prefix without the "-" as con_id parameter: "led".
56 Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio")
58 (``snprintf(... "%s-%s", con_id, gpio_suffixes[]``).
61 ----
62 ACPI also supports function names for GPIOs in a similar fashion to DT.
75 				"\\_SB.GPI0", 0, ResourceConsumer) { 1 } // power
79 			ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
82 					"led-gpios",
89 				Package () { "power-gpios", Package () { ^FOO, 3, 0, 0 } },
95 Documentation/firmware-guide/acpi/gpio-properties.rst.
98 -------------
99 Finally, GPIOs can be bound to devices and functions using platform data. Board
104 GPIOs are mapped by the means of tables of lookups, containing instances of the
112   - key is either the label of the gpiod_chip instance providing the GPIO, or
114   - chip_hwnum is the hardware number of the GPIO within the chip, or U16_MAX
116   - con_id is the name of the GPIO function from the device point of view. It
118   - idx is the index of the GPIO within the function.
119   - flags is defined to specify the following properties:
120 	* GPIO_ACTIVE_HIGH	- GPIO line is active high
121 	* GPIO_ACTIVE_LOW	- GPIO line is active low
122 	* GPIO_OPEN_DRAIN	- GPIO line is set up as open drain
123 	* GPIO_OPEN_SOURCE	- GPIO line is set up as open source
124 	* GPIO_PERSISTENT	- GPIO line is persistent during
126 	* GPIO_TRANSITORY	- GPIO line is transitory and may loose its
138 make use of these GPIOs. It can be NULL, in which case it will be matched for
141 .. code-block:: c
149                         GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW),
158 The driver controlling "foo.0" will then be able to obtain its GPIOs as follows::
160 	struct gpio_desc *red, *green, *blue, *power;
166 	power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
168 Since the "led" GPIOs are mapped as active-high, this example will switch their
169 signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped
170 as active-low, its actual signal will be 0 after this code. Contrary to the
171 legacy integer GPIO interface, the active-low property is handled during
175 the new descriptor-oriented interface.
179 .. code-block:: c
190 The line will be hogged as soon as the gpiochip is created or - in case the
191 chip was created earlier - when the hog table is registered.
194 --------------
204 - pin hardware number of array member 0 must also be 0,
205 - pin hardware numbers of consecutive array members which belong to the same