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 | |
24 | <function>-gpios, where <function> is the function the driver will request | |
25 | through 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 | ||
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 | ||
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 | ||
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 | ||
51 | ACPI | |
52 | ---- | |
53 | ACPI does not support function names for GPIOs. Therefore, only the "idx" | |
54 | argument of gpiod_get_index() is useful to discriminate between GPIOs assigned | |
55 | to a device. The "con_id" argument can still be set for debugging purposes (it | |
56 | will appear under error messages as well as debug and sysfs nodes). | |
57 | ||
58 | Platform Data | |
59 | ------------- | |
60 | Finally, GPIOs can be bound to devices and functions using platform data. Board | |
61 | files that desire to do so need to include the following header: | |
62 | ||
63 | #include <linux/gpio/driver.h> | |
64 | ||
65 | GPIOs are mapped by the means of tables of lookups, containing instances of the | |
66 | gpiod_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 | ||
71 | where | |
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 | |
ad824783 AC |
75 | - dev_id is the identifier of the device that will make use of this GPIO. It |
76 | can be NULL, in which case it will be matched for calls to gpiod_get() | |
77 | with a NULL device. | |
fd8e198c | 78 | - con_id is the name of the GPIO function from the device point of view. It |
ad824783 | 79 | can be NULL, in which case it will match any function. |
fd8e198c AC |
80 | - idx is the index of the GPIO within the function. |
81 | - flags is defined to specify the following properties: | |
82 | * GPIOF_ACTIVE_LOW - to configure the GPIO as active-low | |
83 | * GPIOF_OPEN_DRAIN - GPIO pin is open drain type. | |
84 | * GPIOF_OPEN_SOURCE - GPIO pin is open source type. | |
85 | ||
86 | In the future, these flags might be extended to support more properties. | |
87 | ||
88 | Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0. | |
89 | ||
ad824783 AC |
90 | A lookup table can then be defined as follows, with an empty entry defining its |
91 | end: | |
fd8e198c | 92 | |
ad824783 AC |
93 | struct gpiod_lookup_table gpios_table = { |
94 | .dev_id = "foo.0", | |
95 | .table = { | |
96 | GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH), | |
97 | GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH), | |
98 | GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH), | |
99 | GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW), | |
100 | { }, | |
101 | }, | |
102 | }; | |
fd8e198c AC |
103 | |
104 | And the table can be added by the board code as follows: | |
105 | ||
ad824783 | 106 | gpiod_add_lookup_table(&gpios_table); |
fd8e198c AC |
107 | |
108 | The driver controlling "foo.0" will then be able to obtain its GPIOs as follows: | |
109 | ||
110 | struct gpio_desc *red, *green, *blue, *power; | |
111 | ||
112 | red = gpiod_get_index(dev, "led", 0); | |
113 | green = gpiod_get_index(dev, "led", 1); | |
114 | blue = gpiod_get_index(dev, "led", 2); | |
115 | ||
116 | power = gpiod_get(dev, "power"); | |
117 | gpiod_direction_output(power, 1); | |
118 | ||
119 | Since the "power" GPIO is mapped as active-low, its actual signal will be 0 | |
120 | after this code. Contrary to the legacy integer GPIO interface, the active-low | |
121 | property is handled during mapping and is thus transparent to GPIO consumers. |