Documentation/firmware-guide/acpi/gpio-properties.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ======================================
   4 _DSD Device Properties Related to GPIO
   5 ======================================
   6
   7 With the release of ACPI 5.1, the _DSD configuration object finally
   8 allows names to be given to GPIOs (and other things as well) returned
   9 by _CRS.  Previously, we were only able to use an integer index to find
  10 the corresponding GPIO, which is pretty error prone (it depends on
  11 the _CRS output ordering, for example).
  12
  13 With _DSD we can now query GPIOs using a name instead of an integer
  14 index, like the ASL example below shows::
  15
  16   // Bluetooth device with reset and shutdown GPIOs
  17   Device (BTH)
  18   {
  19       Name (_HID, ...)
  20
  21       Name (_CRS, ResourceTemplate ()
  22       {
  23           GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly,
  24                   "\\_SB.GPO0", 0, ResourceConsumer) { 15 }
  25           GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly,
  26                   "\\_SB.GPO0", 0, ResourceConsumer) { 27, 31 }
  27       })
  28
  29       Name (_DSD, Package ()
  30       {
  31           ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
  32           Package ()
  33           {
  34               Package () { "reset-gpios", Package () { ^BTH, 1, 1, 0 } },
  35               Package () { "shutdown-gpios", Package () { ^BTH, 0, 0, 0 } },
  36           }
  37       })
  38   }
  39
  40 The format of the supported GPIO property is::
  41
  42   Package () { "name", Package () { ref, index, pin, active_low }}
  43
  44 ref
  45   The device that has _CRS containing GpioIo()/GpioInt() resources,
  46   typically this is the device itself (BTH in our case).
  47 index
  48   Index of the GpioIo()/GpioInt() resource in _CRS starting from zero.
  49 pin
  50   Pin in the GpioIo()/GpioInt() resource. Typically this is zero.
  51 active_low
  52   If 1, the GPIO is marked as active_low.
  53
  54 Since ACPI GpioIo() resource does not have a field saying whether it is
  55 active low or high, the "active_low" argument can be used here.  Setting
  56 it to 1 marks the GPIO as active low.
  57
  58 Note, active_low in _DSD does not make sense for GpioInt() resource and
  59 must be 0. GpioInt() resource has its own means of defining it.
  60
  61 In our Bluetooth example the "reset-gpios" refers to the second GpioIo()
  62 resource, second pin in that resource with the GPIO number of 31.
  63
  64 The GpioIo() resource unfortunately doesn't explicitly provide an initial
  65 state of the output pin which driver should use during its initialization.
  66
  67 Linux tries to use common sense here and derives the state from the bias
  68 and polarity settings. The table below shows the expectations:
  69
  70 +-------------+-------------+-----------------------------------------------+
  71 | Pull Bias   | Polarity    | Requested...                                  |
  72 +=============+=============+===============================================+
  73 | Implicit                                                                  |
  74 +-------------+-------------+-----------------------------------------------+
  75 | **Default** | x           | AS IS (assumed firmware configured it for us) |
  76 +-------------+-------------+-----------------------------------------------+
  77 | Explicit                                                                  |
  78 +-------------+-------------+-----------------------------------------------+
  79 | **None**    | x           | AS IS (assumed firmware configured it for us) |
  80 |             |             | with no Pull Bias                             |
  81 +-------------+-------------+-----------------------------------------------+
  82 | **Up**      | x (no _DSD) |                                               |
  83 |             +-------------+ as high, assuming non-active                  |
  84 |             | Low         |                                               |
  85 |             +-------------+-----------------------------------------------+
  86 |             | High        | as high, assuming active                      |
  87 +-------------+-------------+-----------------------------------------------+
  88 | **Down**    | x (no _DSD) |                                               |
  89 |             +-------------+ as low, assuming non-active                   |
  90 |             | High        |                                               |
  91 |             +-------------+-----------------------------------------------+
  92 |             | Low         | as low, assuming active                       |
  93 +-------------+-------------+-----------------------------------------------+
  94
  95 That said, for our above example the both GPIOs, since the bias setting
  96 is explicit and _DSD is present, will be treated as active with a high
  97 polarity and Linux will configure the pins in this state until a driver
  98 reprograms them differently.
  99
 100 It is possible to leave holes in the array of GPIOs. This is useful in
 101 cases like with SPI host controllers where some chip selects may be
 102 implemented as GPIOs and some as native signals. For example a SPI host
 103 controller can have chip selects 0 and 2 implemented as GPIOs and 1 as
 104 native::
 105
 106   Package () {
 107       "cs-gpios",
 108       Package () {
 109           ^GPIO, 19, 0, 0, // chip select 0: GPIO
 110           0,               // chip select 1: native signal
 111           ^GPIO, 20, 0, 0, // chip select 2: GPIO
 112       }
 113   }
 114
 115 Note, that historically ACPI has no means of the GPIO polarity and thus
 116 the SPISerialBus() resource defines it on the per-chip basis. In order
 117 to avoid a chain of negations, the GPIO polarity is considered being
 118 Active High. Even for the cases when _DSD() is involved (see the example
 119 above) the GPIO CS polarity must be defined Active High to avoid ambiguity.
 120
 121 Other supported properties
 122 ==========================
 123
 124 Following Device Tree compatible device properties are also supported by
 125 _DSD device properties for GPIO controllers:
 126
 127 - gpio-hog
 128 - output-high
 129 - output-low
 130 - input
 131 - line-name
 132
 133 Example::
 134
 135   Name (_DSD, Package () {
 136       // _DSD Hierarchical Properties Extension UUID
 137       ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
 138       Package () {
 139           Package () { "hog-gpio8", "G8PU" }
 140       }
 141   })
 142
 143   Name (G8PU, Package () {
 144       ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
 145       Package () {
 146           Package () { "gpio-hog", 1 },
 147           Package () { "gpios", Package () { 8, 0 } },
 148           Package () { "output-high", 1 },
 149           Package () { "line-name", "gpio8-pullup" },
 150       }
 151   })
 152
 153 - gpio-line-names
 154
 155 The ``gpio-line-names`` declaration is a list of strings ("names"), which
 156 describes each line/pin of a GPIO controller/expander. This list, contained in
 157 a package, must be inserted inside the GPIO controller declaration of an ACPI
 158 table (typically inside the DSDT). The ``gpio-line-names`` list must respect the
 159 following rules (see also the examples):
 160
 161   - the first name in the list corresponds with the first line/pin of the GPIO
 162     controller/expander
 163   - the names inside the list must be consecutive (no "holes" are permitted)
 164   - the list can be incomplete and can end before the last GPIO line: in
 165     other words, it is not mandatory to fill all the GPIO lines
 166   - empty names are allowed (two quotation marks ``""`` correspond to an empty
 167     name)
 168   - names inside one GPIO controller/expander must be unique
 169
 170 Example of a GPIO controller of 16 lines, with an incomplete list with two
 171 empty names::
 172
 173   Package () {
 174       "gpio-line-names",
 175       Package () {
 176           "pin_0",
 177           "pin_1",
 178           "",
 179           "",
 180           "pin_3",
 181           "pin_4_push_button",
 182       }
 183   }
 184
 185 At runtime, the above declaration produces the following result (using the
 186 "libgpiod" tools)::
 187
 188   root@debian:~# gpioinfo gpiochip4
 189   gpiochip4 - 16 lines:
 190           line   0:      "pin_0"       unused   input  active-high
 191           line   1:      "pin_1"       unused   input  active-high
 192           line   2:      unnamed       unused   input  active-high
 193           line   3:      unnamed       unused   input  active-high
 194           line   4:      "pin_3"       unused   input  active-high
 195           line   5: "pin_4_push_button" unused input active-high
 196           line   6:      unnamed       unused   input  active-high
 197           line   7       unnamed       unused   input  active-high
 198           line   8:      unnamed       unused   input  active-high
 199           line   9:      unnamed       unused   input  active-high
 200           line  10:      unnamed       unused   input  active-high
 201           line  11:      unnamed       unused   input  active-high
 202           line  12:      unnamed       unused   input  active-high
 203           line  13:      unnamed       unused   input  active-high
 204           line  14:      unnamed       unused   input  active-high
 205           line  15:      unnamed       unused   input  active-high
 206   root@debian:~# gpiofind pin_4_push_button
 207   gpiochip4 5
 208   root@debian:~#
 209
 210 Another example::
 211
 212   Package () {
 213       "gpio-line-names",
 214       Package () {
 215           "SPI0_CS_N", "EXP2_INT", "MUX6_IO", "UART0_RXD",
 216           "MUX7_IO", "LVL_C_A1", "MUX0_IO", "SPI1_MISO",
 217       }
 218   }
 219
 220 See Documentation/devicetree/bindings/gpio/gpio.txt for more information
 221 about these properties.
 222
 223 ACPI GPIO Mappings Provided by Drivers
 224 ======================================
 225
 226 There are systems in which the ACPI tables do not contain _DSD but provide _CRS
 227 with GpioIo()/GpioInt() resources and device drivers still need to work with
 228 them.
 229
 230 In those cases ACPI device identification objects, _HID, _CID, _CLS, _SUB, _HRV,
 231 available to the driver can be used to identify the device and that is supposed
 232 to be sufficient to determine the meaning and purpose of all of the GPIO lines
 233 listed by the GpioIo()/GpioInt() resources returned by _CRS.  In other words,
 234 the driver is supposed to know what to use the GpioIo()/GpioInt() resources for
 235 once it has identified the device.  Having done that, it can simply assign names
 236 to the GPIO lines it is going to use and provide the GPIO subsystem with a
 237 mapping between those names and the ACPI GPIO resources corresponding to them.
 238
 239 To do that, the driver needs to define a mapping table as a NULL-terminated
 240 array of struct acpi_gpio_mapping objects that each contains a name, a pointer
 241 to an array of line data (struct acpi_gpio_params) objects and the size of that
 242 array.  Each struct acpi_gpio_params object consists of three fields,
 243 crs_entry_index, line_index, active_low, representing the index of the target
 244 GpioIo()/GpioInt() resource in _CRS starting from zero, the index of the target
 245 line in that resource starting from zero, and the active-low flag for that line,
 246 respectively, in analogy with the _DSD GPIO property format specified above.
 247
 248 For the example Bluetooth device discussed previously the data structures in
 249 question would look like this::
 250
 251   static const struct acpi_gpio_params reset_gpio = { 1, 1, false };
 252   static const struct acpi_gpio_params shutdown_gpio = { 0, 0, false };
 253
 254   static const struct acpi_gpio_mapping bluetooth_acpi_gpios[] = {
 255     { "reset-gpios", &reset_gpio, 1 },
 256     { "shutdown-gpios", &shutdown_gpio, 1 },
 257     { }
 258   };
 259
 260 Next, the mapping table needs to be passed as the second argument to
 261 acpi_dev_add_driver_gpios() or its managed analogue that will
 262 register it with the ACPI device object pointed to by its first
 263 argument. That should be done in the driver's .probe() routine.
 264 On removal, the driver should unregister its GPIO mapping table by
 265 calling acpi_dev_remove_driver_gpios() on the ACPI device object where that
 266 table was previously registered.
 267
 268 Using the _CRS fallback
 269 =======================
 270
 271 If a device does not have _DSD or the driver does not create ACPI GPIO
 272 mapping, the Linux GPIO framework refuses to return any GPIOs. This is
 273 because the driver does not know what it actually gets. For example if we
 274 have a device like below::
 275
 276   Device (BTH)
 277   {
 278       Name (_HID, ...)
 279
 280       Name (_CRS, ResourceTemplate () {
 281           GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionNone,
 282                   "\\_SB.GPO0", 0, ResourceConsumer) { 15 }
 283           GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionNone,
 284                   "\\_SB.GPO0", 0, ResourceConsumer) { 27 }
 285       })
 286   }
 287
 288 The driver might expect to get the right GPIO when it does::
 289
 290   desc = gpiod_get(dev, "reset", GPIOD_OUT_LOW);
 291   if (IS_ERR(desc))
 292         ...error handling...
 293
 294 but since there is no way to know the mapping between "reset" and
 295 the GpioIo() in _CRS desc will hold ERR_PTR(-ENOENT).
 296
 297 The driver author can solve this by passing the mapping explicitly
 298 (this is the recommended way and it's documented in the above chapter).
 299
 300 The ACPI GPIO mapping tables should not contaminate drivers that are not
 301 knowing about which exact device they are servicing on. It implies that
 302 the ACPI GPIO mapping tables are hardly linked to an ACPI ID and certain
 303 objects, as listed in the above chapter, of the device in question.
 304
 305 Getting GPIO descriptor
 306 =======================
 307
 308 There are two main approaches to get GPIO resource from ACPI::
 309
 310   desc = gpiod_get(dev, connection_id, flags);
 311   desc = gpiod_get_index(dev, connection_id, index, flags);
 312
 313 We may consider two different cases here, i.e. when connection ID is
 314 provided and otherwise.
 315
 316 Case 1::
 317
 318   desc = gpiod_get(dev, "non-null-connection-id", flags);
 319   desc = gpiod_get_index(dev, "non-null-connection-id", index, flags);
 320
 321 Case 2::
 322
 323   desc = gpiod_get(dev, NULL, flags);
 324   desc = gpiod_get_index(dev, NULL, index, flags);
 325
 326 Case 1 assumes that corresponding ACPI device description must have
 327 defined device properties and will prevent to getting any GPIO resources
 328 otherwise.
 329
 330 Case 2 explicitly tells GPIO core to look for resources in _CRS.
 331
 332 Be aware that gpiod_get_index() in cases 1 and 2, assuming that there
 333 are two versions of ACPI device description provided and no mapping is
 334 present in the driver, will return different resources. That's why a
 335 certain driver has to handle them carefully as explained in the previous
 336 chapter.