blob: 86d3fa95fd12828f5110d4ae19e6721740af8d85 [file] [log] [blame]
Alexandre Courbotfd8e1982013-11-16 21:34:21 +09001GPIO 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
Javier Martinez Canillas2b719202015-09-21 15:14:46 +020024<function>-gpios, where <function> is the function the driver will request
25through gpiod_get(). For example:
Alexandre Courbotfd8e1982013-11-16 21:34:21 +090026
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
Javier Martinez Canillas2b719202015-09-21 15:14:46 +020034 power-gpios = <&gpio 1 GPIO_ACTIVE_LOW>;
Alexandre Courbotfd8e1982013-11-16 21:34:21 +090035 };
36
Javier Martinez Canillas2b719202015-09-21 15:14:46 +020037Properties named <function>-gpio are also considered valid and old bindings use
38it but are only supported for compatibility reasons and should not be used for
39newer bindings since it has been deprecated.
40
Alexandre Courbotfd8e1982013-11-16 21:34:21 +090041This property will make GPIOs 15, 16 and 17 available to the driver under the
42"led" function, and GPIO 1 as the "power" GPIO:
43
44 struct gpio_desc *red, *green, *blue, *power;
45
Dirk Behme69de52b2015-09-02 20:07:09 +020046 red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
47 green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
48 blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
Alexandre Courbotfd8e1982013-11-16 21:34:21 +090049
Dirk Behme69de52b2015-09-02 20:07:09 +020050 power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
Alexandre Courbotfd8e1982013-11-16 21:34:21 +090051
52The led GPIOs will be active-high, while the power GPIO will be active-low (i.e.
53gpiod_is_active_low(power) will be true).
54
Dirk Behme87e77e42015-09-02 20:07:10 +020055The second parameter of the gpiod_get() functions, the con_id string, has to be
56the <function>-prefix of the GPIO suffixes ("gpios" or "gpio", automatically
57looked up by the gpiod functions internally) used in the device tree. With above
58"led-gpios" example, use the prefix without the "-" as con_id parameter: "led".
59
60Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio")
61with the string passed in con_id to get the resulting string
62(snprintf(... "%s-%s", con_id, gpio_suffixes[]).
63
Alexandre Courbotfd8e1982013-11-16 21:34:21 +090064ACPI
65----
Mika Westerbergcfc50762015-04-01 11:13:16 +030066ACPI also supports function names for GPIOs in a similar fashion to DT.
67The above DT example can be converted to an equivalent ACPI description
68with the help of _DSD (Device Specific Data), introduced in ACPI 5.1:
69
70 Device (FOO) {
71 Name (_CRS, ResourceTemplate () {
72 GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
73 "\\_SB.GPI0") {15} // red
74 GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
75 "\\_SB.GPI0") {16} // green
76 GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
77 "\\_SB.GPI0") {17} // blue
78 GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
79 "\\_SB.GPI0") {1} // power
80 })
81
82 Name (_DSD, Package () {
83 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
84 Package () {
85 Package () {
86 "led-gpios",
87 Package () {
88 ^FOO, 0, 0, 1,
89 ^FOO, 1, 0, 1,
90 ^FOO, 2, 0, 1,
91 }
92 },
93 Package () {
94 "power-gpios",
95 Package () {^FOO, 3, 0, 0},
96 },
97 }
98 })
99 }
100
101For more information about the ACPI GPIO bindings see
102Documentation/acpi/gpio-properties.txt.
Alexandre Courbotfd8e1982013-11-16 21:34:21 +0900103
104Platform Data
105-------------
106Finally, GPIOs can be bound to devices and functions using platform data. Board
107files that desire to do so need to include the following header:
108
Linus Walleij0a6d3152014-07-24 20:08:55 +0200109 #include <linux/gpio/machine.h>
Alexandre Courbotfd8e1982013-11-16 21:34:21 +0900110
111GPIOs are mapped by the means of tables of lookups, containing instances of the
112gpiod_lookup structure. Two macros are defined to help declaring such mappings:
113
Gabor Juhoscfb74282016-02-25 08:00:45 +0100114 GPIO_LOOKUP(chip_label, chip_hwnum, con_id, flags)
115 GPIO_LOOKUP_IDX(chip_label, chip_hwnum, con_id, idx, flags)
Alexandre Courbotfd8e1982013-11-16 21:34:21 +0900116
117where
118
119 - chip_label is the label of the gpiod_chip instance providing the GPIO
120 - chip_hwnum is the hardware number of the GPIO within the chip
Alexandre Courbotfd8e1982013-11-16 21:34:21 +0900121 - con_id is the name of the GPIO function from the device point of view. It
Alexandre Courbotad824782013-12-03 12:20:11 +0900122 can be NULL, in which case it will match any function.
Alexandre Courbotfd8e1982013-11-16 21:34:21 +0900123 - idx is the index of the GPIO within the function.
124 - flags is defined to specify the following properties:
125 * GPIOF_ACTIVE_LOW - to configure the GPIO as active-low
126 * GPIOF_OPEN_DRAIN - GPIO pin is open drain type.
127 * GPIOF_OPEN_SOURCE - GPIO pin is open source type.
128
129In the future, these flags might be extended to support more properties.
130
131Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.
132
Alexandre Courbotad824782013-12-03 12:20:11 +0900133A lookup table can then be defined as follows, with an empty entry defining its
Gabor Juhoscfb74282016-02-25 08:00:45 +0100134end. The 'dev_id' field of the table is the identifier of the device that will
135make use of these GPIOs. It can be NULL, in which case it will be matched for
136calls to gpiod_get() with a NULL device.
Alexandre Courbotfd8e1982013-11-16 21:34:21 +0900137
Alexandre Courbotad824782013-12-03 12:20:11 +0900138struct gpiod_lookup_table gpios_table = {
139 .dev_id = "foo.0",
140 .table = {
141 GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH),
142 GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH),
143 GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH),
144 GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW),
145 { },
146 },
147};
Alexandre Courbotfd8e1982013-11-16 21:34:21 +0900148
149And the table can be added by the board code as follows:
150
Alexandre Courbotad824782013-12-03 12:20:11 +0900151 gpiod_add_lookup_table(&gpios_table);
Alexandre Courbotfd8e1982013-11-16 21:34:21 +0900152
153The driver controlling "foo.0" will then be able to obtain its GPIOs as follows:
154
155 struct gpio_desc *red, *green, *blue, *power;
156
Dirk Behme69de52b2015-09-02 20:07:09 +0200157 red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
158 green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
159 blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
Alexandre Courbotfd8e1982013-11-16 21:34:21 +0900160
Dirk Behme69de52b2015-09-02 20:07:09 +0200161 power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
Alexandre Courbotfd8e1982013-11-16 21:34:21 +0900162
Dirk Behme69de52b2015-09-02 20:07:09 +0200163Since the "led" GPIOs are mapped as active-high, this example will switch their
164signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped
165as active-low, its actual signal will be 0 after this code. Contrary to the legacy
166integer GPIO interface, the active-low property is handled during mapping and is
167thus transparent to GPIO consumers.