tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1GPIO Mappings
2=============
3
4This document explains how GPIOs can be assigned to given devices and functions.
5Note that it only applies to the new descriptor-based interface. For a
6description of the deprecated integer-based GPIO interface please refer to
7gpio-legacy.txt (actually, there is no real mapping possible with the old
8interface; you just fetch an integer from somewhere and request the
9corresponding GPIO.
10
11Platforms that make use of GPIOs must select ARCH_REQUIRE_GPIOLIB (if GPIO usage
12is mandatory) or ARCH_WANT_OPTIONAL_GPIOLIB (if GPIO support can be omitted) in
13their Kconfig. Then, how GPIOs are mapped depends on what the platform uses to
14describe its hardware layout. Currently, mappings can be defined through device
15tree, ACPI, and platform data.
16
17Device Tree
18-----------
19GPIOs can easily be mapped to devices and functions in the device tree. The
20exact way to do it depends on the GPIO controller providing the GPIOs, see the
21device tree bindings for your controller.
22
23GPIOs mappings are defined in the consumer device's node, in a property named
24<function>-gpios, where <function> is the function the driver will request
25through gpiod_get(). For example:
26
27 foo_device {
28 compatible = "acme,foo";
29 ...
30 led-gpios = <&gpio 15 GPIO_ACTIVE_HIGH>, /* red */
31 <&gpio 16 GPIO_ACTIVE_HIGH>, /* green */
32 <&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */
33
34 power-gpio = <&gpio 1 GPIO_ACTIVE_LOW>;
35 };
36
37This property will make GPIOs 15, 16 and 17 available to the driver under the
38"led" function, and GPIO 1 as the "power" GPIO:
39
40 struct gpio_desc *red, *green, *blue, *power;
41
42 red = gpiod_get_index(dev, "led", 0);
43 green = gpiod_get_index(dev, "led", 1);
44 blue = gpiod_get_index(dev, "led", 2);
45
46 power = gpiod_get(dev, "power");
47
48The led GPIOs will be active-high, while the power GPIO will be active-low (i.e.
49gpiod_is_active_low(power) will be true).
50
51ACPI
52----
53ACPI does not support function names for GPIOs. Therefore, only the "idx"
54argument of gpiod_get_index() is useful to discriminate between GPIOs assigned
55to a device. The "con_id" argument can still be set for debugging purposes (it
56will appear under error messages as well as debug and sysfs nodes).
57
58Platform Data
59-------------
60Finally, GPIOs can be bound to devices and functions using platform data. Board
61files that desire to do so need to include the following header:
62
63 #include <linux/gpio/driver.h>
64
65GPIOs are mapped by the means of tables of lookups, containing instances of the
66gpiod_lookup structure. Two macros are defined to help declaring such mappings:
67
68 GPIO_LOOKUP(chip_label, chip_hwnum, dev_id, con_id, flags)
69 GPIO_LOOKUP_IDX(chip_label, chip_hwnum, dev_id, con_id, idx, flags)
70
71where
72
73 - chip_label is the label of the gpiod_chip instance providing the GPIO
74 - chip_hwnum is the hardware number of the GPIO within the chip
75 - dev_id is the identifier of the device that will make use of this GPIO. If
76 NULL, the GPIO will be available to all devices.
77 - con_id is the name of the GPIO function from the device point of view. It
78 can be NULL.
79 - idx is the index of the GPIO within the function.
80 - flags is defined to specify the following properties:
81 * GPIOF_ACTIVE_LOW - to configure the GPIO as active-low
82 * GPIOF_OPEN_DRAIN - GPIO pin is open drain type.
83 * GPIOF_OPEN_SOURCE - GPIO pin is open source type.
84
85In the future, these flags might be extended to support more properties.
86
87Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.
88
89A lookup table can then be defined as follows:
90
91 struct gpiod_lookup gpios_table[] = {
92 GPIO_LOOKUP_IDX("gpio.0", 15, "foo.0", "led", 0, GPIO_ACTIVE_HIGH),
93 GPIO_LOOKUP_IDX("gpio.0", 16, "foo.0", "led", 1, GPIO_ACTIVE_HIGH),
94 GPIO_LOOKUP_IDX("gpio.0", 17, "foo.0", "led", 2, GPIO_ACTIVE_HIGH),
95 GPIO_LOOKUP("gpio.0", 1, "foo.0", "power", GPIO_ACTIVE_LOW),
96 };
97
98And the table can be added by the board code as follows:
99
100 gpiod_add_table(gpios_table, ARRAY_SIZE(gpios_table));
101
102The driver controlling "foo.0" will then be able to obtain its GPIOs as follows:
103
104 struct gpio_desc *red, *green, *blue, *power;
105
106 red = gpiod_get_index(dev, "led", 0);
107 green = gpiod_get_index(dev, "led", 1);
108 blue = gpiod_get_index(dev, "led", 2);
109
110 power = gpiod_get(dev, "power");
111 gpiod_direction_output(power, 1);
112
113Since the "power" GPIO is mapped as active-low, its actual signal will be 0
114after this code. Contrary to the legacy integer GPIO interface, the active-low
115property is handled during mapping and is thus transparent to GPIO consumers.