Documentation/gpio/board.txt

   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-gpios = <&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/machine.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. It
  76         can be NULL, in which case it will be matched for calls to gpiod_get()
  77         with a NULL device.
  78   - con_id is the name of the GPIO function from the device point of view. It
  79         can be NULL, in which case it will match any function.
  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
  90 A lookup table can then be defined as follows, with an empty entry defining its
  91 end:
  92
  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 };
 103
 104 And the table can be added by the board code as follows:
 105
 106         gpiod_add_lookup_table(&gpios_table);
 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.