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