diff options
Diffstat (limited to 'Documentation/firmware-guide/acpi')
| -rw-r--r-- | Documentation/firmware-guide/acpi/acpi-lid.rst | 8 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/dsd/leds.rst | 8 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/enumeration.rst | 154 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/gpio-properties.rst | 111 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/method-tracing.rst | 2 |
5 files changed, 259 insertions, 24 deletions
diff --git a/Documentation/firmware-guide/acpi/acpi-lid.rst b/Documentation/firmware-guide/acpi/acpi-lid.rst index 874ce0ed340d..71b9af13a048 100644 --- a/Documentation/firmware-guide/acpi/acpi-lid.rst +++ b/Documentation/firmware-guide/acpi/acpi-lid.rst @@ -19,9 +19,9 @@ report the "current" state of the lid as either "opened" or "closed". For most platforms, both the _LID method and the lid notifications are reliable. However, there are exceptions. In order to work with these -exceptional buggy platforms, special restrictions and expections should be +exceptional buggy platforms, special restrictions and exceptions should be taken into account. This document describes the restrictions and the -expections of the Linux ACPI lid device driver. +exceptions of the Linux ACPI lid device driver. Restrictions of the returning value of the _LID control method @@ -46,7 +46,7 @@ state is changed to "closed". The "closed" notification is normally used to trigger some system power saving operations on Windows. Since it is fully tested, it is reliable from all AML tables. -Expections for the userspace users of the ACPI lid device driver +Exceptions for the userspace users of the ACPI lid device driver ================================================================ The ACPI button driver exports the lid state to the userspace via the @@ -100,7 +100,7 @@ use the following kernel parameter: C. button.lid_init_state=ignore: When this option is specified, the ACPI button driver never reports the initial lid state and there is a compensation mechanism implemented to - ensure that the reliable "closed" notifications can always be delievered + ensure that the reliable "closed" notifications can always be delivered to the userspace by always pairing "closed" input events with complement "opened" input events. But there is still no guarantee that the "opened" notifications can be delivered to the userspace when the lid is actually diff --git a/Documentation/firmware-guide/acpi/dsd/leds.rst b/Documentation/firmware-guide/acpi/dsd/leds.rst index aba1e9abfeeb..b99fff8e06f2 100644 --- a/Documentation/firmware-guide/acpi/dsd/leds.rst +++ b/Documentation/firmware-guide/acpi/dsd/leds.rst @@ -90,10 +90,10 @@ where References ========== -[1] Device tree. <URL:https://www.devicetree.org>, referenced 2019-02-21. +[1] Device tree. https://www.devicetree.org, referenced 2019-02-21. [2] Advanced Configuration and Power Interface Specification. - <URL:https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf>, + https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf, referenced 2019-02-21. [3] Documentation/devicetree/bindings/leds/common.txt @@ -101,11 +101,11 @@ References [4] Documentation/devicetree/bindings/media/video-interfaces.txt [5] Device Properties UUID For _DSD. - <URL:https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, + https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf, referenced 2019-02-21. [6] Hierarchical Data Extension UUID For _DSD. - <URL:https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, + https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf, referenced 2019-02-21. [7] Documentation/firmware-guide/acpi/dsd/data-node-references.rst diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst index c13fee8b02ba..9f0d5c854fa4 100644 --- a/Documentation/firmware-guide/acpi/enumeration.rst +++ b/Documentation/firmware-guide/acpi/enumeration.rst @@ -461,3 +461,157 @@ Otherwise, the _DSD itself is regarded as invalid and therefore the "compatible" property returned by it is meaningless. Refer to :doc:`DSD-properties-rules` for more information. + +PCI hierarchy representation +============================ + +Sometimes could be useful to enumerate a PCI device, knowing its position on the +PCI bus. + +For example, some systems use PCI devices soldered directly on the mother board, +in a fixed position (ethernet, Wi-Fi, serial ports, etc.). In this conditions it +is possible to refer to these PCI devices knowing their position on the PCI bus +topology. + +To identify a PCI device, a complete hierarchical description is required, from +the chipset root port to the final device, through all the intermediate +bridges/switches of the board. + +For example, let us assume to have a system with a PCIe serial port, an +Exar XR17V3521, soldered on the main board. This UART chip also includes +16 GPIOs and we want to add the property ``gpio-line-names`` [1] to these pins. +In this case, the ``lspci`` output for this component is:: + + 07:00.0 Serial controller: Exar Corp. XR17V3521 Dual PCIe UART (rev 03) + +The complete ``lspci`` output (manually reduced in length) is:: + + 00:00.0 Host bridge: Intel Corp... Host Bridge (rev 0d) + ... + 00:13.0 PCI bridge: Intel Corp... PCI Express Port A #1 (rev fd) + 00:13.1 PCI bridge: Intel Corp... PCI Express Port A #2 (rev fd) + 00:13.2 PCI bridge: Intel Corp... PCI Express Port A #3 (rev fd) + 00:14.0 PCI bridge: Intel Corp... PCI Express Port B #1 (rev fd) + 00:14.1 PCI bridge: Intel Corp... PCI Express Port B #2 (rev fd) + ... + 05:00.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05) + 06:01.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05) + 06:02.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05) + 06:03.0 PCI bridge: Pericom Semiconductor Device 2404 (rev 05) + 07:00.0 Serial controller: Exar Corp. XR17V3521 Dual PCIe UART (rev 03) <-- Exar + ... + +The bus topology is:: + + -[0000:00]-+-00.0 + ... + +-13.0-[01]----00.0 + +-13.1-[02]----00.0 + +-13.2-[03]-- + +-14.0-[04]----00.0 + +-14.1-[05-09]----00.0-[06-09]--+-01.0-[07]----00.0 <-- Exar + | +-02.0-[08]----00.0 + | \-03.0-[09]-- + ... + \-1f.1 + +To describe this Exar device on the PCI bus, we must start from the ACPI name +of the chipset bridge (also called "root port") with address:: + + Bus: 0 - Device: 14 - Function: 1 + +To find this information is necessary disassemble the BIOS ACPI tables, in +particular the DSDT (see also [2]):: + + mkdir ~/tables/ + cd ~/tables/ + acpidump > acpidump + acpixtract -a acpidump + iasl -e ssdt?.* -d dsdt.dat + +Now, in the dsdt.dsl, we have to search the device whose address is related to +0x14 (device) and 0x01 (function). In this case we can find the following +device:: + + Scope (_SB.PCI0) + { + ... other definitions follow ... + Device (RP02) + { + Method (_ADR, 0, NotSerialized) // _ADR: Address + { + If ((RPA2 != Zero)) + { + Return (RPA2) /* \RPA2 */ + } + Else + { + Return (0x00140001) + } + } + ... other definitions follow ... + +and the _ADR method [3] returns exactly the device/function couple that +we are looking for. With this information and analyzing the above ``lspci`` +output (both the devices list and the devices tree), we can write the following +ACPI description for the Exar PCIe UART, also adding the list of its GPIO line +names:: + + Scope (_SB.PCI0.RP02) + { + Device (BRG1) //Bridge + { + Name (_ADR, 0x0000) + + Device (BRG2) //Bridge + { + Name (_ADR, 0x00010000) + + Device (EXAR) + { + Name (_ADR, 0x0000) + + Name (_DSD, Package () + { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () + { + Package () + { + "gpio-line-names", + Package () + { + "mode_232", + "mode_422", + "mode_485", + "misc_1", + "misc_2", + "misc_3", + "", + "", + "aux_1", + "aux_2", + "aux_3", + } + } + } + }) + } + } + } + } + +The location "_SB.PCI0.RP02" is obtained by the above investigation in the +dsdt.dsl table, whereas the device names "BRG1", "BRG2" and "EXAR" are +created analyzing the position of the Exar UART in the PCI bus topology. + +References +========== + +[1] Documentation/firmware-guide/acpi/gpio-properties.rst + +[2] Documentation/admin-guide/acpi/initrd_table_override.rst + +[3] ACPI Specifications, Version 6.3 - Paragraph 6.1.1 _ADR Address) + https://uefi.org/sites/default/files/resources/ACPI_6_3_May16.pdf, + referenced 2020-11-18 diff --git a/Documentation/firmware-guide/acpi/gpio-properties.rst b/Documentation/firmware-guide/acpi/gpio-properties.rst index bb6d74f23ee0..b36aa3e743d8 100644 --- a/Documentation/firmware-guide/acpi/gpio-properties.rst +++ b/Documentation/firmware-guide/acpi/gpio-properties.rst @@ -20,9 +20,9 @@ index, like the ASL example below shows:: Name (_CRS, ResourceTemplate () { - GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionInputOnly, + GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly, "\\_SB.GPO0", 0, ResourceConsumer) {15} - GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionInputOnly, + GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly, "\\_SB.GPO0", 0, ResourceConsumer) {27, 31} }) @@ -49,15 +49,41 @@ index pin Pin in the GpioIo()/GpioInt() resource. Typically this is zero. active_low - If 1 the GPIO is marked as active_low. + If 1, the GPIO is marked as active_low. Since ACPI GpioIo() resource does not have a field saying whether it is active low or high, the "active_low" argument can be used here. Setting it to 1 marks the GPIO as active low. +Note, active_low in _DSD does not make sense for GpioInt() resource and +must be 0. GpioInt() resource has its own means of defining it. + In our Bluetooth example the "reset-gpios" refers to the second GpioIo() resource, second pin in that resource with the GPIO number of 31. +The GpioIo() resource unfortunately doesn't explicitly provide an initial +state of the output pin which driver should use during its initialization. + +Linux tries to use common sense here and derives the state from the bias +and polarity settings. The table below shows the expectations: + +========= ============= ============== +Pull Bias Polarity Requested... +========= ============= ============== +Implicit x AS IS (assumed firmware configured for us) +Explicit x (no _DSD) as Pull Bias (Up == High, Down == Low), + assuming non-active (Polarity = !Pull Bias) +Down Low as low, assuming active +Down High as low, assuming non-active +Up Low as high, assuming non-active +Up High as high, assuming active +========= ============= ============== + +That said, for our above example the both GPIOs, since the bias setting +is explicit and _DSD is present, will be treated as active with a high +polarity and Linux will configure the pins in this state until a driver +reprograms them differently. + It is possible to leave holes in the array of GPIOs. This is useful in cases like with SPI host controllers where some chip selects may be implemented as GPIOs and some as native signals. For example a SPI host @@ -107,13 +133,67 @@ Example:: - gpio-line-names -Example:: +The ``gpio-line-names`` declaration is a list of strings ("names"), which +describes each line/pin of a GPIO controller/expander. This list, contained in +a package, must be inserted inside the GPIO controller declaration of an ACPI +table (typically inside the DSDT). The ``gpio-line-names`` list must respect the +following rules (see also the examples): + + - the first name in the list corresponds with the first line/pin of the GPIO + controller/expander + - the names inside the list must be consecutive (no "holes" are permitted) + - the list can be incomplete and can end before the last GPIO line: in + other words, it is not mandatory to fill all the GPIO lines + - empty names are allowed (two quotation marks ``""`` correspond to an empty + name) + +Example of a GPIO controller of 16 lines, with an incomplete list with two +empty names:: + + Package () { + "gpio-line-names", + Package () { + "pin_0", + "pin_1", + "", + "", + "pin_3", + "pin_4_push_button", + } + } + +At runtime, the above declaration produces the following result (using the +"libgpiod" tools):: + + root@debian:~# gpioinfo gpiochip4 + gpiochip4 - 16 lines: + line 0: "pin_0" unused input active-high + line 1: "pin_1" unused input active-high + line 2: unnamed unused input active-high + line 3: unnamed unused input active-high + line 4: "pin_3" unused input active-high + line 5: "pin_4_push_button" unused input active-high + line 6: unnamed unused input active-high + line 7 unnamed unused input active-high + line 8: unnamed unused input active-high + line 9: unnamed unused input active-high + line 10: unnamed unused input active-high + line 11: unnamed unused input active-high + line 12: unnamed unused input active-high + line 13: unnamed unused input active-high + line 14: unnamed unused input active-high + line 15: unnamed unused input active-high + root@debian:~# gpiofind pin_4_push_button + gpiochip4 5 + root@debian:~# + +Another example:: Package () { "gpio-line-names", Package () { - "SPI0_CS_N", "EXP2_INT", "MUX6_IO", "UART0_RXD", "MUX7_IO", - "LVL_C_A1", "MUX0_IO", "SPI1_MISO" + "SPI0_CS_N", "EXP2_INT", "MUX6_IO", "UART0_RXD", + "MUX7_IO", "LVL_C_A1", "MUX0_IO", "SPI1_MISO", } } @@ -137,7 +217,7 @@ to the GPIO lines it is going to use and provide the GPIO subsystem with a mapping between those names and the ACPI GPIO resources corresponding to them. To do that, the driver needs to define a mapping table as a NULL-terminated -array of struct acpi_gpio_mapping objects that each contain a name, a pointer +array of struct acpi_gpio_mapping objects that each contains a name, a pointer to an array of line data (struct acpi_gpio_params) objects and the size of that array. Each struct acpi_gpio_params object consists of three fields, crs_entry_index, line_index, active_low, representing the index of the target @@ -154,13 +234,14 @@ question would look like this:: static const struct acpi_gpio_mapping bluetooth_acpi_gpios[] = { { "reset-gpios", &reset_gpio, 1 }, { "shutdown-gpios", &shutdown_gpio, 1 }, - { }, + { } }; Next, the mapping table needs to be passed as the second argument to -acpi_dev_add_driver_gpios() that will register it with the ACPI device object -pointed to by its first argument. That should be done in the driver's .probe() -routine. On removal, the driver should unregister its GPIO mapping table by +acpi_dev_add_driver_gpios() or its managed analogue that will +register it with the ACPI device object pointed to by its first +argument. That should be done in the driver's .probe() routine. +On removal, the driver should unregister its GPIO mapping table by calling acpi_dev_remove_driver_gpios() on the ACPI device object where that table was previously registered. @@ -191,12 +272,12 @@ The driver might expect to get the right GPIO when it does:: but since there is no way to know the mapping between "reset" and the GpioIo() in _CRS desc will hold ERR_PTR(-ENOENT). -The driver author can solve this by passing the mapping explictly -(the recommended way and documented in the above chapter). +The driver author can solve this by passing the mapping explicitly +(this is the recommended way and it's documented in the above chapter). The ACPI GPIO mapping tables should not contaminate drivers that are not knowing about which exact device they are servicing on. It implies that -the ACPI GPIO mapping tables are hardly linked to ACPI ID and certain +the ACPI GPIO mapping tables are hardly linked to an ACPI ID and certain objects, as listed in the above chapter, of the device in question. Getting GPIO descriptor @@ -229,5 +310,5 @@ Case 2 explicitly tells GPIO core to look for resources in _CRS. Be aware that gpiod_get_index() in cases 1 and 2, assuming that there are two versions of ACPI device description provided and no mapping is present in the driver, will return different resources. That's why a -certain driver has to handle them carefully as explained in previous +certain driver has to handle them carefully as explained in the previous chapter. diff --git a/Documentation/firmware-guide/acpi/method-tracing.rst b/Documentation/firmware-guide/acpi/method-tracing.rst index 0aa7e2c5d32a..6ab6c0964042 100644 --- a/Documentation/firmware-guide/acpi/method-tracing.rst +++ b/Documentation/firmware-guide/acpi/method-tracing.rst @@ -98,7 +98,7 @@ subject to change:: [ 0.188903] exdebug-0398 ex_trace_point : Method End [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution. Developers can utilize these special log entries to track the AML -interpretion, thus can aid issue debugging and performance tuning. Note +interpretation, thus can aid issue debugging and performance tuning. Note that, as the "AML tracer" logs are implemented via ACPI_DEBUG_PRINT() macro, CONFIG_ACPI_DEBUG is also required to be enabled for enabling "AML tracer" logs. |