Commit | Line | Data |
---|---|---|
fd8e198c AC |
1 | GPIO Mappings |
2 | ============= | |
3 | ||
4 | This document explains how GPIOs can be assigned to given devices and functions. | |
5 | Note that it only applies to the new descriptor-based interface. For a | |
6 | description of the deprecated integer-based GPIO interface please refer to | |
7 | gpio-legacy.txt (actually, there is no real mapping possible with the old | |
8 | interface; you just fetch an integer from somewhere and request the | |
9 | corresponding GPIO. | |
10 | ||
11 | Platforms that make use of GPIOs must select ARCH_REQUIRE_GPIOLIB (if GPIO usage | |
12 | is mandatory) or ARCH_WANT_OPTIONAL_GPIOLIB (if GPIO support can be omitted) in | |
13 | their Kconfig. Then, how GPIOs are mapped depends on what the platform uses to | |
14 | describe its hardware layout. Currently, mappings can be defined through device | |
15 | tree, ACPI, and platform data. | |
16 | ||
17 | Device Tree | |
18 | ----------- | |
19 | GPIOs can easily be mapped to devices and functions in the device tree. The | |
20 | exact way to do it depends on the GPIO controller providing the GPIOs, see the | |
21 | device tree bindings for your controller. | |
22 | ||
23 | GPIOs mappings are defined in the consumer device's node, in a property named | |
ae80d64e JMC |
24 | either <function>-gpios or <function>-gpio, where <function> is the function |
25 | the driver will request through gpiod_get(). For example: | |
fd8e198c AC |
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 | ||
ae80d64e | 34 | power-gpio = <&gpio 1 GPIO_ACTIVE_LOW>; |
fd8e198c AC |
35 | }; |
36 | ||
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: | |
39 | ||
40 | struct gpio_desc *red, *green, *blue, *power; | |
41 | ||
69de52ba DB |
42 | 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); | |
fd8e198c | 45 | |
69de52ba | 46 | power = gpiod_get(dev, "power", GPIOD_OUT_HIGH); |
fd8e198c AC |
47 | |
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). | |
50 | ||
87e77e46 DB |
51 | The second parameter of the gpiod_get() functions, the con_id string, has to be |
52 | the <function>-prefix of the GPIO suffixes ("gpios" or "gpio", automatically | |
53 | looked 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 | ||
56 | Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio") | |
57 | with the string passed in con_id to get the resulting string | |
58 | (snprintf(... "%s-%s", con_id, gpio_suffixes[]). | |
59 | ||
fd8e198c AC |
60 | ACPI |
61 | ---- | |
cfc50764 MW |
62 | ACPI also supports function names for GPIOs in a similar fashion to DT. |
63 | The above DT example can be converted to an equivalent ACPI description | |
64 | with 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 | ||
97 | For more information about the ACPI GPIO bindings see | |
98 | Documentation/acpi/gpio-properties.txt. | |
fd8e198c AC |
99 | |
100 | Platform Data | |
101 | ------------- | |
102 | Finally, GPIOs can be bound to devices and functions using platform data. Board | |
103 | files that desire to do so need to include the following header: | |
104 | ||
0a6d3158 | 105 | #include <linux/gpio/machine.h> |
fd8e198c AC |
106 | |
107 | GPIOs are mapped by the means of tables of lookups, containing instances of the | |
108 | gpiod_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 | ||
113 | where | |
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 | |
ad824783 AC |
117 | - 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. | |
fd8e198c | 120 | - con_id is the name of the GPIO function from the device point of view. It |
ad824783 | 121 | can be NULL, in which case it will match any function. |
fd8e198c AC |
122 | - 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 | ||
128 | In the future, these flags might be extended to support more properties. | |
129 | ||
130 | Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0. | |
131 | ||
ad824783 AC |
132 | A lookup table can then be defined as follows, with an empty entry defining its |
133 | end: | |
fd8e198c | 134 | |
ad824783 AC |
135 | struct 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 | }; | |
fd8e198c AC |
145 | |
146 | And the table can be added by the board code as follows: | |
147 | ||
ad824783 | 148 | gpiod_add_lookup_table(&gpios_table); |
fd8e198c AC |
149 | |
150 | The driver controlling "foo.0" will then be able to obtain its GPIOs as follows: | |
151 | ||
152 | struct gpio_desc *red, *green, *blue, *power; | |
153 | ||
69de52ba DB |
154 | 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); | |
fd8e198c | 157 | |
69de52ba | 158 | power = gpiod_get(dev, "power", GPIOD_OUT_HIGH); |
fd8e198c | 159 | |
69de52ba DB |
160 | Since the "led" GPIOs are mapped as active-high, this example will switch their |
161 | signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped | |
162 | as active-low, its actual signal will be 0 after this code. Contrary to the legacy | |
163 | integer GPIO interface, the active-low property is handled during mapping and is | |
164 | thus transparent to GPIO consumers. |