blob: f59c43b6411b7d1b51b48c9acc1dd4b5f2338337 [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 Canillasae80d642015-09-01 10:46:15 +020024either <function>-gpios or <function>-gpio, where <function> is the function
25the driver will request through 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 Canillasae80d642015-09-01 10:46:15 +020034 power-gpio = <&gpio 1 GPIO_ACTIVE_LOW>;
Alexandre Courbotfd8e1982013-11-16 21:34:21 +090035 };
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
Dirk Behme69de52b2015-09-02 20:07:09 +020042 red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
43 green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
44 blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
Alexandre Courbotfd8e1982013-11-16 21:34:21 +090045
Dirk Behme69de52b2015-09-02 20:07:09 +020046 power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
Alexandre Courbotfd8e1982013-11-16 21:34:21 +090047
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
Dirk Behme87e77e42015-09-02 20:07:10 +020051The second parameter of the gpiod_get() functions, the con_id string, has to be
52the <function>-prefix of the GPIO suffixes ("gpios" or "gpio", automatically
53looked up by the gpiod functions internally) used in the device tree. With above
54"led-gpios" example, use the prefix without the "-" as con_id parameter: "led".
55
56Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio")
57with the string passed in con_id to get the resulting string
58(snprintf(... "%s-%s", con_id, gpio_suffixes[]).
59
Alexandre Courbotfd8e1982013-11-16 21:34:21 +090060ACPI
61----
Mika Westerbergcfc50762015-04-01 11:13:16 +030062ACPI also supports function names for GPIOs in a similar fashion to DT.
63The above DT example can be converted to an equivalent ACPI description
64with the help of _DSD (Device Specific Data), introduced in ACPI 5.1:
65
66 Device (FOO) {
67 Name (_CRS, ResourceTemplate () {
68 GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
69 "\\_SB.GPI0") {15} // red
70 GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
71 "\\_SB.GPI0") {16} // green
72 GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
73 "\\_SB.GPI0") {17} // blue
74 GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
75 "\\_SB.GPI0") {1} // power
76 })
77
78 Name (_DSD, Package () {
79 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
80 Package () {
81 Package () {
82 "led-gpios",
83 Package () {
84 ^FOO, 0, 0, 1,
85 ^FOO, 1, 0, 1,
86 ^FOO, 2, 0, 1,
87 }
88 },
89 Package () {
90 "power-gpios",
91 Package () {^FOO, 3, 0, 0},
92 },
93 }
94 })
95 }
96
97For more information about the ACPI GPIO bindings see
98Documentation/acpi/gpio-properties.txt.
Alexandre Courbotfd8e1982013-11-16 21:34:21 +090099
100Platform Data
101-------------
102Finally, GPIOs can be bound to devices and functions using platform data. Board
103files that desire to do so need to include the following header:
104
Linus Walleij0a6d3152014-07-24 20:08:55 +0200105 #include <linux/gpio/machine.h>
Alexandre Courbotfd8e1982013-11-16 21:34:21 +0900106
107GPIOs are mapped by the means of tables of lookups, containing instances of the
108gpiod_lookup structure. Two macros are defined to help declaring such mappings:
109
110 GPIO_LOOKUP(chip_label, chip_hwnum, dev_id, con_id, flags)
111 GPIO_LOOKUP_IDX(chip_label, chip_hwnum, dev_id, con_id, idx, flags)
112
113where
114
115 - chip_label is the label of the gpiod_chip instance providing the GPIO
116 - chip_hwnum is the hardware number of the GPIO within the chip
Alexandre Courbotad824782013-12-03 12:20:11 +0900117 - dev_id is the identifier of the device that will make use of this GPIO. It
118 can be NULL, in which case it will be matched for calls to gpiod_get()
119 with a NULL device.
Alexandre Courbotfd8e1982013-11-16 21:34:21 +0900120 - con_id is the name of the GPIO function from the device point of view. It
Alexandre Courbotad824782013-12-03 12:20:11 +0900121 can be NULL, in which case it will match any function.
Alexandre Courbotfd8e1982013-11-16 21:34:21 +0900122 - idx is the index of the GPIO within the function.
123 - flags is defined to specify the following properties:
124 * GPIOF_ACTIVE_LOW - to configure the GPIO as active-low
125 * GPIOF_OPEN_DRAIN - GPIO pin is open drain type.
126 * GPIOF_OPEN_SOURCE - GPIO pin is open source type.
127
128In the future, these flags might be extended to support more properties.
129
130Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.
131
Alexandre Courbotad824782013-12-03 12:20:11 +0900132A lookup table can then be defined as follows, with an empty entry defining its
133end:
Alexandre Courbotfd8e1982013-11-16 21:34:21 +0900134
Alexandre Courbotad824782013-12-03 12:20:11 +0900135struct gpiod_lookup_table gpios_table = {
136 .dev_id = "foo.0",
137 .table = {
138 GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH),
139 GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH),
140 GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH),
141 GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW),
142 { },
143 },
144};
Alexandre Courbotfd8e1982013-11-16 21:34:21 +0900145
146And the table can be added by the board code as follows:
147
Alexandre Courbotad824782013-12-03 12:20:11 +0900148 gpiod_add_lookup_table(&gpios_table);
Alexandre Courbotfd8e1982013-11-16 21:34:21 +0900149
150The driver controlling "foo.0" will then be able to obtain its GPIOs as follows:
151
152 struct gpio_desc *red, *green, *blue, *power;
153
Dirk Behme69de52b2015-09-02 20:07:09 +0200154 red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
155 green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
156 blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
Alexandre Courbotfd8e1982013-11-16 21:34:21 +0900157
Dirk Behme69de52b2015-09-02 20:07:09 +0200158 power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
Alexandre Courbotfd8e1982013-11-16 21:34:21 +0900159
Dirk Behme69de52b2015-09-02 20:07:09 +0200160Since the "led" GPIOs are mapped as active-high, this example will switch their
161signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped
162as active-low, its actual signal will be 0 after this code. Contrary to the legacy
163integer GPIO interface, the active-low property is handled during mapping and is
164thus transparent to GPIO consumers.