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