board.rst 8.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225
  1. =============
  2. GPIO Mappings
  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. All platforms can enable the GPIO library, but if the platform strictly
  11. requires GPIO functionality to be present, it needs to select GPIOLIB from its
  12. Kconfig. Then, how GPIOs are mapped depends on what the platform uses to
  13. describe its hardware layout. Currently, mappings can be defined through device
  14. tree, ACPI, and platform data.
  15. Device Tree
  16. -----------
  17. GPIOs can easily be mapped to devices and functions in the device tree. The
  18. exact way to do it depends on the GPIO controller providing the GPIOs, see the
  19. device tree bindings for your controller.
  20. GPIOs mappings are defined in the consumer device's node, in a property named
  21. <function>-gpios, where <function> is the function the driver will request
  22. through gpiod_get(). For example::
  23. foo_device {
  24. compatible = "acme,foo";
  25. ...
  26. led-gpios = <&gpio 15 GPIO_ACTIVE_HIGH>, /* red */
  27. <&gpio 16 GPIO_ACTIVE_HIGH>, /* green */
  28. <&gpio 17 GPIO_ACTIVE_HIGH>; /* blue */
  29. power-gpios = <&gpio 1 GPIO_ACTIVE_LOW>;
  30. };
  31. Properties named <function>-gpio are also considered valid and old bindings use
  32. it but are only supported for compatibility reasons and should not be used for
  33. newer bindings since it has been deprecated.
  34. This property will make GPIOs 15, 16 and 17 available to the driver under the
  35. "led" function, and GPIO 1 as the "power" GPIO::
  36. struct gpio_desc *red, *green, *blue, *power;
  37. red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
  38. green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
  39. blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
  40. power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
  41. The led GPIOs will be active high, while the power GPIO will be active low (i.e.
  42. gpiod_is_active_low(power) will be true).
  43. The second parameter of the gpiod_get() functions, the con_id string, has to be
  44. the <function>-prefix of the GPIO suffixes ("gpios" or "gpio", automatically
  45. looked up by the gpiod functions internally) used in the device tree. With above
  46. "led-gpios" example, use the prefix without the "-" as con_id parameter: "led".
  47. Internally, the GPIO subsystem prefixes the GPIO suffix ("gpios" or "gpio")
  48. with the string passed in con_id to get the resulting string
  49. (``snprintf(... "%s-%s", con_id, gpio_suffixes[]``).
  50. ACPI
  51. ----
  52. ACPI also supports function names for GPIOs in a similar fashion to DT.
  53. The above DT example can be converted to an equivalent ACPI description
  54. with the help of _DSD (Device Specific Data), introduced in ACPI 5.1::
  55. Device (FOO) {
  56. Name (_CRS, ResourceTemplate () {
  57. GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
  58. "\\_SB.GPI0") {15} // red
  59. GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
  60. "\\_SB.GPI0") {16} // green
  61. GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
  62. "\\_SB.GPI0") {17} // blue
  63. GpioIo (Exclusive, ..., IoRestrictionOutputOnly,
  64. "\\_SB.GPI0") {1} // power
  65. })
  66. Name (_DSD, Package () {
  67. ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
  68. Package () {
  69. Package () {
  70. "led-gpios",
  71. Package () {
  72. ^FOO, 0, 0, 1,
  73. ^FOO, 1, 0, 1,
  74. ^FOO, 2, 0, 1,
  75. }
  76. },
  77. Package () {
  78. "power-gpios",
  79. Package () {^FOO, 3, 0, 0},
  80. },
  81. }
  82. })
  83. }
  84. For more information about the ACPI GPIO bindings see
  85. Documentation/firmware-guide/acpi/gpio-properties.rst.
  86. Platform Data
  87. -------------
  88. Finally, GPIOs can be bound to devices and functions using platform data. Board
  89. files that desire to do so need to include the following header::
  90. #include <linux/gpio/machine.h>
  91. GPIOs are mapped by the means of tables of lookups, containing instances of the
  92. gpiod_lookup structure. Two macros are defined to help declaring such mappings::
  93. GPIO_LOOKUP(key, chip_hwnum, con_id, flags)
  94. GPIO_LOOKUP_IDX(key, chip_hwnum, con_id, idx, flags)
  95. where
  96. - key is either the label of the gpiod_chip instance providing the GPIO, or
  97. the GPIO line name
  98. - chip_hwnum is the hardware number of the GPIO within the chip, or U16_MAX
  99. to indicate that key is a GPIO line name
  100. - con_id is the name of the GPIO function from the device point of view. It
  101. can be NULL, in which case it will match any function.
  102. - idx is the index of the GPIO within the function.
  103. - flags is defined to specify the following properties:
  104. * GPIO_ACTIVE_HIGH - GPIO line is active high
  105. * GPIO_ACTIVE_LOW - GPIO line is active low
  106. * GPIO_OPEN_DRAIN - GPIO line is set up as open drain
  107. * GPIO_OPEN_SOURCE - GPIO line is set up as open source
  108. * GPIO_PERSISTENT - GPIO line is persistent during
  109. suspend/resume and maintains its value
  110. * GPIO_TRANSITORY - GPIO line is transitory and may loose its
  111. electrical state during suspend/resume
  112. In the future, these flags might be extended to support more properties.
  113. Note that:
  114. 1. GPIO line names are not guaranteed to be globally unique, so the first
  115. match found will be used.
  116. 2. GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.
  117. A lookup table can then be defined as follows, with an empty entry defining its
  118. end. The 'dev_id' field of the table is the identifier of the device that will
  119. make use of these GPIOs. It can be NULL, in which case it will be matched for
  120. calls to gpiod_get() with a NULL device.
  121. .. code-block:: c
  122. struct gpiod_lookup_table gpios_table = {
  123. .dev_id = "foo.0",
  124. .table = {
  125. GPIO_LOOKUP_IDX("gpio.0", 15, "led", 0, GPIO_ACTIVE_HIGH),
  126. GPIO_LOOKUP_IDX("gpio.0", 16, "led", 1, GPIO_ACTIVE_HIGH),
  127. GPIO_LOOKUP_IDX("gpio.0", 17, "led", 2, GPIO_ACTIVE_HIGH),
  128. GPIO_LOOKUP("gpio.0", 1, "power", GPIO_ACTIVE_LOW),
  129. { },
  130. },
  131. };
  132. And the table can be added by the board code as follows::
  133. gpiod_add_lookup_table(&gpios_table);
  134. The driver controlling "foo.0" will then be able to obtain its GPIOs as follows::
  135. struct gpio_desc *red, *green, *blue, *power;
  136. red = gpiod_get_index(dev, "led", 0, GPIOD_OUT_HIGH);
  137. green = gpiod_get_index(dev, "led", 1, GPIOD_OUT_HIGH);
  138. blue = gpiod_get_index(dev, "led", 2, GPIOD_OUT_HIGH);
  139. power = gpiod_get(dev, "power", GPIOD_OUT_HIGH);
  140. Since the "led" GPIOs are mapped as active-high, this example will switch their
  141. signals to 1, i.e. enabling the LEDs. And for the "power" GPIO, which is mapped
  142. as active-low, its actual signal will be 0 after this code. Contrary to the
  143. legacy integer GPIO interface, the active-low property is handled during
  144. mapping and is thus transparent to GPIO consumers.
  145. A set of functions such as gpiod_set_value() is available to work with
  146. the new descriptor-oriented interface.
  147. Boards using platform data can also hog GPIO lines by defining GPIO hog tables.
  148. .. code-block:: c
  149. struct gpiod_hog gpio_hog_table[] = {
  150. GPIO_HOG("gpio.0", 10, "foo", GPIO_ACTIVE_LOW, GPIOD_OUT_HIGH),
  151. { }
  152. };
  153. And the table can be added to the board code as follows::
  154. gpiod_add_hogs(gpio_hog_table);
  155. The line will be hogged as soon as the gpiochip is created or - in case the
  156. chip was created earlier - when the hog table is registered.
  157. Arrays of pins
  158. --------------
  159. In addition to requesting pins belonging to a function one by one, a device may
  160. also request an array of pins assigned to the function. The way those pins are
  161. mapped to the device determines if the array qualifies for fast bitmap
  162. processing. If yes, a bitmap is passed over get/set array functions directly
  163. between a caller and a respective .get/set_multiple() callback of a GPIO chip.
  164. In order to qualify for fast bitmap processing, the array must meet the
  165. following requirements:
  166. - pin hardware number of array member 0 must also be 0,
  167. - pin hardware numbers of consecutive array members which belong to the same
  168. chip as member 0 does must also match their array indexes.
  169. Otherwise fast bitmap processing path is not used in order to avoid consecutive
  170. pins which belong to the same chip but are not in hardware order being processed
  171. separately.
  172. If the array applies for fast bitmap processing path, pins which belong to
  173. different chips than member 0 does, as well as those with indexes different from
  174. their hardware pin numbers, are excluded from the fast path, both input and
  175. output. Moreover, open drain and open source pins are excluded from fast bitmap
  176. output processing.