mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-08-24 17:59:32 +00:00
![Javier Martinez Canillas](/assets/img/avatar_default.png)
The gpiolib supports parsing DT properties of the form <function>-gpio
but it was only added for compatibility with older DT bindings that got
it wrong and should not be used in newer bindings.
The commit that added support for this was:
dd34c37aa3
("gpio: of: Allow -gpio suffix for property names")
but didn't update the documentation to explain this so it's been a source
of confusion. So let's make clear this in the GPIO documentation.
Signed-off-by: Javier Martinez Canillas <javier@osg.samsung.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
168 lines
6.1 KiB
Text
168 lines
6.1 KiB
Text
GPIO Mappings
|
|
=============
|
|
|
|
This document explains how GPIOs can be assigned to given devices and functions.
|
|
Note that it only applies to the new descriptor-based interface. For a
|
|
description of the deprecated integer-based GPIO interface please refer to
|
|
gpio-legacy.txt (actually, there is no real mapping possible with the old
|
|
interface; you just fetch an integer from somewhere and request the
|
|
corresponding GPIO.
|
|
|
|
Platforms that make use of GPIOs must select ARCH_REQUIRE_GPIOLIB (if GPIO usage
|
|
is mandatory) or ARCH_WANT_OPTIONAL_GPIOLIB (if GPIO support can be omitted) in
|
|
their Kconfig. Then, how GPIOs are mapped depends on what the platform uses to
|
|
describe its hardware layout. Currently, mappings can be defined through device
|
|
tree, ACPI, and platform data.
|
|
|
|
Device Tree
|
|
-----------
|
|
GPIOs can easily be mapped to devices and functions in the device tree. The
|
|
exact way to do it depends on the GPIO controller providing the GPIOs, see the
|
|
device tree bindings for your controller.
|
|
|
|
GPIOs mappings are defined in the consumer device's node, in a property named
|
|
<function>-gpios, where <function> is the function the driver will request
|
|
through gpiod_get(). For example:
|
|
|
|
foo_device {
|
|
compatible = "acme,foo";
|
|
...
|
|
led-gpios = <&gpio 15 GPIO_ACTIVE_HIGH>, /* red */
|
|
<&gpio 16 GPIO_ACTIVE_HIGH>, /* green */
|
|
<&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */
|
|
|
|
power-gpios = <&gpio 1 GPIO_ACTIVE_LOW>;
|
|
};
|
|
|
|
Properties named <function>-gpio are also considered valid and old bindings use
|
|
it but are only supported for compatibility reasons and should not be used for
|
|
newer bindings since it has been deprecated.
|
|
|
|
This property will make GPIOs 15, 16 and 17 available to the driver under the
|
|
"led" function, and GPIO 1 as the "power" GPIO:
|
|
|
|
struct gpio_desc *red, *green, *blue, *power;
|
|
|
|
red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
|
|
green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
|
|
blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
|
|
|
|
power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
|
|
|
|
The led GPIOs will be active-high, while the power GPIO will be active-low (i.e.
|
|
gpiod_is_active_low(power) will be true).
|
|
|
|
The second parameter of the gpiod_get() functions, the con_id string, has to be
|
|
the <function>-prefix of the GPIO suffixes ("gpios" or "gpio", automatically
|
|
looked up by the gpiod functions internally) used in the device tree. With above
|
|
"led-gpios" example, use the prefix without the "-" as con_id parameter: "led".
|
|
|
|
Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio")
|
|
with the string passed in con_id to get the resulting string
|
|
(snprintf(... "%s-%s", con_id, gpio_suffixes[]).
|
|
|
|
ACPI
|
|
----
|
|
ACPI also supports function names for GPIOs in a similar fashion to DT.
|
|
The above DT example can be converted to an equivalent ACPI description
|
|
with the help of _DSD (Device Specific Data), introduced in ACPI 5.1:
|
|
|
|
Device (FOO) {
|
|
Name (_CRS, ResourceTemplate () {
|
|
GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
|
|
"\\_SB.GPI0") {15} // red
|
|
GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
|
|
"\\_SB.GPI0") {16} // green
|
|
GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
|
|
"\\_SB.GPI0") {17} // blue
|
|
GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
|
|
"\\_SB.GPI0") {1} // power
|
|
})
|
|
|
|
Name (_DSD, Package () {
|
|
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
|
|
Package () {
|
|
Package () {
|
|
"led-gpios",
|
|
Package () {
|
|
^FOO, 0, 0, 1,
|
|
^FOO, 1, 0, 1,
|
|
^FOO, 2, 0, 1,
|
|
}
|
|
},
|
|
Package () {
|
|
"power-gpios",
|
|
Package () {^FOO, 3, 0, 0},
|
|
},
|
|
}
|
|
})
|
|
}
|
|
|
|
For more information about the ACPI GPIO bindings see
|
|
Documentation/acpi/gpio-properties.txt.
|
|
|
|
Platform Data
|
|
-------------
|
|
Finally, GPIOs can be bound to devices and functions using platform data. Board
|
|
files that desire to do so need to include the following header:
|
|
|
|
#include <linux/gpio/machine.h>
|
|
|
|
GPIOs are mapped by the means of tables of lookups, containing instances of the
|
|
gpiod_lookup structure. Two macros are defined to help declaring such mappings:
|
|
|
|
GPIO_LOOKUP(chip_label, chip_hwnum, dev_id, con_id, flags)
|
|
GPIO_LOOKUP_IDX(chip_label, chip_hwnum, dev_id, con_id, idx, flags)
|
|
|
|
where
|
|
|
|
- chip_label is the label of the gpiod_chip instance providing the GPIO
|
|
- chip_hwnum is the hardware number of the GPIO within the chip
|
|
- dev_id is the identifier of the device that will make use of this GPIO. It
|
|
can be NULL, in which case it will be matched for calls to gpiod_get()
|
|
with a NULL device.
|
|
- con_id is the name of the GPIO function from the device point of view. It
|
|
can be NULL, in which case it will match any function.
|
|
- idx is the index of the GPIO within the function.
|
|
- flags is defined to specify the following properties:
|
|
* GPIOF_ACTIVE_LOW - to configure the GPIO as active-low
|
|
* GPIOF_OPEN_DRAIN - GPIO pin is open drain type.
|
|
* GPIOF_OPEN_SOURCE - GPIO pin is open source type.
|
|
|
|
In the future, these flags might be extended to support more properties.
|
|
|
|
Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.
|
|
|
|
A lookup table can then be defined as follows, with an empty entry defining its
|
|
end:
|
|
|
|
struct gpiod_lookup_table gpios_table = {
|
|
.dev_id = "foo.0",
|
|
.table = {
|
|
GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH),
|
|
GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH),
|
|
GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH),
|
|
GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW),
|
|
{ },
|
|
},
|
|
};
|
|
|
|
And the table can be added by the board code as follows:
|
|
|
|
gpiod_add_lookup_table(&gpios_table);
|
|
|
|
The driver controlling "foo.0" will then be able to obtain its GPIOs as follows:
|
|
|
|
struct gpio_desc *red, *green, *blue, *power;
|
|
|
|
red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
|
|
green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
|
|
blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
|
|
|
|
power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
|
|
|
|
Since the "led" GPIOs are mapped as active-high, this example will switch their
|
|
signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped
|
|
as active-low, its actual signal will be 0 after this code. Contrary to the legacy
|
|
integer GPIO interface, the active-low property is handled during mapping and is
|
|
thus transparent to GPIO consumers.
|