diff options
Diffstat (limited to 'Documentation/gpio/board.txt')
-rw-r--r-- | Documentation/gpio/board.txt | 115 |
1 files changed, 115 insertions, 0 deletions
diff --git a/Documentation/gpio/board.txt b/Documentation/gpio/board.txt new file mode 100644 index 000000000000..0d03506f2cc5 --- /dev/null +++ b/Documentation/gpio/board.txt | |||
@@ -0,0 +1,115 @@ | |||
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 | ||
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 | |||
85 | In the future, these flags might be extended to support more properties. | ||
86 | |||
87 | Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0. | ||
88 | |||
89 | A 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 | |||
98 | And the table can be added by the board code as follows: | ||
99 | |||
100 | gpiod_add_table(gpios_table, ARRAY_SIZE(gpios_table)); | ||
101 | |||
102 | The 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 | |||
113 | Since the "power" GPIO is mapped as active-low, its actual signal will be 0 | ||
114 | after this code. Contrary to the legacy integer GPIO interface, the active-low | ||
115 | property is handled during mapping and is thus transparent to GPIO consumers. | ||