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 102Other supported properties 103========================== 104 105Following Device Tree compatible device properties are also supported by 106_DSD device properties for GPIO controllers: 107 108- gpio-hog 109- output-high 110- output-low 111- input 112- line-name 113 114Example:: 115 116 Name (_DSD, Package () { 117 // _DSD Hierarchical Properties Extension UUID 118 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), 119 Package () { 120 Package () {"hog-gpio8", "G8PU"} 121 } 122 }) 123 124 Name (G8PU, Package () { 125 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), 126 Package () { 127 Package () {"gpio-hog", 1}, 128 Package () {"gpios", Package () {8, 0}}, 129 Package () {"output-high", 1}, 130 Package () {"line-name", "gpio8-pullup"}, 131 } 132 }) 133 134- gpio-line-names 135 136The ``gpio-line-names`` declaration is a list of strings ("names"), which 137describes each line/pin of a GPIO controller/expander. This list, contained in 138a package, must be inserted inside the GPIO controller declaration of an ACPI 139table (typically inside the DSDT). The ``gpio-line-names`` list must respect the 140following rules (see also the examples): 141 142 - the first name in the list corresponds with the first line/pin of the GPIO 143 controller/expander 144 - the names inside the list must be consecutive (no "holes" are permitted) 145 - the list can be incomplete and can end before the last GPIO line: in 146 other words, it is not mandatory to fill all the GPIO lines 147 - empty names are allowed (two quotation marks ``""`` correspond to an empty 148 name) 149 150Example of a GPIO controller of 16 lines, with an incomplete list with two 151empty names:: 152 153 Package () { 154 "gpio-line-names", 155 Package () { 156 "pin_0", 157 "pin_1", 158 "", 159 "", 160 "pin_3", 161 "pin_4_push_button", 162 } 163 } 164 165At runtime, the above declaration produces the following result (using the 166"libgpiod" tools):: 167 168 root@debian:~# gpioinfo gpiochip4 169 gpiochip4 - 16 lines: 170 line 0: "pin_0" unused input active-high 171 line 1: "pin_1" unused input active-high 172 line 2: unnamed unused input active-high 173 line 3: unnamed unused input active-high 174 line 4: "pin_3" unused input active-high 175 line 5: "pin_4_push_button" unused input active-high 176 line 6: unnamed unused input active-high 177 line 7 unnamed unused input active-high 178 line 8: unnamed unused input active-high 179 line 9: unnamed unused input active-high 180 line 10: unnamed unused input active-high 181 line 11: unnamed unused input active-high 182 line 12: unnamed unused input active-high 183 line 13: unnamed unused input active-high 184 line 14: unnamed unused input active-high 185 line 15: unnamed unused input active-high 186 root@debian:~# gpiofind pin_4_push_button 187 gpiochip4 5 188 root@debian:~# 189 190Another example:: 191 192 Package () { 193 "gpio-line-names", 194 Package () { 195 "SPI0_CS_N", "EXP2_INT", "MUX6_IO", "UART0_RXD", 196 "MUX7_IO", "LVL_C_A1", "MUX0_IO", "SPI1_MISO", 197 } 198 } 199 200See Documentation/devicetree/bindings/gpio/gpio.txt for more information 201about these properties. 202 203ACPI GPIO Mappings Provided by Drivers 204====================================== 205 206There are systems in which the ACPI tables do not contain _DSD but provide _CRS 207with GpioIo()/GpioInt() resources and device drivers still need to work with 208them. 209 210In those cases ACPI device identification objects, _HID, _CID, _CLS, _SUB, _HRV, 211available to the driver can be used to identify the device and that is supposed 212to be sufficient to determine the meaning and purpose of all of the GPIO lines 213listed by the GpioIo()/GpioInt() resources returned by _CRS. In other words, 214the driver is supposed to know what to use the GpioIo()/GpioInt() resources for 215once it has identified the device. Having done that, it can simply assign names 216to the GPIO lines it is going to use and provide the GPIO subsystem with a 217mapping between those names and the ACPI GPIO resources corresponding to them. 218 219To do that, the driver needs to define a mapping table as a NULL-terminated 220array of struct acpi_gpio_mapping objects that each contains a name, a pointer 221to an array of line data (struct acpi_gpio_params) objects and the size of that 222array. Each struct acpi_gpio_params object consists of three fields, 223crs_entry_index, line_index, active_low, representing the index of the target 224GpioIo()/GpioInt() resource in _CRS starting from zero, the index of the target 225line in that resource starting from zero, and the active-low flag for that line, 226respectively, in analogy with the _DSD GPIO property format specified above. 227 228For the example Bluetooth device discussed previously the data structures in 229question would look like this:: 230 231 static const struct acpi_gpio_params reset_gpio = { 1, 1, false }; 232 static const struct acpi_gpio_params shutdown_gpio = { 0, 0, false }; 233 234 static const struct acpi_gpio_mapping bluetooth_acpi_gpios[] = { 235 { "reset-gpios", &reset_gpio, 1 }, 236 { "shutdown-gpios", &shutdown_gpio, 1 }, 237 { } 238 }; 239 240Next, the mapping table needs to be passed as the second argument to 241acpi_dev_add_driver_gpios() or its managed analogue that will 242register it with the ACPI device object pointed to by its first 243argument. That should be done in the driver's .probe() routine. 244On removal, the driver should unregister its GPIO mapping table by 245calling acpi_dev_remove_driver_gpios() on the ACPI device object where that 246table was previously registered. 247 248Using the _CRS fallback 249======================= 250 251If a device does not have _DSD or the driver does not create ACPI GPIO 252mapping, the Linux GPIO framework refuses to return any GPIOs. This is 253because the driver does not know what it actually gets. For example if we 254have a device like below:: 255 256 Device (BTH) 257 { 258 Name (_HID, ...) 259 260 Name (_CRS, ResourceTemplate () { 261 GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionNone, 262 "\\_SB.GPO0", 0, ResourceConsumer) {15} 263 GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionNone, 264 "\\_SB.GPO0", 0, ResourceConsumer) {27} 265 }) 266 } 267 268The driver might expect to get the right GPIO when it does:: 269 270 desc = gpiod_get(dev, "reset", GPIOD_OUT_LOW); 271 272but since there is no way to know the mapping between "reset" and 273the GpioIo() in _CRS desc will hold ERR_PTR(-ENOENT). 274 275The driver author can solve this by passing the mapping explicitly 276(this is the recommended way and it's documented in the above chapter). 277 278The ACPI GPIO mapping tables should not contaminate drivers that are not 279knowing about which exact device they are servicing on. It implies that 280the ACPI GPIO mapping tables are hardly linked to an ACPI ID and certain 281objects, as listed in the above chapter, of the device in question. 282 283Getting GPIO descriptor 284======================= 285 286There are two main approaches to get GPIO resource from ACPI:: 287 288 desc = gpiod_get(dev, connection_id, flags); 289 desc = gpiod_get_index(dev, connection_id, index, flags); 290 291We may consider two different cases here, i.e. when connection ID is 292provided and otherwise. 293 294Case 1:: 295 296 desc = gpiod_get(dev, "non-null-connection-id", flags); 297 desc = gpiod_get_index(dev, "non-null-connection-id", index, flags); 298 299Case 2:: 300 301 desc = gpiod_get(dev, NULL, flags); 302 desc = gpiod_get_index(dev, NULL, index, flags); 303 304Case 1 assumes that corresponding ACPI device description must have 305defined device properties and will prevent to getting any GPIO resources 306otherwise. 307 308Case 2 explicitly tells GPIO core to look for resources in _CRS. 309 310Be aware that gpiod_get_index() in cases 1 and 2, assuming that there 311are two versions of ACPI device description provided and no mapping is 312present in the driver, will return different resources. That's why a 313certain driver has to handle them carefully as explained in the previous 314chapter. 315