From 680e6ffa15103ab610c0fc1241d2f98c801b13e2 Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 25 Apr 2019 23:30:54 +0800 Subject: Documentation: add Linux ACPI to Sphinx TOC tree Add below index.rst files for ACPI subsystem. More docs will be added later. o admin-guide/acpi/index.rst o driver-api/acpi/index.rst o firmware-guide/index.rst Signed-off-by: Changbin Du Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Rafael J. Wysocki --- Documentation/firmware-guide/acpi/index.rst | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 Documentation/firmware-guide/acpi/index.rst (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst new file mode 100644 index 000000000000..0ec7d072ba22 --- /dev/null +++ b/Documentation/firmware-guide/acpi/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============ +ACPI Support +============ + +.. toctree:: + :maxdepth: 1 + -- cgit v1.2.3-59-g8ed1b From 8a2fe04b446f909ffffadb84b886199edbe408c2 Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 25 Apr 2019 01:52:44 +0800 Subject: Documentation: ACPI: move namespace.txt to firmware-guide/acpi and convert to reST This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/namespace.txt | 388 ----------------------- Documentation/firmware-guide/acpi/index.rst | 1 + Documentation/firmware-guide/acpi/namespace.rst | 400 ++++++++++++++++++++++++ 3 files changed, 401 insertions(+), 388 deletions(-) delete mode 100644 Documentation/acpi/namespace.txt create mode 100644 Documentation/firmware-guide/acpi/namespace.rst (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/acpi/namespace.txt b/Documentation/acpi/namespace.txt deleted file mode 100644 index 1860cb3865c6..000000000000 --- a/Documentation/acpi/namespace.txt +++ /dev/null @@ -1,388 +0,0 @@ -ACPI Device Tree - Representation of ACPI Namespace - -Copyright (C) 2013, Intel Corporation -Author: Lv Zheng - - -Abstract: - -The Linux ACPI subsystem converts ACPI namespace objects into a Linux -device tree under the /sys/devices/LNXSYSTEM:00 and updates it upon -receiving ACPI hotplug notification events. For each device object in this -hierarchy there is a corresponding symbolic link in the -/sys/bus/acpi/devices. -This document illustrates the structure of the ACPI device tree. - - -Credit: - -Thanks for the help from Zhang Rui and Rafael J. -Wysocki . - - -1. ACPI Definition Blocks - - The ACPI firmware sets up RSDP (Root System Description Pointer) in the - system memory address space pointing to the XSDT (Extended System - Description Table). The XSDT always points to the FADT (Fixed ACPI - Description Table) using its first entry, the data within the FADT - includes various fixed-length entries that describe fixed ACPI features - of the hardware. The FADT contains a pointer to the DSDT - (Differentiated System Descripition Table). The XSDT also contains - entries pointing to possibly multiple SSDTs (Secondary System - Description Table). - - The DSDT and SSDT data is organized in data structures called definition - blocks that contain definitions of various objects, including ACPI - control methods, encoded in AML (ACPI Machine Language). The data block - of the DSDT along with the contents of SSDTs represents a hierarchical - data structure called the ACPI namespace whose topology reflects the - structure of the underlying hardware platform. - - The relationships between ACPI System Definition Tables described above - are illustrated in the following diagram. - - +---------+ +-------+ +--------+ +------------------------+ - | RSDP | +->| XSDT | +->| FADT | | +-------------------+ | - +---------+ | +-------+ | +--------+ +-|->| DSDT | | - | Pointer | | | Entry |-+ | ...... | | | +-------------------+ | - +---------+ | +-------+ | X_DSDT |--+ | | Definition Blocks | | - | Pointer |-+ | ..... | | ...... | | +-------------------+ | - +---------+ +-------+ +--------+ | +-------------------+ | - | Entry |------------------|->| SSDT | | - +- - - -+ | +-------------------| | - | Entry | - - - - - - - -+ | | Definition Blocks | | - +- - - -+ | | +-------------------+ | - | | +- - - - - - - - - -+ | - +-|->| SSDT | | - | +-------------------+ | - | | Definition Blocks | | - | +- - - - - - - - - -+ | - +------------------------+ - | - OSPM Loading | - \|/ - +----------------+ - | ACPI Namespace | - +----------------+ - - Figure 1. ACPI Definition Blocks - - NOTE: RSDP can also contain a pointer to the RSDT (Root System - Description Table). Platforms provide RSDT to enable - compatibility with ACPI 1.0 operating systems. The OS is expected - to use XSDT, if present. - - -2. Example ACPI Namespace - - All definition blocks are loaded into a single namespace. The namespace - is a hierarchy of objects identified by names and paths. - The following naming conventions apply to object names in the ACPI - namespace: - 1. All names are 32 bits long. - 2. The first byte of a name must be one of 'A' - 'Z', '_'. - 3. Each of the remaining bytes of a name must be one of 'A' - 'Z', '0' - - '9', '_'. - 4. Names starting with '_' are reserved by the ACPI specification. - 5. The '\' symbol represents the root of the namespace (i.e. names - prepended with '\' are relative to the namespace root). - 6. The '^' symbol represents the parent of the current namespace node - (i.e. names prepended with '^' are relative to the parent of the - current namespace node). - - The figure below shows an example ACPI namespace. - - +------+ - | \ | Root - +------+ - | - | +------+ - +-| _PR | Scope(_PR): the processor namespace - | +------+ - | | - | | +------+ - | +-| CPU0 | Processor(CPU0): the first processor - | +------+ - | - | +------+ - +-| _SB | Scope(_SB): the system bus namespace - | +------+ - | | - | | +------+ - | +-| LID0 | Device(LID0); the lid device - | | +------+ - | | | - | | | +------+ - | | +-| _HID | Name(_HID, "PNP0C0D"): the hardware ID - | | | +------+ - | | | - | | | +------+ - | | +-| _STA | Method(_STA): the status control method - | | +------+ - | | - | | +------+ - | +-| PCI0 | Device(PCI0); the PCI root bridge - | +------+ - | | - | | +------+ - | +-| _HID | Name(_HID, "PNP0A08"): the hardware ID - | | +------+ - | | - | | +------+ - | +-| _CID | Name(_CID, "PNP0A03"): the compatible ID - | | +------+ - | | - | | +------+ - | +-| RP03 | Scope(RP03): the PCI0 power scope - | | +------+ - | | | - | | | +------+ - | | +-| PXP3 | PowerResource(PXP3): the PCI0 power resource - | | +------+ - | | - | | +------+ - | +-| GFX0 | Device(GFX0): the graphics adapter - | +------+ - | | - | | +------+ - | +-| _ADR | Name(_ADR, 0x00020000): the PCI bus address - | | +------+ - | | - | | +------+ - | +-| DD01 | Device(DD01): the LCD output device - | +------+ - | | - | | +------+ - | +-| _BCL | Method(_BCL): the backlight control method - | +------+ - | - | +------+ - +-| _TZ | Scope(_TZ): the thermal zone namespace - | +------+ - | | - | | +------+ - | +-| FN00 | PowerResource(FN00): the FAN0 power resource - | | +------+ - | | - | | +------+ - | +-| FAN0 | Device(FAN0): the FAN0 cooling device - | | +------+ - | | | - | | | +------+ - | | +-| _HID | Name(_HID, "PNP0A0B"): the hardware ID - | | +------+ - | | - | | +------+ - | +-| TZ00 | ThermalZone(TZ00); the FAN thermal zone - | +------+ - | - | +------+ - +-| _GPE | Scope(_GPE): the GPE namespace - +------+ - - Figure 2. Example ACPI Namespace - - -3. Linux ACPI Device Objects - - The Linux kernel's core ACPI subsystem creates struct acpi_device - objects for ACPI namespace objects representing devices, power resources - processors, thermal zones. Those objects are exported to user space via - sysfs as directories in the subtree under /sys/devices/LNXSYSTM:00. The - format of their names is , where 'bus_id' refers to the - ACPI namespace representation of the given object and 'instance' is used - for distinguishing different object of the same 'bus_id' (it is - two-digit decimal representation of an unsigned integer). - - The value of 'bus_id' depends on the type of the object whose name it is - part of as listed in the table below. - - +---+-----------------+-------+----------+ - | | Object/Feature | Table | bus_id | - +---+-----------------+-------+----------+ - | N | Root | xSDT | LNXSYSTM | - +---+-----------------+-------+----------+ - | N | Device | xSDT | _HID | - +---+-----------------+-------+----------+ - | N | Processor | xSDT | LNXCPU | - +---+-----------------+-------+----------+ - | N | ThermalZone | xSDT | LNXTHERM | - +---+-----------------+-------+----------+ - | N | PowerResource | xSDT | LNXPOWER | - +---+-----------------+-------+----------+ - | N | Other Devices | xSDT | device | - +---+-----------------+-------+----------+ - | F | PWR_BUTTON | FADT | LNXPWRBN | - +---+-----------------+-------+----------+ - | F | SLP_BUTTON | FADT | LNXSLPBN | - +---+-----------------+-------+----------+ - | M | Video Extension | xSDT | LNXVIDEO | - +---+-----------------+-------+----------+ - | M | ATA Controller | xSDT | LNXIOBAY | - +---+-----------------+-------+----------+ - | M | Docking Station | xSDT | LNXDOCK | - +---+-----------------+-------+----------+ - - Table 1. ACPI Namespace Objects Mapping - - The following rules apply when creating struct acpi_device objects on - the basis of the contents of ACPI System Description Tables (as - indicated by the letter in the first column and the notation in the - second column of the table above): - N: - The object's source is an ACPI namespace node (as indicated by the - named object's type in the second column). In that case the object's - directory in sysfs will contain the 'path' attribute whose value is - the full path to the node from the namespace root. - F: - The struct acpi_device object is created for a fixed hardware - feature (as indicated by the fixed feature flag's name in the second - column), so its sysfs directory will not contain the 'path' - attribute. - M: - The struct acpi_device object is created for an ACPI namespace node - with specific control methods (as indicated by the ACPI defined - device's type in the second column). The 'path' attribute containing - its namespace path will be present in its sysfs directory. For - example, if the _BCL method is present for an ACPI namespace node, a - struct acpi_device object with LNXVIDEO 'bus_id' will be created for - it. - - The third column of the above table indicates which ACPI System - Description Tables contain information used for the creation of the - struct acpi_device objects represented by the given row (xSDT means DSDT - or SSDT). - - The forth column of the above table indicates the 'bus_id' generation - rule of the struct acpi_device object: - _HID: - _HID in the last column of the table means that the object's bus_id - is derived from the _HID/_CID identification objects present under - the corresponding ACPI namespace node. The object's sysfs directory - will then contain the 'hid' and 'modalias' attributes that can be - used to retrieve the _HID and _CIDs of that object. - LNXxxxxx: - The 'modalias' attribute is also present for struct acpi_device - objects having bus_id of the "LNXxxxxx" form (pseudo devices), in - which cases it contains the bus_id string itself. - device: - 'device' in the last column of the table indicates that the object's - bus_id cannot be determined from _HID/_CID of the corresponding - ACPI namespace node, although that object represents a device (for - example, it may be a PCI device with _ADR defined and without _HID - or _CID). In that case the string 'device' will be used as the - object's bus_id. - - -4. Linux ACPI Physical Device Glue - - ACPI device (i.e. struct acpi_device) objects may be linked to other - objects in the Linux' device hierarchy that represent "physical" devices - (for example, devices on the PCI bus). If that happens, it means that - the ACPI device object is a "companion" of a device otherwise - represented in a different way and is used (1) to provide configuration - information on that device which cannot be obtained by other means and - (2) to do specific things to the device with the help of its ACPI - control methods. One ACPI device object may be linked this way to - multiple "physical" devices. - - If an ACPI device object is linked to a "physical" device, its sysfs - directory contains the "physical_node" symbolic link to the sysfs - directory of the target device object. In turn, the target device's - sysfs directory will then contain the "firmware_node" symbolic link to - the sysfs directory of the companion ACPI device object. - The linking mechanism relies on device identification provided by the - ACPI namespace. For example, if there's an ACPI namespace object - representing a PCI device (i.e. a device object under an ACPI namespace - object representing a PCI bridge) whose _ADR returns 0x00020000 and the - bus number of the parent PCI bridge is 0, the sysfs directory - representing the struct acpi_device object created for that ACPI - namespace object will contain the 'physical_node' symbolic link to the - /sys/devices/pci0000:00/0000:00:02:0/ sysfs directory of the - corresponding PCI device. - - The linking mechanism is generally bus-specific. The core of its - implementation is located in the drivers/acpi/glue.c file, but there are - complementary parts depending on the bus types in question located - elsewhere. For example, the PCI-specific part of it is located in - drivers/pci/pci-acpi.c. - - -5. Example Linux ACPI Device Tree - - The sysfs hierarchy of struct acpi_device objects corresponding to the - example ACPI namespace illustrated in Figure 2 with the addition of - fixed PWR_BUTTON/SLP_BUTTON devices is shown below. - - +--------------+---+-----------------+ - | LNXSYSTEM:00 | \ | acpi:LNXSYSTEM: | - +--------------+---+-----------------+ - | - | +-------------+-----+----------------+ - +-| LNXPWRBN:00 | N/A | acpi:LNXPWRBN: | - | +-------------+-----+----------------+ - | - | +-------------+-----+----------------+ - +-| LNXSLPBN:00 | N/A | acpi:LNXSLPBN: | - | +-------------+-----+----------------+ - | - | +-----------+------------+--------------+ - +-| LNXCPU:00 | \_PR_.CPU0 | acpi:LNXCPU: | - | +-----------+------------+--------------+ - | - | +-------------+-------+----------------+ - +-| LNXSYBUS:00 | \_SB_ | acpi:LNXSYBUS: | - | +-------------+-------+----------------+ - | | - | | +- - - - - - - +- - - - - - +- - - - - - - -+ - | +-| PNP0C0D:00 | \_SB_.LID0 | acpi:PNP0C0D: | - | | +- - - - - - - +- - - - - - +- - - - - - - -+ - | | - | | +------------+------------+-----------------------+ - | +-| PNP0A08:00 | \_SB_.PCI0 | acpi:PNP0A08:PNP0A03: | - | +------------+------------+-----------------------+ - | | - | | +-----------+-----------------+-----+ - | +-| device:00 | \_SB_.PCI0.RP03 | N/A | - | | +-----------+-----------------+-----+ - | | | - | | | +-------------+----------------------+----------------+ - | | +-| LNXPOWER:00 | \_SB_.PCI0.RP03.PXP3 | acpi:LNXPOWER: | - | | +-------------+----------------------+----------------+ - | | - | | +-------------+-----------------+----------------+ - | +-| LNXVIDEO:00 | \_SB_.PCI0.GFX0 | acpi:LNXVIDEO: | - | +-------------+-----------------+----------------+ - | | - | | +-----------+-----------------+-----+ - | +-| device:01 | \_SB_.PCI0.DD01 | N/A | - | +-----------+-----------------+-----+ - | - | +-------------+-------+----------------+ - +-| LNXSYBUS:01 | \_TZ_ | acpi:LNXSYBUS: | - +-------------+-------+----------------+ - | - | +-------------+------------+----------------+ - +-| LNXPOWER:0a | \_TZ_.FN00 | acpi:LNXPOWER: | - | +-------------+------------+----------------+ - | - | +------------+------------+---------------+ - +-| PNP0C0B:00 | \_TZ_.FAN0 | acpi:PNP0C0B: | - | +------------+------------+---------------+ - | - | +-------------+------------+----------------+ - +-| LNXTHERM:00 | \_TZ_.TZ00 | acpi:LNXTHERM: | - +-------------+------------+----------------+ - - Figure 3. Example Linux ACPI Device Tree - - NOTE: Each node is represented as "object/path/modalias", where: - 1. 'object' is the name of the object's directory in sysfs. - 2. 'path' is the ACPI namespace path of the corresponding - ACPI namespace object, as returned by the object's 'path' - sysfs attribute. - 3. 'modalias' is the value of the object's 'modalias' sysfs - attribute (as described earlier in this document). - NOTE: N/A indicates the device object does not have the 'path' or the - 'modalias' attribute. diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index 0ec7d072ba22..210ad8acd6df 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -7,3 +7,4 @@ ACPI Support .. toctree:: :maxdepth: 1 + namespace diff --git a/Documentation/firmware-guide/acpi/namespace.rst b/Documentation/firmware-guide/acpi/namespace.rst new file mode 100644 index 000000000000..835521baeb89 --- /dev/null +++ b/Documentation/firmware-guide/acpi/namespace.rst @@ -0,0 +1,400 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +=================================================== +ACPI Device Tree - Representation of ACPI Namespace +=================================================== + +:Copyright: |copy| 2013, Intel Corporation + +:Author: Lv Zheng + +:Credit: Thanks for the help from Zhang Rui and + Rafael J.Wysocki . + +Abstract +======== +The Linux ACPI subsystem converts ACPI namespace objects into a Linux +device tree under the /sys/devices/LNXSYSTEM:00 and updates it upon +receiving ACPI hotplug notification events. For each device object +in this hierarchy there is a corresponding symbolic link in the +/sys/bus/acpi/devices. + +This document illustrates the structure of the ACPI device tree. + +ACPI Definition Blocks +====================== + +The ACPI firmware sets up RSDP (Root System Description Pointer) in the +system memory address space pointing to the XSDT (Extended System +Description Table). The XSDT always points to the FADT (Fixed ACPI +Description Table) using its first entry, the data within the FADT +includes various fixed-length entries that describe fixed ACPI features +of the hardware. The FADT contains a pointer to the DSDT +(Differentiated System Descripition Table). The XSDT also contains +entries pointing to possibly multiple SSDTs (Secondary System +Description Table). + +The DSDT and SSDT data is organized in data structures called definition +blocks that contain definitions of various objects, including ACPI +control methods, encoded in AML (ACPI Machine Language). The data block +of the DSDT along with the contents of SSDTs represents a hierarchical +data structure called the ACPI namespace whose topology reflects the +structure of the underlying hardware platform. + +The relationships between ACPI System Definition Tables described above +are illustrated in the following diagram:: + + +---------+ +-------+ +--------+ +------------------------+ + | RSDP | +->| XSDT | +->| FADT | | +-------------------+ | + +---------+ | +-------+ | +--------+ +-|->| DSDT | | + | Pointer | | | Entry |-+ | ...... | | | +-------------------+ | + +---------+ | +-------+ | X_DSDT |--+ | | Definition Blocks | | + | Pointer |-+ | ..... | | ...... | | +-------------------+ | + +---------+ +-------+ +--------+ | +-------------------+ | + | Entry |------------------|->| SSDT | | + +- - - -+ | +-------------------| | + | Entry | - - - - - - - -+ | | Definition Blocks | | + +- - - -+ | | +-------------------+ | + | | +- - - - - - - - - -+ | + +-|->| SSDT | | + | +-------------------+ | + | | Definition Blocks | | + | +- - - - - - - - - -+ | + +------------------------+ + | + OSPM Loading | + \|/ + +----------------+ + | ACPI Namespace | + +----------------+ + + Figure 1. ACPI Definition Blocks + +.. note:: RSDP can also contain a pointer to the RSDT (Root System + Description Table). Platforms provide RSDT to enable + compatibility with ACPI 1.0 operating systems. The OS is expected + to use XSDT, if present. + + +Example ACPI Namespace +====================== + +All definition blocks are loaded into a single namespace. The namespace +is a hierarchy of objects identified by names and paths. +The following naming conventions apply to object names in the ACPI +namespace: + + 1. All names are 32 bits long. + 2. The first byte of a name must be one of 'A' - 'Z', '_'. + 3. Each of the remaining bytes of a name must be one of 'A' - 'Z', '0' + - '9', '_'. + 4. Names starting with '_' are reserved by the ACPI specification. + 5. The '\' symbol represents the root of the namespace (i.e. names + prepended with '\' are relative to the namespace root). + 6. The '^' symbol represents the parent of the current namespace node + (i.e. names prepended with '^' are relative to the parent of the + current namespace node). + +The figure below shows an example ACPI namespace:: + + +------+ + | \ | Root + +------+ + | + | +------+ + +-| _PR | Scope(_PR): the processor namespace + | +------+ + | | + | | +------+ + | +-| CPU0 | Processor(CPU0): the first processor + | +------+ + | + | +------+ + +-| _SB | Scope(_SB): the system bus namespace + | +------+ + | | + | | +------+ + | +-| LID0 | Device(LID0); the lid device + | | +------+ + | | | + | | | +------+ + | | +-| _HID | Name(_HID, "PNP0C0D"): the hardware ID + | | | +------+ + | | | + | | | +------+ + | | +-| _STA | Method(_STA): the status control method + | | +------+ + | | + | | +------+ + | +-| PCI0 | Device(PCI0); the PCI root bridge + | +------+ + | | + | | +------+ + | +-| _HID | Name(_HID, "PNP0A08"): the hardware ID + | | +------+ + | | + | | +------+ + | +-| _CID | Name(_CID, "PNP0A03"): the compatible ID + | | +------+ + | | + | | +------+ + | +-| RP03 | Scope(RP03): the PCI0 power scope + | | +------+ + | | | + | | | +------+ + | | +-| PXP3 | PowerResource(PXP3): the PCI0 power resource + | | +------+ + | | + | | +------+ + | +-| GFX0 | Device(GFX0): the graphics adapter + | +------+ + | | + | | +------+ + | +-| _ADR | Name(_ADR, 0x00020000): the PCI bus address + | | +------+ + | | + | | +------+ + | +-| DD01 | Device(DD01): the LCD output device + | +------+ + | | + | | +------+ + | +-| _BCL | Method(_BCL): the backlight control method + | +------+ + | + | +------+ + +-| _TZ | Scope(_TZ): the thermal zone namespace + | +------+ + | | + | | +------+ + | +-| FN00 | PowerResource(FN00): the FAN0 power resource + | | +------+ + | | + | | +------+ + | +-| FAN0 | Device(FAN0): the FAN0 cooling device + | | +------+ + | | | + | | | +------+ + | | +-| _HID | Name(_HID, "PNP0A0B"): the hardware ID + | | +------+ + | | + | | +------+ + | +-| TZ00 | ThermalZone(TZ00); the FAN thermal zone + | +------+ + | + | +------+ + +-| _GPE | Scope(_GPE): the GPE namespace + +------+ + + Figure 2. Example ACPI Namespace + + +Linux ACPI Device Objects +========================= + +The Linux kernel's core ACPI subsystem creates struct acpi_device +objects for ACPI namespace objects representing devices, power resources +processors, thermal zones. Those objects are exported to user space via +sysfs as directories in the subtree under /sys/devices/LNXSYSTM:00. The +format of their names is , where 'bus_id' refers to the +ACPI namespace representation of the given object and 'instance' is used +for distinguishing different object of the same 'bus_id' (it is +two-digit decimal representation of an unsigned integer). + +The value of 'bus_id' depends on the type of the object whose name it is +part of as listed in the table below:: + + +---+-----------------+-------+----------+ + | | Object/Feature | Table | bus_id | + +---+-----------------+-------+----------+ + | N | Root | xSDT | LNXSYSTM | + +---+-----------------+-------+----------+ + | N | Device | xSDT | _HID | + +---+-----------------+-------+----------+ + | N | Processor | xSDT | LNXCPU | + +---+-----------------+-------+----------+ + | N | ThermalZone | xSDT | LNXTHERM | + +---+-----------------+-------+----------+ + | N | PowerResource | xSDT | LNXPOWER | + +---+-----------------+-------+----------+ + | N | Other Devices | xSDT | device | + +---+-----------------+-------+----------+ + | F | PWR_BUTTON | FADT | LNXPWRBN | + +---+-----------------+-------+----------+ + | F | SLP_BUTTON | FADT | LNXSLPBN | + +---+-----------------+-------+----------+ + | M | Video Extension | xSDT | LNXVIDEO | + +---+-----------------+-------+----------+ + | M | ATA Controller | xSDT | LNXIOBAY | + +---+-----------------+-------+----------+ + | M | Docking Station | xSDT | LNXDOCK | + +---+-----------------+-------+----------+ + + Table 1. ACPI Namespace Objects Mapping + +The following rules apply when creating struct acpi_device objects on +the basis of the contents of ACPI System Description Tables (as +indicated by the letter in the first column and the notation in the +second column of the table above): + + N: + The object's source is an ACPI namespace node (as indicated by the + named object's type in the second column). In that case the object's + directory in sysfs will contain the 'path' attribute whose value is + the full path to the node from the namespace root. + F: + The struct acpi_device object is created for a fixed hardware + feature (as indicated by the fixed feature flag's name in the second + column), so its sysfs directory will not contain the 'path' + attribute. + M: + The struct acpi_device object is created for an ACPI namespace node + with specific control methods (as indicated by the ACPI defined + device's type in the second column). The 'path' attribute containing + its namespace path will be present in its sysfs directory. For + example, if the _BCL method is present for an ACPI namespace node, a + struct acpi_device object with LNXVIDEO 'bus_id' will be created for + it. + +The third column of the above table indicates which ACPI System +Description Tables contain information used for the creation of the +struct acpi_device objects represented by the given row (xSDT means DSDT +or SSDT). + +The forth column of the above table indicates the 'bus_id' generation +rule of the struct acpi_device object: + + _HID: + _HID in the last column of the table means that the object's bus_id + is derived from the _HID/_CID identification objects present under + the corresponding ACPI namespace node. The object's sysfs directory + will then contain the 'hid' and 'modalias' attributes that can be + used to retrieve the _HID and _CIDs of that object. + LNXxxxxx: + The 'modalias' attribute is also present for struct acpi_device + objects having bus_id of the "LNXxxxxx" form (pseudo devices), in + which cases it contains the bus_id string itself. + device: + 'device' in the last column of the table indicates that the object's + bus_id cannot be determined from _HID/_CID of the corresponding + ACPI namespace node, although that object represents a device (for + example, it may be a PCI device with _ADR defined and without _HID + or _CID). In that case the string 'device' will be used as the + object's bus_id. + + +Linux ACPI Physical Device Glue +=============================== + +ACPI device (i.e. struct acpi_device) objects may be linked to other +objects in the Linux' device hierarchy that represent "physical" devices +(for example, devices on the PCI bus). If that happens, it means that +the ACPI device object is a "companion" of a device otherwise +represented in a different way and is used (1) to provide configuration +information on that device which cannot be obtained by other means and +(2) to do specific things to the device with the help of its ACPI +control methods. One ACPI device object may be linked this way to +multiple "physical" devices. + +If an ACPI device object is linked to a "physical" device, its sysfs +directory contains the "physical_node" symbolic link to the sysfs +directory of the target device object. In turn, the target device's +sysfs directory will then contain the "firmware_node" symbolic link to +the sysfs directory of the companion ACPI device object. +The linking mechanism relies on device identification provided by the +ACPI namespace. For example, if there's an ACPI namespace object +representing a PCI device (i.e. a device object under an ACPI namespace +object representing a PCI bridge) whose _ADR returns 0x00020000 and the +bus number of the parent PCI bridge is 0, the sysfs directory +representing the struct acpi_device object created for that ACPI +namespace object will contain the 'physical_node' symbolic link to the +/sys/devices/pci0000:00/0000:00:02:0/ sysfs directory of the +corresponding PCI device. + +The linking mechanism is generally bus-specific. The core of its +implementation is located in the drivers/acpi/glue.c file, but there are +complementary parts depending on the bus types in question located +elsewhere. For example, the PCI-specific part of it is located in +drivers/pci/pci-acpi.c. + + +Example Linux ACPI Device Tree +================================= + +The sysfs hierarchy of struct acpi_device objects corresponding to the +example ACPI namespace illustrated in Figure 2 with the addition of +fixed PWR_BUTTON/SLP_BUTTON devices is shown below:: + + +--------------+---+-----------------+ + | LNXSYSTEM:00 | \ | acpi:LNXSYSTEM: | + +--------------+---+-----------------+ + | + | +-------------+-----+----------------+ + +-| LNXPWRBN:00 | N/A | acpi:LNXPWRBN: | + | +-------------+-----+----------------+ + | + | +-------------+-----+----------------+ + +-| LNXSLPBN:00 | N/A | acpi:LNXSLPBN: | + | +-------------+-----+----------------+ + | + | +-----------+------------+--------------+ + +-| LNXCPU:00 | \_PR_.CPU0 | acpi:LNXCPU: | + | +-----------+------------+--------------+ + | + | +-------------+-------+----------------+ + +-| LNXSYBUS:00 | \_SB_ | acpi:LNXSYBUS: | + | +-------------+-------+----------------+ + | | + | | +- - - - - - - +- - - - - - +- - - - - - - -+ + | +-| PNP0C0D:00 | \_SB_.LID0 | acpi:PNP0C0D: | + | | +- - - - - - - +- - - - - - +- - - - - - - -+ + | | + | | +------------+------------+-----------------------+ + | +-| PNP0A08:00 | \_SB_.PCI0 | acpi:PNP0A08:PNP0A03: | + | +------------+------------+-----------------------+ + | | + | | +-----------+-----------------+-----+ + | +-| device:00 | \_SB_.PCI0.RP03 | N/A | + | | +-----------+-----------------+-----+ + | | | + | | | +-------------+----------------------+----------------+ + | | +-| LNXPOWER:00 | \_SB_.PCI0.RP03.PXP3 | acpi:LNXPOWER: | + | | +-------------+----------------------+----------------+ + | | + | | +-------------+-----------------+----------------+ + | +-| LNXVIDEO:00 | \_SB_.PCI0.GFX0 | acpi:LNXVIDEO: | + | +-------------+-----------------+----------------+ + | | + | | +-----------+-----------------+-----+ + | +-| device:01 | \_SB_.PCI0.DD01 | N/A | + | +-----------+-----------------+-----+ + | + | +-------------+-------+----------------+ + +-| LNXSYBUS:01 | \_TZ_ | acpi:LNXSYBUS: | + +-------------+-------+----------------+ + | + | +-------------+------------+----------------+ + +-| LNXPOWER:0a | \_TZ_.FN00 | acpi:LNXPOWER: | + | +-------------+------------+----------------+ + | + | +------------+------------+---------------+ + +-| PNP0C0B:00 | \_TZ_.FAN0 | acpi:PNP0C0B: | + | +------------+------------+---------------+ + | + | +-------------+------------+----------------+ + +-| LNXTHERM:00 | \_TZ_.TZ00 | acpi:LNXTHERM: | + +-------------+------------+----------------+ + + Figure 3. Example Linux ACPI Device Tree + +.. note:: Each node is represented as "object/path/modalias", where: + + 1. 'object' is the name of the object's directory in sysfs. + 2. 'path' is the ACPI namespace path of the corresponding + ACPI namespace object, as returned by the object's 'path' + sysfs attribute. + 3. 'modalias' is the value of the object's 'modalias' sysfs + attribute (as described earlier in this document). + +.. note:: N/A indicates the device object does not have the 'path' or the + 'modalias' attribute. -- cgit v1.2.3-59-g8ed1b From c24bc66e8157ca4956b8be1ed62493d70dfdb547 Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 25 Apr 2019 01:52:45 +0800 Subject: Documentation: ACPI: move enumeration.txt to firmware-guide/acpi and convert to reST This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/enumeration.txt | 452 --------------------- Documentation/firmware-guide/acpi/enumeration.rst | 463 ++++++++++++++++++++++ Documentation/firmware-guide/acpi/index.rst | 1 + 3 files changed, 464 insertions(+), 452 deletions(-) delete mode 100644 Documentation/acpi/enumeration.txt create mode 100644 Documentation/firmware-guide/acpi/enumeration.rst (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/acpi/enumeration.txt b/Documentation/acpi/enumeration.txt deleted file mode 100644 index 1395b844649c..000000000000 --- a/Documentation/acpi/enumeration.txt +++ /dev/null @@ -1,452 +0,0 @@ -ACPI based device enumeration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -ACPI 5 introduced a set of new resources (UartTSerialBus, I2cSerialBus, -SpiSerialBus, GpioIo and GpioInt) which can be used in enumerating slave -devices behind serial bus controllers. - -In addition we are starting to see peripherals integrated in the -SoC/Chipset to appear only in ACPI namespace. These are typically devices -that are accessed through memory-mapped registers. - -In order to support this and re-use the existing drivers as much as -possible we decided to do following: - - o Devices that have no bus connector resource are represented as - platform devices. - - o Devices behind real busses where there is a connector resource - are represented as struct spi_device or struct i2c_device - (standard UARTs are not busses so there is no struct uart_device). - -As both ACPI and Device Tree represent a tree of devices (and their -resources) this implementation follows the Device Tree way as much as -possible. - -The ACPI implementation enumerates devices behind busses (platform, SPI and -I2C), creates the physical devices and binds them to their ACPI handle in -the ACPI namespace. - -This means that when ACPI_HANDLE(dev) returns non-NULL the device was -enumerated from ACPI namespace. This handle can be used to extract other -device-specific configuration. There is an example of this below. - -Platform bus support -~~~~~~~~~~~~~~~~~~~~ -Since we are using platform devices to represent devices that are not -connected to any physical bus we only need to implement a platform driver -for the device and add supported ACPI IDs. If this same IP-block is used on -some other non-ACPI platform, the driver might work out of the box or needs -some minor changes. - -Adding ACPI support for an existing driver should be pretty -straightforward. Here is the simplest example: - - #ifdef CONFIG_ACPI - static const struct acpi_device_id mydrv_acpi_match[] = { - /* ACPI IDs here */ - { } - }; - MODULE_DEVICE_TABLE(acpi, mydrv_acpi_match); - #endif - - static struct platform_driver my_driver = { - ... - .driver = { - .acpi_match_table = ACPI_PTR(mydrv_acpi_match), - }, - }; - -If the driver needs to perform more complex initialization like getting and -configuring GPIOs it can get its ACPI handle and extract this information -from ACPI tables. - -DMA support -~~~~~~~~~~~ -DMA controllers enumerated via ACPI should be registered in the system to -provide generic access to their resources. For example, a driver that would -like to be accessible to slave devices via generic API call -dma_request_slave_channel() must register itself at the end of the probe -function like this: - - err = devm_acpi_dma_controller_register(dev, xlate_func, dw); - /* Handle the error if it's not a case of !CONFIG_ACPI */ - -and implement custom xlate function if needed (usually acpi_dma_simple_xlate() -is enough) which converts the FixedDMA resource provided by struct -acpi_dma_spec into the corresponding DMA channel. A piece of code for that case -could look like: - - #ifdef CONFIG_ACPI - struct filter_args { - /* Provide necessary information for the filter_func */ - ... - }; - - static bool filter_func(struct dma_chan *chan, void *param) - { - /* Choose the proper channel */ - ... - } - - static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec, - struct acpi_dma *adma) - { - dma_cap_mask_t cap; - struct filter_args args; - - /* Prepare arguments for filter_func */ - ... - return dma_request_channel(cap, filter_func, &args); - } - #else - static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec, - struct acpi_dma *adma) - { - return NULL; - } - #endif - -dma_request_slave_channel() will call xlate_func() for each registered DMA -controller. In the xlate function the proper channel must be chosen based on -information in struct acpi_dma_spec and the properties of the controller -provided by struct acpi_dma. - -Clients must call dma_request_slave_channel() with the string parameter that -corresponds to a specific FixedDMA resource. By default "tx" means the first -entry of the FixedDMA resource array, "rx" means the second entry. The table -below shows a layout: - - Device (I2C0) - { - ... - Method (_CRS, 0, NotSerialized) - { - Name (DBUF, ResourceTemplate () - { - FixedDMA (0x0018, 0x0004, Width32bit, _Y48) - FixedDMA (0x0019, 0x0005, Width32bit, ) - }) - ... - } - } - -So, the FixedDMA with request line 0x0018 is "tx" and next one is "rx" in -this example. - -In robust cases the client unfortunately needs to call -acpi_dma_request_slave_chan_by_index() directly and therefore choose the -specific FixedDMA resource by its index. - -SPI serial bus support -~~~~~~~~~~~~~~~~~~~~~~ -Slave devices behind SPI bus have SpiSerialBus resource attached to them. -This is extracted automatically by the SPI core and the slave devices are -enumerated once spi_register_master() is called by the bus driver. - -Here is what the ACPI namespace for a SPI slave might look like: - - Device (EEP0) - { - Name (_ADR, 1) - Name (_CID, Package() { - "ATML0025", - "AT25", - }) - ... - Method (_CRS, 0, NotSerialized) - { - SPISerialBus(1, PolarityLow, FourWireMode, 8, - ControllerInitiated, 1000000, ClockPolarityLow, - ClockPhaseFirst, "\\_SB.PCI0.SPI1",) - } - ... - -The SPI device drivers only need to add ACPI IDs in a similar way than with -the platform device drivers. Below is an example where we add ACPI support -to at25 SPI eeprom driver (this is meant for the above ACPI snippet): - - #ifdef CONFIG_ACPI - static const struct acpi_device_id at25_acpi_match[] = { - { "AT25", 0 }, - { }, - }; - MODULE_DEVICE_TABLE(acpi, at25_acpi_match); - #endif - - static struct spi_driver at25_driver = { - .driver = { - ... - .acpi_match_table = ACPI_PTR(at25_acpi_match), - }, - }; - -Note that this driver actually needs more information like page size of the -eeprom etc. but at the time writing this there is no standard way of -passing those. One idea is to return this in _DSM method like: - - Device (EEP0) - { - ... - Method (_DSM, 4, NotSerialized) - { - Store (Package (6) - { - "byte-len", 1024, - "addr-mode", 2, - "page-size, 32 - }, Local0) - - // Check UUIDs etc. - - Return (Local0) - } - -Then the at25 SPI driver can get this configuration by calling _DSM on its -ACPI handle like: - - struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL }; - struct acpi_object_list input; - acpi_status status; - - /* Fill in the input buffer */ - - status = acpi_evaluate_object(ACPI_HANDLE(&spi->dev), "_DSM", - &input, &output); - if (ACPI_FAILURE(status)) - /* Handle the error */ - - /* Extract the data here */ - - kfree(output.pointer); - -I2C serial bus support -~~~~~~~~~~~~~~~~~~~~~~ -The slaves behind I2C bus controller only need to add the ACPI IDs like -with the platform and SPI drivers. The I2C core automatically enumerates -any slave devices behind the controller device once the adapter is -registered. - -Below is an example of how to add ACPI support to the existing mpu3050 -input driver: - - #ifdef CONFIG_ACPI - static const struct acpi_device_id mpu3050_acpi_match[] = { - { "MPU3050", 0 }, - { }, - }; - MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match); - #endif - - static struct i2c_driver mpu3050_i2c_driver = { - .driver = { - .name = "mpu3050", - .owner = THIS_MODULE, - .pm = &mpu3050_pm, - .of_match_table = mpu3050_of_match, - .acpi_match_table = ACPI_PTR(mpu3050_acpi_match), - }, - .probe = mpu3050_probe, - .remove = mpu3050_remove, - .id_table = mpu3050_ids, - }; - -GPIO support -~~~~~~~~~~~~ -ACPI 5 introduced two new resources to describe GPIO connections: GpioIo -and GpioInt. These resources can be used to pass GPIO numbers used by -the device to the driver. ACPI 5.1 extended this with _DSD (Device -Specific Data) which made it possible to name the GPIOs among other things. - -For example: - -Device (DEV) -{ - Method (_CRS, 0, NotSerialized) - { - Name (SBUF, ResourceTemplate() - { - ... - // Used to power on/off the device - GpioIo (Exclusive, PullDefault, 0x0000, 0x0000, - IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0", - 0x00, ResourceConsumer,,) - { - // Pin List - 0x0055 - } - - // Interrupt for the device - GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone, - 0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,) - { - // Pin list - 0x0058 - } - - ... - - } - - Return (SBUF) - } - - // ACPI 5.1 _DSD used for naming the GPIOs - Name (_DSD, Package () - { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () - { - Package () {"power-gpios", Package() {^DEV, 0, 0, 0 }}, - Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }}, - } - }) - ... - -These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0" -specifies the path to the controller. In order to use these GPIOs in Linux -we need to translate them to the corresponding Linux GPIO descriptors. - -There is a standard GPIO API for that and is documented in -Documentation/gpio/. - -In the above example we can get the corresponding two GPIO descriptors with -a code like this: - - #include - ... - - struct gpio_desc *irq_desc, *power_desc; - - irq_desc = gpiod_get(dev, "irq"); - if (IS_ERR(irq_desc)) - /* handle error */ - - power_desc = gpiod_get(dev, "power"); - if (IS_ERR(power_desc)) - /* handle error */ - - /* Now we can use the GPIO descriptors */ - -There are also devm_* versions of these functions which release the -descriptors once the device is released. - -See Documentation/acpi/gpio-properties.txt for more information about the -_DSD binding related to GPIOs. - -MFD devices -~~~~~~~~~~~ -The MFD devices register their children as platform devices. For the child -devices there needs to be an ACPI handle that they can use to reference -parts of the ACPI namespace that relate to them. In the Linux MFD subsystem -we provide two ways: - - o The children share the parent ACPI handle. - o The MFD cell can specify the ACPI id of the device. - -For the first case, the MFD drivers do not need to do anything. The -resulting child platform device will have its ACPI_COMPANION() set to point -to the parent device. - -If the ACPI namespace has a device that we can match using an ACPI id or ACPI -adr, the cell should be set like: - - static struct mfd_cell_acpi_match my_subdevice_cell_acpi_match = { - .pnpid = "XYZ0001", - .adr = 0, - }; - - static struct mfd_cell my_subdevice_cell = { - .name = "my_subdevice", - /* set the resources relative to the parent */ - .acpi_match = &my_subdevice_cell_acpi_match, - }; - -The ACPI id "XYZ0001" is then used to lookup an ACPI device directly under -the MFD device and if found, that ACPI companion device is bound to the -resulting child platform device. - -Device Tree namespace link device ID -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Device Tree protocol uses device identification based on the "compatible" -property whose value is a string or an array of strings recognized as device -identifiers by drivers and the driver core. The set of all those strings may be -regarded as a device identification namespace analogous to the ACPI/PNP device -ID namespace. Consequently, in principle it should not be necessary to allocate -a new (and arguably redundant) ACPI/PNP device ID for a devices with an existing -identification string in the Device Tree (DT) namespace, especially if that ID -is only needed to indicate that a given device is compatible with another one, -presumably having a matching driver in the kernel already. - -In ACPI, the device identification object called _CID (Compatible ID) is used to -list the IDs of devices the given one is compatible with, but those IDs must -belong to one of the namespaces prescribed by the ACPI specification (see -Section 6.1.2 of ACPI 6.0 for details) and the DT namespace is not one of them. -Moreover, the specification mandates that either a _HID or an _ADR identification -object be present for all ACPI objects representing devices (Section 6.1 of ACPI -6.0). For non-enumerable bus types that object must be _HID and its value must -be a device ID from one of the namespaces prescribed by the specification too. - -The special DT namespace link device ID, PRP0001, provides a means to use the -existing DT-compatible device identification in ACPI and to satisfy the above -requirements following from the ACPI specification at the same time. Namely, -if PRP0001 is returned by _HID, the ACPI subsystem will look for the -"compatible" property in the device object's _DSD and will use the value of that -property to identify the corresponding device in analogy with the original DT -device identification algorithm. If the "compatible" property is not present -or its value is not valid, the device will not be enumerated by the ACPI -subsystem. Otherwise, it will be enumerated automatically as a platform device -(except when an I2C or SPI link from the device to its parent is present, in -which case the ACPI core will leave the device enumeration to the parent's -driver) and the identification strings from the "compatible" property value will -be used to find a driver for the device along with the device IDs listed by _CID -(if present). - -Analogously, if PRP0001 is present in the list of device IDs returned by _CID, -the identification strings listed by the "compatible" property value (if present -and valid) will be used to look for a driver matching the device, but in that -case their relative priority with respect to the other device IDs listed by -_HID and _CID depends on the position of PRP0001 in the _CID return package. -Specifically, the device IDs returned by _HID and preceding PRP0001 in the _CID -return package will be checked first. Also in that case the bus type the device -will be enumerated to depends on the device ID returned by _HID. - -For example, the following ACPI sample might be used to enumerate an lm75-type -I2C temperature sensor and match it to the driver using the Device Tree -namespace link: - - Device (TMP0) - { - Name (_HID, "PRP0001") - Name (_DSD, Package() { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () { - Package (2) { "compatible", "ti,tmp75" }, - } - }) - Method (_CRS, 0, Serialized) - { - Name (SBUF, ResourceTemplate () - { - I2cSerialBusV2 (0x48, ControllerInitiated, - 400000, AddressingMode7Bit, - "\\_SB.PCI0.I2C1", 0x00, - ResourceConsumer, , Exclusive,) - }) - Return (SBUF) - } - } - -It is valid to define device objects with a _HID returning PRP0001 and without -the "compatible" property in the _DSD or a _CID as long as one of their -ancestors provides a _DSD with a valid "compatible" property. Such device -objects are then simply regarded as additional "blocks" providing hierarchical -configuration information to the driver of the composite ancestor device. - -However, PRP0001 can only be returned from either _HID or _CID of a device -object if all of the properties returned by the _DSD associated with it (either -the _DSD of the device object itself or the _DSD of its ancestor in the -"composite device" case described above) can be used in the ACPI environment. -Otherwise, the _DSD itself is regarded as invalid and therefore the "compatible" -property returned by it is meaningless. - -Refer to DSD-properties-rules.txt for more information. diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst new file mode 100644 index 000000000000..6b32b7be8c85 --- /dev/null +++ b/Documentation/firmware-guide/acpi/enumeration.rst @@ -0,0 +1,463 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================= +ACPI Based Device Enumeration +============================= + +ACPI 5 introduced a set of new resources (UartTSerialBus, I2cSerialBus, +SpiSerialBus, GpioIo and GpioInt) which can be used in enumerating slave +devices behind serial bus controllers. + +In addition we are starting to see peripherals integrated in the +SoC/Chipset to appear only in ACPI namespace. These are typically devices +that are accessed through memory-mapped registers. + +In order to support this and re-use the existing drivers as much as +possible we decided to do following: + + - Devices that have no bus connector resource are represented as + platform devices. + + - Devices behind real busses where there is a connector resource + are represented as struct spi_device or struct i2c_device + (standard UARTs are not busses so there is no struct uart_device). + +As both ACPI and Device Tree represent a tree of devices (and their +resources) this implementation follows the Device Tree way as much as +possible. + +The ACPI implementation enumerates devices behind busses (platform, SPI and +I2C), creates the physical devices and binds them to their ACPI handle in +the ACPI namespace. + +This means that when ACPI_HANDLE(dev) returns non-NULL the device was +enumerated from ACPI namespace. This handle can be used to extract other +device-specific configuration. There is an example of this below. + +Platform bus support +==================== + +Since we are using platform devices to represent devices that are not +connected to any physical bus we only need to implement a platform driver +for the device and add supported ACPI IDs. If this same IP-block is used on +some other non-ACPI platform, the driver might work out of the box or needs +some minor changes. + +Adding ACPI support for an existing driver should be pretty +straightforward. Here is the simplest example:: + + #ifdef CONFIG_ACPI + static const struct acpi_device_id mydrv_acpi_match[] = { + /* ACPI IDs here */ + { } + }; + MODULE_DEVICE_TABLE(acpi, mydrv_acpi_match); + #endif + + static struct platform_driver my_driver = { + ... + .driver = { + .acpi_match_table = ACPI_PTR(mydrv_acpi_match), + }, + }; + +If the driver needs to perform more complex initialization like getting and +configuring GPIOs it can get its ACPI handle and extract this information +from ACPI tables. + +DMA support +=========== + +DMA controllers enumerated via ACPI should be registered in the system to +provide generic access to their resources. For example, a driver that would +like to be accessible to slave devices via generic API call +dma_request_slave_channel() must register itself at the end of the probe +function like this:: + + err = devm_acpi_dma_controller_register(dev, xlate_func, dw); + /* Handle the error if it's not a case of !CONFIG_ACPI */ + +and implement custom xlate function if needed (usually acpi_dma_simple_xlate() +is enough) which converts the FixedDMA resource provided by struct +acpi_dma_spec into the corresponding DMA channel. A piece of code for that case +could look like:: + + #ifdef CONFIG_ACPI + struct filter_args { + /* Provide necessary information for the filter_func */ + ... + }; + + static bool filter_func(struct dma_chan *chan, void *param) + { + /* Choose the proper channel */ + ... + } + + static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec, + struct acpi_dma *adma) + { + dma_cap_mask_t cap; + struct filter_args args; + + /* Prepare arguments for filter_func */ + ... + return dma_request_channel(cap, filter_func, &args); + } + #else + static struct dma_chan *xlate_func(struct acpi_dma_spec *dma_spec, + struct acpi_dma *adma) + { + return NULL; + } + #endif + +dma_request_slave_channel() will call xlate_func() for each registered DMA +controller. In the xlate function the proper channel must be chosen based on +information in struct acpi_dma_spec and the properties of the controller +provided by struct acpi_dma. + +Clients must call dma_request_slave_channel() with the string parameter that +corresponds to a specific FixedDMA resource. By default "tx" means the first +entry of the FixedDMA resource array, "rx" means the second entry. The table +below shows a layout:: + + Device (I2C0) + { + ... + Method (_CRS, 0, NotSerialized) + { + Name (DBUF, ResourceTemplate () + { + FixedDMA (0x0018, 0x0004, Width32bit, _Y48) + FixedDMA (0x0019, 0x0005, Width32bit, ) + }) + ... + } + } + +So, the FixedDMA with request line 0x0018 is "tx" and next one is "rx" in +this example. + +In robust cases the client unfortunately needs to call +acpi_dma_request_slave_chan_by_index() directly and therefore choose the +specific FixedDMA resource by its index. + +SPI serial bus support +====================== + +Slave devices behind SPI bus have SpiSerialBus resource attached to them. +This is extracted automatically by the SPI core and the slave devices are +enumerated once spi_register_master() is called by the bus driver. + +Here is what the ACPI namespace for a SPI slave might look like:: + + Device (EEP0) + { + Name (_ADR, 1) + Name (_CID, Package() { + "ATML0025", + "AT25", + }) + ... + Method (_CRS, 0, NotSerialized) + { + SPISerialBus(1, PolarityLow, FourWireMode, 8, + ControllerInitiated, 1000000, ClockPolarityLow, + ClockPhaseFirst, "\\_SB.PCI0.SPI1",) + } + ... + +The SPI device drivers only need to add ACPI IDs in a similar way than with +the platform device drivers. Below is an example where we add ACPI support +to at25 SPI eeprom driver (this is meant for the above ACPI snippet):: + + #ifdef CONFIG_ACPI + static const struct acpi_device_id at25_acpi_match[] = { + { "AT25", 0 }, + { }, + }; + MODULE_DEVICE_TABLE(acpi, at25_acpi_match); + #endif + + static struct spi_driver at25_driver = { + .driver = { + ... + .acpi_match_table = ACPI_PTR(at25_acpi_match), + }, + }; + +Note that this driver actually needs more information like page size of the +eeprom etc. but at the time writing this there is no standard way of +passing those. One idea is to return this in _DSM method like:: + + Device (EEP0) + { + ... + Method (_DSM, 4, NotSerialized) + { + Store (Package (6) + { + "byte-len", 1024, + "addr-mode", 2, + "page-size, 32 + }, Local0) + + // Check UUIDs etc. + + Return (Local0) + } + +Then the at25 SPI driver can get this configuration by calling _DSM on its +ACPI handle like:: + + struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL }; + struct acpi_object_list input; + acpi_status status; + + /* Fill in the input buffer */ + + status = acpi_evaluate_object(ACPI_HANDLE(&spi->dev), "_DSM", + &input, &output); + if (ACPI_FAILURE(status)) + /* Handle the error */ + + /* Extract the data here */ + + kfree(output.pointer); + +I2C serial bus support +====================== + +The slaves behind I2C bus controller only need to add the ACPI IDs like +with the platform and SPI drivers. The I2C core automatically enumerates +any slave devices behind the controller device once the adapter is +registered. + +Below is an example of how to add ACPI support to the existing mpu3050 +input driver:: + + #ifdef CONFIG_ACPI + static const struct acpi_device_id mpu3050_acpi_match[] = { + { "MPU3050", 0 }, + { }, + }; + MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match); + #endif + + static struct i2c_driver mpu3050_i2c_driver = { + .driver = { + .name = "mpu3050", + .owner = THIS_MODULE, + .pm = &mpu3050_pm, + .of_match_table = mpu3050_of_match, + .acpi_match_table = ACPI_PTR(mpu3050_acpi_match), + }, + .probe = mpu3050_probe, + .remove = mpu3050_remove, + .id_table = mpu3050_ids, + }; + +GPIO support +============ + +ACPI 5 introduced two new resources to describe GPIO connections: GpioIo +and GpioInt. These resources can be used to pass GPIO numbers used by +the device to the driver. ACPI 5.1 extended this with _DSD (Device +Specific Data) which made it possible to name the GPIOs among other things. + +For example:: + + Device (DEV) + { + Method (_CRS, 0, NotSerialized) + { + Name (SBUF, ResourceTemplate() + { + ... + // Used to power on/off the device + GpioIo (Exclusive, PullDefault, 0x0000, 0x0000, + IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0", + 0x00, ResourceConsumer,,) + { + // Pin List + 0x0055 + } + + // Interrupt for the device + GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone, + 0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,) + { + // Pin list + 0x0058 + } + + ... + + } + + Return (SBUF) + } + + // ACPI 5.1 _DSD used for naming the GPIOs + Name (_DSD, Package () + { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () + { + Package () {"power-gpios", Package() {^DEV, 0, 0, 0 }}, + Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }}, + } + }) + ... + +These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0" +specifies the path to the controller. In order to use these GPIOs in Linux +we need to translate them to the corresponding Linux GPIO descriptors. + +There is a standard GPIO API for that and is documented in +Documentation/gpio/. + +In the above example we can get the corresponding two GPIO descriptors with +a code like this:: + + #include + ... + + struct gpio_desc *irq_desc, *power_desc; + + irq_desc = gpiod_get(dev, "irq"); + if (IS_ERR(irq_desc)) + /* handle error */ + + power_desc = gpiod_get(dev, "power"); + if (IS_ERR(power_desc)) + /* handle error */ + + /* Now we can use the GPIO descriptors */ + +There are also devm_* versions of these functions which release the +descriptors once the device is released. + +See Documentation/acpi/gpio-properties.txt for more information about the +_DSD binding related to GPIOs. + +MFD devices +=========== + +The MFD devices register their children as platform devices. For the child +devices there needs to be an ACPI handle that they can use to reference +parts of the ACPI namespace that relate to them. In the Linux MFD subsystem +we provide two ways: + + - The children share the parent ACPI handle. + - The MFD cell can specify the ACPI id of the device. + +For the first case, the MFD drivers do not need to do anything. The +resulting child platform device will have its ACPI_COMPANION() set to point +to the parent device. + +If the ACPI namespace has a device that we can match using an ACPI id or ACPI +adr, the cell should be set like:: + + static struct mfd_cell_acpi_match my_subdevice_cell_acpi_match = { + .pnpid = "XYZ0001", + .adr = 0, + }; + + static struct mfd_cell my_subdevice_cell = { + .name = "my_subdevice", + /* set the resources relative to the parent */ + .acpi_match = &my_subdevice_cell_acpi_match, + }; + +The ACPI id "XYZ0001" is then used to lookup an ACPI device directly under +the MFD device and if found, that ACPI companion device is bound to the +resulting child platform device. + +Device Tree namespace link device ID +==================================== + +The Device Tree protocol uses device identification based on the "compatible" +property whose value is a string or an array of strings recognized as device +identifiers by drivers and the driver core. The set of all those strings may be +regarded as a device identification namespace analogous to the ACPI/PNP device +ID namespace. Consequently, in principle it should not be necessary to allocate +a new (and arguably redundant) ACPI/PNP device ID for a devices with an existing +identification string in the Device Tree (DT) namespace, especially if that ID +is only needed to indicate that a given device is compatible with another one, +presumably having a matching driver in the kernel already. + +In ACPI, the device identification object called _CID (Compatible ID) is used to +list the IDs of devices the given one is compatible with, but those IDs must +belong to one of the namespaces prescribed by the ACPI specification (see +Section 6.1.2 of ACPI 6.0 for details) and the DT namespace is not one of them. +Moreover, the specification mandates that either a _HID or an _ADR identification +object be present for all ACPI objects representing devices (Section 6.1 of ACPI +6.0). For non-enumerable bus types that object must be _HID and its value must +be a device ID from one of the namespaces prescribed by the specification too. + +The special DT namespace link device ID, PRP0001, provides a means to use the +existing DT-compatible device identification in ACPI and to satisfy the above +requirements following from the ACPI specification at the same time. Namely, +if PRP0001 is returned by _HID, the ACPI subsystem will look for the +"compatible" property in the device object's _DSD and will use the value of that +property to identify the corresponding device in analogy with the original DT +device identification algorithm. If the "compatible" property is not present +or its value is not valid, the device will not be enumerated by the ACPI +subsystem. Otherwise, it will be enumerated automatically as a platform device +(except when an I2C or SPI link from the device to its parent is present, in +which case the ACPI core will leave the device enumeration to the parent's +driver) and the identification strings from the "compatible" property value will +be used to find a driver for the device along with the device IDs listed by _CID +(if present). + +Analogously, if PRP0001 is present in the list of device IDs returned by _CID, +the identification strings listed by the "compatible" property value (if present +and valid) will be used to look for a driver matching the device, but in that +case their relative priority with respect to the other device IDs listed by +_HID and _CID depends on the position of PRP0001 in the _CID return package. +Specifically, the device IDs returned by _HID and preceding PRP0001 in the _CID +return package will be checked first. Also in that case the bus type the device +will be enumerated to depends on the device ID returned by _HID. + +For example, the following ACPI sample might be used to enumerate an lm75-type +I2C temperature sensor and match it to the driver using the Device Tree +namespace link: + + Device (TMP0) + { + Name (_HID, "PRP0001") + Name (_DSD, Package() { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package (2) { "compatible", "ti,tmp75" }, + } + }) + Method (_CRS, 0, Serialized) + { + Name (SBUF, ResourceTemplate () + { + I2cSerialBusV2 (0x48, ControllerInitiated, + 400000, AddressingMode7Bit, + "\\_SB.PCI0.I2C1", 0x00, + ResourceConsumer, , Exclusive,) + }) + Return (SBUF) + } + } + +It is valid to define device objects with a _HID returning PRP0001 and without +the "compatible" property in the _DSD or a _CID as long as one of their +ancestors provides a _DSD with a valid "compatible" property. Such device +objects are then simply regarded as additional "blocks" providing hierarchical +configuration information to the driver of the composite ancestor device. + +However, PRP0001 can only be returned from either _HID or _CID of a device +object if all of the properties returned by the _DSD associated with it (either +the _DSD of the device object itself or the _DSD of its ancestor in the +"composite device" case described above) can be used in the ACPI environment. +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. diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index 210ad8acd6df..99677c73f1fb 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -8,3 +8,4 @@ ACPI Support :maxdepth: 1 namespace + enumeration -- cgit v1.2.3-59-g8ed1b From 1cf70ae6f07b071affcd4e324803e928e3336a8d Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 25 Apr 2019 01:52:46 +0800 Subject: Documentation: ACPI: move osi.txt to firmware-guide/acpi and convert to reST This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/osi.txt | 187 --------------------------- Documentation/firmware-guide/acpi/index.rst | 1 + Documentation/firmware-guide/acpi/osi.rst | 190 ++++++++++++++++++++++++++++ 3 files changed, 191 insertions(+), 187 deletions(-) delete mode 100644 Documentation/acpi/osi.txt create mode 100644 Documentation/firmware-guide/acpi/osi.rst (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/acpi/osi.txt b/Documentation/acpi/osi.txt deleted file mode 100644 index 50cde0ceb9b0..000000000000 --- a/Documentation/acpi/osi.txt +++ /dev/null @@ -1,187 +0,0 @@ -ACPI _OSI and _REV methods --------------------------- - -An ACPI BIOS can use the "Operating System Interfaces" method (_OSI) -to find out what the operating system supports. Eg. If BIOS -AML code includes _OSI("XYZ"), the kernel's AML interpreter -can evaluate that method, look to see if it supports 'XYZ' -and answer YES or NO to the BIOS. - -The ACPI _REV method returns the "Revision of the ACPI specification -that OSPM supports" - -This document explains how and why the BIOS and Linux should use these methods. -It also explains how and why they are widely misused. - -How to use _OSI ---------------- - -Linux runs on two groups of machines -- those that are tested by the OEM -to be compatible with Linux, and those that were never tested with Linux, -but where Linux was installed to replace the original OS (Windows or OSX). - -The larger group is the systems tested to run only Windows. Not only that, -but many were tested to run with just one specific version of Windows. -So even though the BIOS may use _OSI to query what version of Windows is running, -only a single path through the BIOS has actually been tested. -Experience shows that taking untested paths through the BIOS -exposes Linux to an entire category of BIOS bugs. -For this reason, Linux _OSI defaults must continue to claim compatibility -with all versions of Windows. - -But Linux isn't actually compatible with Windows, and the Linux community -has also been hurt with regressions when Linux adds the latest version of -Windows to its list of _OSI strings. So it is possible that additional strings -will be more thoroughly vetted before shipping upstream in the future. -But it is likely that they will all eventually be added. - -What should an OEM do if they want to support Linux and Windows -using the same BIOS image? Often they need to do something different -for Linux to deal with how Linux is different from Windows. -Here the BIOS should ask exactly what it wants to know: - -_OSI("Linux-OEM-my_interface_name") -where 'OEM' is needed if this is an OEM-specific hook, -and 'my_interface_name' describes the hook, which could be a -quirk, a bug, or a bug-fix. - -In addition, the OEM should send a patch to upstream Linux -via the linux-acpi@vger.kernel.org mailing list. When that patch -is checked into Linux, the OS will answer "YES" when the BIOS -on the OEM's system uses _OSI to ask if the interface is supported -by the OS. Linux distributors can back-port that patch for Linux -pre-installs, and it will be included by all distributions that -re-base to upstream. If the distribution can not update the kernel binary, -they can also add an acpi_osi=Linux-OEM-my_interface_name -cmdline parameter to the boot loader, as needed. - -If the string refers to a feature where the upstream kernel -eventually grows support, a patch should be sent to remove -the string when that support is added to the kernel. - -That was easy. Read on, to find out how to do it wrong. - -Before _OSI, there was _OS --------------------------- - -ACPI 1.0 specified "_OS" as an -"object that evaluates to a string that identifies the operating system." - -The ACPI BIOS flow would include an evaluation of _OS, and the AML -interpreter in the kernel would return to it a string identifying the OS: - -Windows 98, SE: "Microsoft Windows" -Windows ME: "Microsoft WindowsME:Millenium Edition" -Windows NT: "Microsoft Windows NT" - -The idea was on a platform tasked with running multiple OS's, -the BIOS could use _OS to enable devices that an OS -might support, or enable quirks or bug workarounds -necessary to make the platform compatible with that pre-existing OS. - -But _OS had fundamental problems. First, the BIOS needed to know the name -of every possible version of the OS that would run on it, and needed to know -all the quirks of those OS's. Certainly it would make more sense -for the BIOS to ask *specific* things of the OS, such -"do you support a specific interface", and thus in ACPI 3.0, -_OSI was born to replace _OS. - -_OS was abandoned, though even today, many BIOS look for -_OS "Microsoft Windows NT", though it seems somewhat far-fetched -that anybody would install those old operating systems -over what came with the machine. - -Linux answers "Microsoft Windows NT" to please that BIOS idiom. -That is the *only* viable strategy, as that is what modern Windows does, -and so doing otherwise could steer the BIOS down an untested path. - -_OSI is born, and immediately misused --------------------------------------- - -With _OSI, the *BIOS* provides the string describing an interface, -and asks the OS: "YES/NO, are you compatible with this interface?" - -eg. _OSI("3.0 Thermal Model") would return TRUE if the OS knows how -to deal with the thermal extensions made to the ACPI 3.0 specification. -An old OS that doesn't know about those extensions would answer FALSE, -and a new OS may be able to return TRUE. - -For an OS-specific interface, the ACPI spec said that the BIOS and the OS -were to agree on a string of the form such as "Windows-interface_name". - -But two bad things happened. First, the Windows ecosystem used _OSI -not as designed, but as a direct replacement for _OS -- identifying -the OS version, rather than an OS supported interface. Indeed, right -from the start, the ACPI 3.0 spec itself codified this misuse -in example code using _OSI("Windows 2001"). - -This misuse was adopted and continues today. - -Linux had no choice but to also return TRUE to _OSI("Windows 2001") -and its successors. To do otherwise would virtually guarantee breaking -a BIOS that has been tested only with that _OSI returning TRUE. - -This strategy is problematic, as Linux is never completely compatible with -the latest version of Windows, and sometimes it takes more than a year -to iron out incompatibilities. - -Not to be out-done, the Linux community made things worse by returning TRUE -to _OSI("Linux"). Doing so is even worse than the Windows misuse -of _OSI, as "Linux" does not even contain any version information. -_OSI("Linux") led to some BIOS' malfunctioning due to BIOS writer's -using it in untested BIOS flows. But some OEM's used _OSI("Linux") -in tested flows to support real Linux features. In 2009, Linux -removed _OSI("Linux"), and added a cmdline parameter to restore it -for legacy systems still needed it. Further a BIOS_BUG warning prints -for all BIOS's that invoke it. - -No BIOS should use _OSI("Linux"). - -The result is a strategy for Linux to maximize compatibility with -ACPI BIOS that are tested on Windows machines. There is a real risk -of over-stating that compatibility; but the alternative has often been -catastrophic failure resulting from the BIOS taking paths that -were never validated under *any* OS. - -Do not use _REV ---------------- - -Since _OSI("Linux") went away, some BIOS writers used _REV -to support Linux and Windows differences in the same BIOS. - -_REV was defined in ACPI 1.0 to return the version of ACPI -supported by the OS and the OS AML interpreter. - -Modern Windows returns _REV = 2. Linux used ACPI_CA_SUPPORT_LEVEL, -which would increment, based on the version of the spec supported. - -Unfortunately, _REV was also misused. eg. some BIOS would check -for _REV = 3, and do something for Linux, but when Linux returned -_REV = 4, that support broke. - -In response to this problem, Linux returns _REV = 2 always, -from mid-2015 onward. The ACPI specification will also be updated -to reflect that _REV is deprecated, and always returns 2. - -Apple Mac and _OSI("Darwin") ----------------------------- - -On Apple's Mac platforms, the ACPI BIOS invokes _OSI("Darwin") -to determine if the machine is running Apple OSX. - -Like Linux's _OSI("*Windows*") strategy, Linux defaults to -answering YES to _OSI("Darwin") to enable full access -to the hardware and validated BIOS paths seen by OSX. -Just like on Windows-tested platforms, this strategy has risks. - -Starting in Linux-3.18, the kernel answered YES to _OSI("Darwin") -for the purpose of enabling Mac Thunderbolt support. Further, -if the kernel noticed _OSI("Darwin") being invoked, it additionally -disabled all _OSI("*Windows*") to keep poorly written Mac BIOS -from going down untested combinations of paths. - -The Linux-3.18 change in default caused power regressions on Mac -laptops, and the 3.18 implementation did not allow changing -the default via cmdline "acpi_osi=!Darwin". Linux-4.7 fixed -the ability to use acpi_osi=!Darwin as a workaround, and -we hope to see Mac Thunderbolt power management support in Linux-4.11. diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index 99677c73f1fb..868bd25a3398 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -9,3 +9,4 @@ ACPI Support namespace enumeration + osi diff --git a/Documentation/firmware-guide/acpi/osi.rst b/Documentation/firmware-guide/acpi/osi.rst new file mode 100644 index 000000000000..29e9ef79ebc0 --- /dev/null +++ b/Documentation/firmware-guide/acpi/osi.rst @@ -0,0 +1,190 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================== +ACPI _OSI and _REV methods +========================== + +An ACPI BIOS can use the "Operating System Interfaces" method (_OSI) +to find out what the operating system supports. Eg. If BIOS +AML code includes _OSI("XYZ"), the kernel's AML interpreter +can evaluate that method, look to see if it supports 'XYZ' +and answer YES or NO to the BIOS. + +The ACPI _REV method returns the "Revision of the ACPI specification +that OSPM supports" + +This document explains how and why the BIOS and Linux should use these methods. +It also explains how and why they are widely misused. + +How to use _OSI +=============== + +Linux runs on two groups of machines -- those that are tested by the OEM +to be compatible with Linux, and those that were never tested with Linux, +but where Linux was installed to replace the original OS (Windows or OSX). + +The larger group is the systems tested to run only Windows. Not only that, +but many were tested to run with just one specific version of Windows. +So even though the BIOS may use _OSI to query what version of Windows is running, +only a single path through the BIOS has actually been tested. +Experience shows that taking untested paths through the BIOS +exposes Linux to an entire category of BIOS bugs. +For this reason, Linux _OSI defaults must continue to claim compatibility +with all versions of Windows. + +But Linux isn't actually compatible with Windows, and the Linux community +has also been hurt with regressions when Linux adds the latest version of +Windows to its list of _OSI strings. So it is possible that additional strings +will be more thoroughly vetted before shipping upstream in the future. +But it is likely that they will all eventually be added. + +What should an OEM do if they want to support Linux and Windows +using the same BIOS image? Often they need to do something different +for Linux to deal with how Linux is different from Windows. +Here the BIOS should ask exactly what it wants to know: + +_OSI("Linux-OEM-my_interface_name") +where 'OEM' is needed if this is an OEM-specific hook, +and 'my_interface_name' describes the hook, which could be a +quirk, a bug, or a bug-fix. + +In addition, the OEM should send a patch to upstream Linux +via the linux-acpi@vger.kernel.org mailing list. When that patch +is checked into Linux, the OS will answer "YES" when the BIOS +on the OEM's system uses _OSI to ask if the interface is supported +by the OS. Linux distributors can back-port that patch for Linux +pre-installs, and it will be included by all distributions that +re-base to upstream. If the distribution can not update the kernel binary, +they can also add an acpi_osi=Linux-OEM-my_interface_name +cmdline parameter to the boot loader, as needed. + +If the string refers to a feature where the upstream kernel +eventually grows support, a patch should be sent to remove +the string when that support is added to the kernel. + +That was easy. Read on, to find out how to do it wrong. + +Before _OSI, there was _OS +========================== + +ACPI 1.0 specified "_OS" as an +"object that evaluates to a string that identifies the operating system." + +The ACPI BIOS flow would include an evaluation of _OS, and the AML +interpreter in the kernel would return to it a string identifying the OS: + +Windows 98, SE: "Microsoft Windows" +Windows ME: "Microsoft WindowsME:Millenium Edition" +Windows NT: "Microsoft Windows NT" + +The idea was on a platform tasked with running multiple OS's, +the BIOS could use _OS to enable devices that an OS +might support, or enable quirks or bug workarounds +necessary to make the platform compatible with that pre-existing OS. + +But _OS had fundamental problems. First, the BIOS needed to know the name +of every possible version of the OS that would run on it, and needed to know +all the quirks of those OS's. Certainly it would make more sense +for the BIOS to ask *specific* things of the OS, such +"do you support a specific interface", and thus in ACPI 3.0, +_OSI was born to replace _OS. + +_OS was abandoned, though even today, many BIOS look for +_OS "Microsoft Windows NT", though it seems somewhat far-fetched +that anybody would install those old operating systems +over what came with the machine. + +Linux answers "Microsoft Windows NT" to please that BIOS idiom. +That is the *only* viable strategy, as that is what modern Windows does, +and so doing otherwise could steer the BIOS down an untested path. + +_OSI is born, and immediately misused +===================================== + +With _OSI, the *BIOS* provides the string describing an interface, +and asks the OS: "YES/NO, are you compatible with this interface?" + +eg. _OSI("3.0 Thermal Model") would return TRUE if the OS knows how +to deal with the thermal extensions made to the ACPI 3.0 specification. +An old OS that doesn't know about those extensions would answer FALSE, +and a new OS may be able to return TRUE. + +For an OS-specific interface, the ACPI spec said that the BIOS and the OS +were to agree on a string of the form such as "Windows-interface_name". + +But two bad things happened. First, the Windows ecosystem used _OSI +not as designed, but as a direct replacement for _OS -- identifying +the OS version, rather than an OS supported interface. Indeed, right +from the start, the ACPI 3.0 spec itself codified this misuse +in example code using _OSI("Windows 2001"). + +This misuse was adopted and continues today. + +Linux had no choice but to also return TRUE to _OSI("Windows 2001") +and its successors. To do otherwise would virtually guarantee breaking +a BIOS that has been tested only with that _OSI returning TRUE. + +This strategy is problematic, as Linux is never completely compatible with +the latest version of Windows, and sometimes it takes more than a year +to iron out incompatibilities. + +Not to be out-done, the Linux community made things worse by returning TRUE +to _OSI("Linux"). Doing so is even worse than the Windows misuse +of _OSI, as "Linux" does not even contain any version information. +_OSI("Linux") led to some BIOS' malfunctioning due to BIOS writer's +using it in untested BIOS flows. But some OEM's used _OSI("Linux") +in tested flows to support real Linux features. In 2009, Linux +removed _OSI("Linux"), and added a cmdline parameter to restore it +for legacy systems still needed it. Further a BIOS_BUG warning prints +for all BIOS's that invoke it. + +No BIOS should use _OSI("Linux"). + +The result is a strategy for Linux to maximize compatibility with +ACPI BIOS that are tested on Windows machines. There is a real risk +of over-stating that compatibility; but the alternative has often been +catastrophic failure resulting from the BIOS taking paths that +were never validated under *any* OS. + +Do not use _REV +=============== + +Since _OSI("Linux") went away, some BIOS writers used _REV +to support Linux and Windows differences in the same BIOS. + +_REV was defined in ACPI 1.0 to return the version of ACPI +supported by the OS and the OS AML interpreter. + +Modern Windows returns _REV = 2. Linux used ACPI_CA_SUPPORT_LEVEL, +which would increment, based on the version of the spec supported. + +Unfortunately, _REV was also misused. eg. some BIOS would check +for _REV = 3, and do something for Linux, but when Linux returned +_REV = 4, that support broke. + +In response to this problem, Linux returns _REV = 2 always, +from mid-2015 onward. The ACPI specification will also be updated +to reflect that _REV is deprecated, and always returns 2. + +Apple Mac and _OSI("Darwin") +============================ + +On Apple's Mac platforms, the ACPI BIOS invokes _OSI("Darwin") +to determine if the machine is running Apple OSX. + +Like Linux's _OSI("*Windows*") strategy, Linux defaults to +answering YES to _OSI("Darwin") to enable full access +to the hardware and validated BIOS paths seen by OSX. +Just like on Windows-tested platforms, this strategy has risks. + +Starting in Linux-3.18, the kernel answered YES to _OSI("Darwin") +for the purpose of enabling Mac Thunderbolt support. Further, +if the kernel noticed _OSI("Darwin") being invoked, it additionally +disabled all _OSI("*Windows*") to keep poorly written Mac BIOS +from going down untested combinations of paths. + +The Linux-3.18 change in default caused power regressions on Mac +laptops, and the 3.18 implementation did not allow changing +the default via cmdline "acpi_osi=!Darwin". Linux-4.7 fixed +the ability to use acpi_osi=!Darwin as a workaround, and +we hope to see Mac Thunderbolt power management support in Linux-4.11. -- cgit v1.2.3-59-g8ed1b From 538f6f76b9ca5cbcd521db80e137d1c43e55556b Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 25 Apr 2019 01:52:49 +0800 Subject: Documentation: ACPI: move DSD-properties-rules.txt to firmware-guide/acpi and covert to reST This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/DSD-properties-rules.txt | 97 -------------------- .../firmware-guide/acpi/DSD-properties-rules.rst | 100 +++++++++++++++++++++ Documentation/firmware-guide/acpi/index.rst | 1 + 3 files changed, 101 insertions(+), 97 deletions(-) delete mode 100644 Documentation/acpi/DSD-properties-rules.txt create mode 100644 Documentation/firmware-guide/acpi/DSD-properties-rules.rst (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/acpi/DSD-properties-rules.txt b/Documentation/acpi/DSD-properties-rules.txt deleted file mode 100644 index 3e4862bdad98..000000000000 --- a/Documentation/acpi/DSD-properties-rules.txt +++ /dev/null @@ -1,97 +0,0 @@ -_DSD Device Properties Usage Rules ----------------------------------- - -Properties, Property Sets and Property Subsets ----------------------------------------------- - -The _DSD (Device Specific Data) configuration object, introduced in ACPI 5.1, -allows any type of device configuration data to be provided via the ACPI -namespace. In principle, the format of the data may be arbitrary, but it has to -be identified by a UUID which must be recognized by the driver processing the -_DSD output. However, there are generic UUIDs defined for _DSD recognized by -the ACPI subsystem in the Linux kernel which automatically processes the data -packages associated with them and makes those data available to device drivers -as "device properties". - -A device property is a data item consisting of a string key and a value (of a -specific type) associated with it. - -In the ACPI _DSD context it is an element of the sub-package following the -generic Device Properties UUID in the _DSD return package as specified in the -Device Properties UUID definition document [1]. - -It also may be regarded as the definition of a key and the associated data type -that can be returned by _DSD in the Device Properties UUID sub-package for a -given device. - -A property set is a collection of properties applicable to a hardware entity -like a device. In the ACPI _DSD context it is the set of all properties that -can be returned in the Device Properties UUID sub-package for the device in -question. - -Property subsets are nested collections of properties. Each of them is -associated with an additional key (name) allowing the subset to be referred -to as a whole (and to be treated as a separate entity). The canonical -representation of property subsets is via the mechanism specified in the -Hierarchical Properties Extension UUID definition document [2]. - -Property sets may be hierarchical. That is, a property set may contain -multiple property subsets that each may contain property subsets of its -own and so on. - -General Validity Rule for Property Sets ---------------------------------------- - -Valid property sets must follow the guidance given by the Device Properties UUID -definition document [1]. - -_DSD properties are intended to be used in addition to, and not instead of, the -existing mechanisms defined by the ACPI specification. Therefore, as a rule, -they should only be used if the ACPI specification does not make direct -provisions for handling the underlying use case. It generally is invalid to -return property sets which do not follow that rule from _DSD in data packages -associated with the Device Properties UUID. - -Additional Considerations -------------------------- - -There are cases in which, even if the general rule given above is followed in -principle, the property set may still not be regarded as a valid one. - -For example, that applies to device properties which may cause kernel code -(either a device driver or a library/subsystem) to access hardware in a way -possibly leading to a conflict with AML methods in the ACPI namespace. In -particular, that may happen if the kernel code uses device properties to -manipulate hardware normally controlled by ACPI methods related to power -management, like _PSx and _DSW (for device objects) or _ON and _OFF (for power -resource objects), or by ACPI device disabling/enabling methods, like _DIS and -_SRS. - -In all cases in which kernel code may do something that will confuse AML as a -result of using device properties, the device properties in question are not -suitable for the ACPI environment and consequently they cannot belong to a valid -property set. - -Property Sets and Device Tree Bindings --------------------------------------- - -It often is useful to make _DSD return property sets that follow Device Tree -bindings. - -In those cases, however, the above validity considerations must be taken into -account in the first place and returning invalid property sets from _DSD must be -avoided. For this reason, it may not be possible to make _DSD return a property -set following the given DT binding literally and completely. Still, for the -sake of code re-use, it may make sense to provide as much of the configuration -data as possible in the form of device properties and complement that with an -ACPI-specific mechanism suitable for the use case at hand. - -In any case, property sets following DT bindings literally should not be -expected to automatically work in the ACPI environment regardless of their -contents. - -References ----------- - -[1] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf -[2] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf diff --git a/Documentation/firmware-guide/acpi/DSD-properties-rules.rst b/Documentation/firmware-guide/acpi/DSD-properties-rules.rst new file mode 100644 index 000000000000..4306f29b6103 --- /dev/null +++ b/Documentation/firmware-guide/acpi/DSD-properties-rules.rst @@ -0,0 +1,100 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================== +_DSD Device Properties Usage Rules +================================== + +Properties, Property Sets and Property Subsets +============================================== + +The _DSD (Device Specific Data) configuration object, introduced in ACPI 5.1, +allows any type of device configuration data to be provided via the ACPI +namespace. In principle, the format of the data may be arbitrary, but it has to +be identified by a UUID which must be recognized by the driver processing the +_DSD output. However, there are generic UUIDs defined for _DSD recognized by +the ACPI subsystem in the Linux kernel which automatically processes the data +packages associated with them and makes those data available to device drivers +as "device properties". + +A device property is a data item consisting of a string key and a value (of a +specific type) associated with it. + +In the ACPI _DSD context it is an element of the sub-package following the +generic Device Properties UUID in the _DSD return package as specified in the +Device Properties UUID definition document [1]_. + +It also may be regarded as the definition of a key and the associated data type +that can be returned by _DSD in the Device Properties UUID sub-package for a +given device. + +A property set is a collection of properties applicable to a hardware entity +like a device. In the ACPI _DSD context it is the set of all properties that +can be returned in the Device Properties UUID sub-package for the device in +question. + +Property subsets are nested collections of properties. Each of them is +associated with an additional key (name) allowing the subset to be referred +to as a whole (and to be treated as a separate entity). The canonical +representation of property subsets is via the mechanism specified in the +Hierarchical Properties Extension UUID definition document [2]_. + +Property sets may be hierarchical. That is, a property set may contain +multiple property subsets that each may contain property subsets of its +own and so on. + +General Validity Rule for Property Sets +======================================= + +Valid property sets must follow the guidance given by the Device Properties UUID +definition document [1]. + +_DSD properties are intended to be used in addition to, and not instead of, the +existing mechanisms defined by the ACPI specification. Therefore, as a rule, +they should only be used if the ACPI specification does not make direct +provisions for handling the underlying use case. It generally is invalid to +return property sets which do not follow that rule from _DSD in data packages +associated with the Device Properties UUID. + +Additional Considerations +------------------------- + +There are cases in which, even if the general rule given above is followed in +principle, the property set may still not be regarded as a valid one. + +For example, that applies to device properties which may cause kernel code +(either a device driver or a library/subsystem) to access hardware in a way +possibly leading to a conflict with AML methods in the ACPI namespace. In +particular, that may happen if the kernel code uses device properties to +manipulate hardware normally controlled by ACPI methods related to power +management, like _PSx and _DSW (for device objects) or _ON and _OFF (for power +resource objects), or by ACPI device disabling/enabling methods, like _DIS and +_SRS. + +In all cases in which kernel code may do something that will confuse AML as a +result of using device properties, the device properties in question are not +suitable for the ACPI environment and consequently they cannot belong to a valid +property set. + +Property Sets and Device Tree Bindings +====================================== + +It often is useful to make _DSD return property sets that follow Device Tree +bindings. + +In those cases, however, the above validity considerations must be taken into +account in the first place and returning invalid property sets from _DSD must be +avoided. For this reason, it may not be possible to make _DSD return a property +set following the given DT binding literally and completely. Still, for the +sake of code re-use, it may make sense to provide as much of the configuration +data as possible in the form of device properties and complement that with an +ACPI-specific mechanism suitable for the use case at hand. + +In any case, property sets following DT bindings literally should not be +expected to automatically work in the ACPI environment regardless of their +contents. + +References +========== + +.. [1] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf +.. [2] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index 868bd25a3398..0e05b843521c 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -10,3 +10,4 @@ ACPI Support namespace enumeration osi + DSD-properties-rules -- cgit v1.2.3-59-g8ed1b From b6dff0e153e919b62e2a1c90fd6e5a4ba922f99b Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 25 Apr 2019 01:52:50 +0800 Subject: Documentation: ACPI: move gpio-properties.txt to firmware-guide/acpi and convert to reST This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/gpio-properties.txt | 223 -------------------- .../firmware-guide/acpi/gpio-properties.rst | 233 +++++++++++++++++++++ Documentation/firmware-guide/acpi/index.rst | 1 + MAINTAINERS | 2 +- 4 files changed, 235 insertions(+), 224 deletions(-) delete mode 100644 Documentation/acpi/gpio-properties.txt create mode 100644 Documentation/firmware-guide/acpi/gpio-properties.rst (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/acpi/gpio-properties.txt b/Documentation/acpi/gpio-properties.txt deleted file mode 100644 index 88c65cb5bf0a..000000000000 --- a/Documentation/acpi/gpio-properties.txt +++ /dev/null @@ -1,223 +0,0 @@ -_DSD Device Properties Related to GPIO --------------------------------------- - -With the release of ACPI 5.1, the _DSD configuration object finally -allows names to be given to GPIOs (and other things as well) returned -by _CRS. Previously, we were only able to use an integer index to find -the corresponding GPIO, which is pretty error prone (it depends on -the _CRS output ordering, for example). - -With _DSD we can now query GPIOs using a name instead of an integer -index, like the ASL example below shows: - - // Bluetooth device with reset and shutdown GPIOs - Device (BTH) - { - Name (_HID, ...) - - Name (_CRS, ResourceTemplate () - { - GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionInputOnly, - "\\_SB.GPO0", 0, ResourceConsumer) {15} - GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionInputOnly, - "\\_SB.GPO0", 0, ResourceConsumer) {27, 31} - }) - - Name (_DSD, Package () - { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () - { - Package () {"reset-gpios", Package() {^BTH, 1, 1, 0 }}, - Package () {"shutdown-gpios", Package() {^BTH, 0, 0, 0 }}, - } - }) - } - -The format of the supported GPIO property is: - - Package () { "name", Package () { ref, index, pin, active_low }} - - ref - The device that has _CRS containing GpioIo()/GpioInt() resources, - typically this is the device itself (BTH in our case). - index - Index of the GpioIo()/GpioInt() resource in _CRS starting from zero. - pin - Pin in the GpioIo()/GpioInt() resource. Typically this is zero. - 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. - -In our Bluetooth example the "reset-gpios" refers to the second GpioIo() -resource, second pin in that resource with the GPIO number of 31. - -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 -controller can have chip selects 0 and 2 implemented as GPIOs and 1 as -native: - - Package () { - "cs-gpios", - Package () { - ^GPIO, 19, 0, 0, // chip select 0: GPIO - 0, // chip select 1: native signal - ^GPIO, 20, 0, 0, // chip select 2: GPIO - } - } - -Other supported properties --------------------------- - -Following Device Tree compatible device properties are also supported by -_DSD device properties for GPIO controllers: - -- gpio-hog -- output-high -- output-low -- input -- line-name - -Example: - - Name (_DSD, Package () { - // _DSD Hierarchical Properties Extension UUID - ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), - Package () { - Package () {"hog-gpio8", "G8PU"} - } - }) - - Name (G8PU, Package () { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () { - Package () {"gpio-hog", 1}, - Package () {"gpios", Package () {8, 0}}, - Package () {"output-high", 1}, - Package () {"line-name", "gpio8-pullup"}, - } - }) - -- gpio-line-names - -Example: - - Package () { - "gpio-line-names", - Package () { - "SPI0_CS_N", "EXP2_INT", "MUX6_IO", "UART0_RXD", "MUX7_IO", - "LVL_C_A1", "MUX0_IO", "SPI1_MISO" - } - } - -See Documentation/devicetree/bindings/gpio/gpio.txt for more information -about these properties. - -ACPI GPIO Mappings Provided by Drivers --------------------------------------- - -There are systems in which the ACPI tables do not contain _DSD but provide _CRS -with GpioIo()/GpioInt() resources and device drivers still need to work with -them. - -In those cases ACPI device identification objects, _HID, _CID, _CLS, _SUB, _HRV, -available to the driver can be used to identify the device and that is supposed -to be sufficient to determine the meaning and purpose of all of the GPIO lines -listed by the GpioIo()/GpioInt() resources returned by _CRS. In other words, -the driver is supposed to know what to use the GpioIo()/GpioInt() resources for -once it has identified the device. Having done that, it can simply assign names -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 -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 -GpioIo()/GpioInt() resource in _CRS starting from zero, the index of the target -line in that resource starting from zero, and the active-low flag for that line, -respectively, in analogy with the _DSD GPIO property format specified above. - -For the example Bluetooth device discussed previously the data structures in -question would look like this: - -static const struct acpi_gpio_params reset_gpio = { 1, 1, false }; -static const struct acpi_gpio_params shutdown_gpio = { 0, 0, false }; - -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 -calling acpi_dev_remove_driver_gpios() on the ACPI device object where that -table was previously registered. - -Using the _CRS fallback ------------------------ - -If a device does not have _DSD or the driver does not create ACPI GPIO -mapping, the Linux GPIO framework refuses to return any GPIOs. This is -because the driver does not know what it actually gets. For example if we -have a device like below: - - Device (BTH) - { - Name (_HID, ...) - - Name (_CRS, ResourceTemplate () { - GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionNone, - "\\_SB.GPO0", 0, ResourceConsumer) {15} - GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionNone, - "\\_SB.GPO0", 0, ResourceConsumer) {27} - }) - } - -The driver might expect to get the right GPIO when it does: - - desc = gpiod_get(dev, "reset", GPIOD_OUT_LOW); - -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 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 -objects, as listed in the above chapter, of the device in question. - -Getting GPIO descriptor ------------------------ - -There are two main approaches to get GPIO resource from ACPI: - desc = gpiod_get(dev, connection_id, flags); - desc = gpiod_get_index(dev, connection_id, index, flags); - -We may consider two different cases here, i.e. when connection ID is -provided and otherwise. - -Case 1: - desc = gpiod_get(dev, "non-null-connection-id", flags); - desc = gpiod_get_index(dev, "non-null-connection-id", index, flags); - -Case 2: - desc = gpiod_get(dev, NULL, flags); - desc = gpiod_get_index(dev, NULL, index, flags); - -Case 1 assumes that corresponding ACPI device description must have -defined device properties and will prevent to getting any GPIO resources -otherwise. - -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 -chapter. diff --git a/Documentation/firmware-guide/acpi/gpio-properties.rst b/Documentation/firmware-guide/acpi/gpio-properties.rst new file mode 100644 index 000000000000..bb6d74f23ee0 --- /dev/null +++ b/Documentation/firmware-guide/acpi/gpio-properties.rst @@ -0,0 +1,233 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================================== +_DSD Device Properties Related to GPIO +====================================== + +With the release of ACPI 5.1, the _DSD configuration object finally +allows names to be given to GPIOs (and other things as well) returned +by _CRS. Previously, we were only able to use an integer index to find +the corresponding GPIO, which is pretty error prone (it depends on +the _CRS output ordering, for example). + +With _DSD we can now query GPIOs using a name instead of an integer +index, like the ASL example below shows:: + + // Bluetooth device with reset and shutdown GPIOs + Device (BTH) + { + Name (_HID, ...) + + Name (_CRS, ResourceTemplate () + { + GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionInputOnly, + "\\_SB.GPO0", 0, ResourceConsumer) {15} + GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionInputOnly, + "\\_SB.GPO0", 0, ResourceConsumer) {27, 31} + }) + + Name (_DSD, Package () + { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () + { + Package () {"reset-gpios", Package() {^BTH, 1, 1, 0 }}, + Package () {"shutdown-gpios", Package() {^BTH, 0, 0, 0 }}, + } + }) + } + +The format of the supported GPIO property is:: + + Package () { "name", Package () { ref, index, pin, active_low }} + +ref + The device that has _CRS containing GpioIo()/GpioInt() resources, + typically this is the device itself (BTH in our case). +index + Index of the GpioIo()/GpioInt() resource in _CRS starting from zero. +pin + Pin in the GpioIo()/GpioInt() resource. Typically this is zero. +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. + +In our Bluetooth example the "reset-gpios" refers to the second GpioIo() +resource, second pin in that resource with the GPIO number of 31. + +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 +controller can have chip selects 0 and 2 implemented as GPIOs and 1 as +native:: + + Package () { + "cs-gpios", + Package () { + ^GPIO, 19, 0, 0, // chip select 0: GPIO + 0, // chip select 1: native signal + ^GPIO, 20, 0, 0, // chip select 2: GPIO + } + } + +Other supported properties +========================== + +Following Device Tree compatible device properties are also supported by +_DSD device properties for GPIO controllers: + +- gpio-hog +- output-high +- output-low +- input +- line-name + +Example:: + + Name (_DSD, Package () { + // _DSD Hierarchical Properties Extension UUID + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () {"hog-gpio8", "G8PU"} + } + }) + + Name (G8PU, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () {"gpio-hog", 1}, + Package () {"gpios", Package () {8, 0}}, + Package () {"output-high", 1}, + Package () {"line-name", "gpio8-pullup"}, + } + }) + +- gpio-line-names + +Example:: + + Package () { + "gpio-line-names", + Package () { + "SPI0_CS_N", "EXP2_INT", "MUX6_IO", "UART0_RXD", "MUX7_IO", + "LVL_C_A1", "MUX0_IO", "SPI1_MISO" + } + } + +See Documentation/devicetree/bindings/gpio/gpio.txt for more information +about these properties. + +ACPI GPIO Mappings Provided by Drivers +====================================== + +There are systems in which the ACPI tables do not contain _DSD but provide _CRS +with GpioIo()/GpioInt() resources and device drivers still need to work with +them. + +In those cases ACPI device identification objects, _HID, _CID, _CLS, _SUB, _HRV, +available to the driver can be used to identify the device and that is supposed +to be sufficient to determine the meaning and purpose of all of the GPIO lines +listed by the GpioIo()/GpioInt() resources returned by _CRS. In other words, +the driver is supposed to know what to use the GpioIo()/GpioInt() resources for +once it has identified the device. Having done that, it can simply assign names +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 +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 +GpioIo()/GpioInt() resource in _CRS starting from zero, the index of the target +line in that resource starting from zero, and the active-low flag for that line, +respectively, in analogy with the _DSD GPIO property format specified above. + +For the example Bluetooth device discussed previously the data structures in +question would look like this:: + + static const struct acpi_gpio_params reset_gpio = { 1, 1, false }; + static const struct acpi_gpio_params shutdown_gpio = { 0, 0, false }; + + 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 +calling acpi_dev_remove_driver_gpios() on the ACPI device object where that +table was previously registered. + +Using the _CRS fallback +======================= + +If a device does not have _DSD or the driver does not create ACPI GPIO +mapping, the Linux GPIO framework refuses to return any GPIOs. This is +because the driver does not know what it actually gets. For example if we +have a device like below:: + + Device (BTH) + { + Name (_HID, ...) + + Name (_CRS, ResourceTemplate () { + GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionNone, + "\\_SB.GPO0", 0, ResourceConsumer) {15} + GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionNone, + "\\_SB.GPO0", 0, ResourceConsumer) {27} + }) + } + +The driver might expect to get the right GPIO when it does:: + + desc = gpiod_get(dev, "reset", GPIOD_OUT_LOW); + +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 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 +objects, as listed in the above chapter, of the device in question. + +Getting GPIO descriptor +======================= + +There are two main approaches to get GPIO resource from ACPI:: + + desc = gpiod_get(dev, connection_id, flags); + desc = gpiod_get_index(dev, connection_id, index, flags); + +We may consider two different cases here, i.e. when connection ID is +provided and otherwise. + +Case 1:: + + desc = gpiod_get(dev, "non-null-connection-id", flags); + desc = gpiod_get_index(dev, "non-null-connection-id", index, flags); + +Case 2:: + + desc = gpiod_get(dev, NULL, flags); + desc = gpiod_get_index(dev, NULL, index, flags); + +Case 1 assumes that corresponding ACPI device description must have +defined device properties and will prevent to getting any GPIO resources +otherwise. + +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 +chapter. diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index 0e05b843521c..61d67763851b 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -11,3 +11,4 @@ ACPI Support enumeration osi DSD-properties-rules + gpio-properties diff --git a/MAINTAINERS b/MAINTAINERS index 3e5a5d263f29..89c13e1ed648 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -6593,7 +6593,7 @@ M: Andy Shevchenko L: linux-gpio@vger.kernel.org L: linux-acpi@vger.kernel.org S: Maintained -F: Documentation/acpi/gpio-properties.txt +F: Documentation/firmware-guide/acpi/gpio-properties.rst F: drivers/gpio/gpiolib-acpi.c GPIO IR Transmitter -- cgit v1.2.3-59-g8ed1b From eea7803278619d1a3bda6306cd8470497cd2c5e3 Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 25 Apr 2019 01:52:51 +0800 Subject: Documentation: ACPI: move method-customizing.txt to firmware-guide/acpi and convert to reST This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/method-customizing.txt | 73 ------------------ Documentation/firmware-guide/acpi/index.rst | 3 +- .../firmware-guide/acpi/method-customizing.rst | 89 ++++++++++++++++++++++ 3 files changed, 91 insertions(+), 74 deletions(-) delete mode 100644 Documentation/acpi/method-customizing.txt create mode 100644 Documentation/firmware-guide/acpi/method-customizing.rst (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/acpi/method-customizing.txt b/Documentation/acpi/method-customizing.txt deleted file mode 100644 index 7235da975f23..000000000000 --- a/Documentation/acpi/method-customizing.txt +++ /dev/null @@ -1,73 +0,0 @@ -Linux ACPI Custom Control Method How To -======================================= - -Written by Zhang Rui - - -Linux supports customizing ACPI control methods at runtime. - -Users can use this to -1. override an existing method which may not work correctly, - or just for debugging purposes. -2. insert a completely new method in order to create a missing - method such as _OFF, _ON, _STA, _INI, etc. -For these cases, it is far simpler to dynamically install a single -control method rather than override the entire DSDT, because kernel -rebuild/reboot is not needed and test result can be got in minutes. - -Note: Only ACPI METHOD can be overridden, any other object types like - "Device", "OperationRegion", are not recognized. Methods - declared inside scope operators are also not supported. -Note: The same ACPI control method can be overridden for many times, - and it's always the latest one that used by Linux/kernel. -Note: To get the ACPI debug object output (Store (AAAA, Debug)), - please run "echo 1 > /sys/module/acpi/parameters/aml_debug_output". - -1. override an existing method - a) get the ACPI table via ACPI sysfs I/F. e.g. to get the DSDT, - just run "cat /sys/firmware/acpi/tables/DSDT > /tmp/dsdt.dat" - b) disassemble the table by running "iasl -d dsdt.dat". - c) rewrite the ASL code of the method and save it in a new file, - d) package the new file (psr.asl) to an ACPI table format. - Here is an example of a customized \_SB._AC._PSR method, - - DefinitionBlock ("", "SSDT", 1, "", "", 0x20080715) - { - Method (\_SB_.AC._PSR, 0, NotSerialized) - { - Store ("In AC _PSR", Debug) - Return (ACON) - } - } - Note that the full pathname of the method in ACPI namespace - should be used. - e) assemble the file to generate the AML code of the method. - e.g. "iasl -vw 6084 psr.asl" (psr.aml is generated as a result) - If parameter "-vw 6084" is not supported by your iASL compiler, - please try a newer version. - f) mount debugfs by "mount -t debugfs none /sys/kernel/debug" - g) override the old method via the debugfs by running - "cat /tmp/psr.aml > /sys/kernel/debug/acpi/custom_method" - -2. insert a new method - This is easier than overriding an existing method. - We just need to create the ASL code of the method we want to - insert and then follow the step c) ~ g) in section 1. - -3. undo your changes - The "undo" operation is not supported for a new inserted method - right now, i.e. we can not remove a method currently. - For an overridden method, in order to undo your changes, please - save a copy of the method original ASL code in step c) section 1, - and redo step c) ~ g) to override the method with the original one. - - -Note: We can use a kernel with multiple custom ACPI method running, - But each individual write to debugfs can implement a SINGLE - method override. i.e. if we want to insert/override multiple - ACPI methods, we need to redo step c) ~ g) for multiple times. - -Note: Be aware that root can mis-use this driver to modify arbitrary - memory and gain additional rights, if root's privileges got - restricted (for example if root is not allowed to load additional - modules after boot). diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index 61d67763851b..d1d069b26bbc 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -10,5 +10,6 @@ ACPI Support namespace enumeration osi + method-customizing DSD-properties-rules - gpio-properties + gpio-properties \ No newline at end of file diff --git a/Documentation/firmware-guide/acpi/method-customizing.rst b/Documentation/firmware-guide/acpi/method-customizing.rst new file mode 100644 index 000000000000..de3ebcaed4cf --- /dev/null +++ b/Documentation/firmware-guide/acpi/method-customizing.rst @@ -0,0 +1,89 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================= +Linux ACPI Custom Control Method How To +======================================= + +:Author: Zhang Rui + + +Linux supports customizing ACPI control methods at runtime. + +Users can use this to: + +1. override an existing method which may not work correctly, + or just for debugging purposes. +2. insert a completely new method in order to create a missing + method such as _OFF, _ON, _STA, _INI, etc. + +For these cases, it is far simpler to dynamically install a single +control method rather than override the entire DSDT, because kernel +rebuild/reboot is not needed and test result can be got in minutes. + +.. note:: + + - Only ACPI METHOD can be overridden, any other object types like + "Device", "OperationRegion", are not recognized. Methods + declared inside scope operators are also not supported. + + - The same ACPI control method can be overridden for many times, + and it's always the latest one that used by Linux/kernel. + + - To get the ACPI debug object output (Store (AAAA, Debug)), + please run:: + + echo 1 > /sys/module/acpi/parameters/aml_debug_output + + +1. override an existing method +============================== +a) get the ACPI table via ACPI sysfs I/F. e.g. to get the DSDT, + just run "cat /sys/firmware/acpi/tables/DSDT > /tmp/dsdt.dat" +b) disassemble the table by running "iasl -d dsdt.dat". +c) rewrite the ASL code of the method and save it in a new file, +d) package the new file (psr.asl) to an ACPI table format. + Here is an example of a customized \_SB._AC._PSR method:: + + DefinitionBlock ("", "SSDT", 1, "", "", 0x20080715) + { + Method (\_SB_.AC._PSR, 0, NotSerialized) + { + Store ("In AC _PSR", Debug) + Return (ACON) + } + } + + Note that the full pathname of the method in ACPI namespace + should be used. +e) assemble the file to generate the AML code of the method. + e.g. "iasl -vw 6084 psr.asl" (psr.aml is generated as a result) + If parameter "-vw 6084" is not supported by your iASL compiler, + please try a newer version. +f) mount debugfs by "mount -t debugfs none /sys/kernel/debug" +g) override the old method via the debugfs by running + "cat /tmp/psr.aml > /sys/kernel/debug/acpi/custom_method" + +2. insert a new method +====================== +This is easier than overriding an existing method. +We just need to create the ASL code of the method we want to +insert and then follow the step c) ~ g) in section 1. + +3. undo your changes +==================== +The "undo" operation is not supported for a new inserted method +right now, i.e. we can not remove a method currently. +For an overridden method, in order to undo your changes, please +save a copy of the method original ASL code in step c) section 1, +and redo step c) ~ g) to override the method with the original one. + + +.. note:: We can use a kernel with multiple custom ACPI method running, + But each individual write to debugfs can implement a SINGLE + method override. i.e. if we want to insert/override multiple + ACPI methods, we need to redo step c) ~ g) for multiple times. + +.. note:: Be aware that root can mis-use this driver to modify arbitrary + memory and gain additional rights, if root's privileges got + restricted (for example if root is not allowed to load additional + modules after boot). -- cgit v1.2.3-59-g8ed1b From 572c9fa516f532d6cfd7123d7753fe52730f1c59 Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 25 Apr 2019 01:52:54 +0800 Subject: Documentation: ACPI: move i2c-muxes.txt to firmware-guide/acpi and convert to reST This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/i2c-muxes.txt | 58 ----------------------- Documentation/firmware-guide/acpi/i2c-muxes.rst | 61 +++++++++++++++++++++++++ Documentation/firmware-guide/acpi/index.rst | 3 +- 3 files changed, 63 insertions(+), 59 deletions(-) delete mode 100644 Documentation/acpi/i2c-muxes.txt create mode 100644 Documentation/firmware-guide/acpi/i2c-muxes.rst (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/acpi/i2c-muxes.txt b/Documentation/acpi/i2c-muxes.txt deleted file mode 100644 index 9fcc4f0b885e..000000000000 --- a/Documentation/acpi/i2c-muxes.txt +++ /dev/null @@ -1,58 +0,0 @@ -ACPI I2C Muxes --------------- - -Describing an I2C device hierarchy that includes I2C muxes requires an ACPI -Device () scope per mux channel. - -Consider this topology: - -+------+ +------+ -| SMB1 |-->| MUX0 |--CH00--> i2c client A (0x50) -| | | 0x70 |--CH01--> i2c client B (0x50) -+------+ +------+ - -which corresponds to the following ASL: - -Device (SMB1) -{ - Name (_HID, ...) - Device (MUX0) - { - Name (_HID, ...) - Name (_CRS, ResourceTemplate () { - I2cSerialBus (0x70, ControllerInitiated, I2C_SPEED, - AddressingMode7Bit, "^SMB1", 0x00, - ResourceConsumer,,) - } - - Device (CH00) - { - Name (_ADR, 0) - - Device (CLIA) - { - Name (_HID, ...) - Name (_CRS, ResourceTemplate () { - I2cSerialBus (0x50, ControllerInitiated, I2C_SPEED, - AddressingMode7Bit, "^CH00", 0x00, - ResourceConsumer,,) - } - } - } - - Device (CH01) - { - Name (_ADR, 1) - - Device (CLIB) - { - Name (_HID, ...) - Name (_CRS, ResourceTemplate () { - I2cSerialBus (0x50, ControllerInitiated, I2C_SPEED, - AddressingMode7Bit, "^CH01", 0x00, - ResourceConsumer,,) - } - } - } - } -} diff --git a/Documentation/firmware-guide/acpi/i2c-muxes.rst b/Documentation/firmware-guide/acpi/i2c-muxes.rst new file mode 100644 index 000000000000..3a8997ccd7c4 --- /dev/null +++ b/Documentation/firmware-guide/acpi/i2c-muxes.rst @@ -0,0 +1,61 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============== +ACPI I2C Muxes +============== + +Describing an I2C device hierarchy that includes I2C muxes requires an ACPI +Device () scope per mux channel. + +Consider this topology:: + + +------+ +------+ + | SMB1 |-->| MUX0 |--CH00--> i2c client A (0x50) + | | | 0x70 |--CH01--> i2c client B (0x50) + +------+ +------+ + +which corresponds to the following ASL:: + + Device (SMB1) + { + Name (_HID, ...) + Device (MUX0) + { + Name (_HID, ...) + Name (_CRS, ResourceTemplate () { + I2cSerialBus (0x70, ControllerInitiated, I2C_SPEED, + AddressingMode7Bit, "^SMB1", 0x00, + ResourceConsumer,,) + } + + Device (CH00) + { + Name (_ADR, 0) + + Device (CLIA) + { + Name (_HID, ...) + Name (_CRS, ResourceTemplate () { + I2cSerialBus (0x50, ControllerInitiated, I2C_SPEED, + AddressingMode7Bit, "^CH00", 0x00, + ResourceConsumer,,) + } + } + } + + Device (CH01) + { + Name (_ADR, 1) + + Device (CLIB) + { + Name (_HID, ...) + Name (_CRS, ResourceTemplate () { + I2cSerialBus (0x50, ControllerInitiated, I2C_SPEED, + AddressingMode7Bit, "^CH01", 0x00, + ResourceConsumer,,) + } + } + } + } + } diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index d1d069b26bbc..1c89888f6ee8 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -12,4 +12,5 @@ ACPI Support osi method-customizing DSD-properties-rules - gpio-properties \ No newline at end of file + gpio-properties + i2c-muxes -- cgit v1.2.3-59-g8ed1b From 011eed59ba6df428a1380fd1419a2a422f0d807a Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 25 Apr 2019 01:52:55 +0800 Subject: Documentation: ACPI: move acpi-lid.txt to firmware-guide/acpi and convert to reST This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/acpi-lid.txt | 96 --------------------- Documentation/firmware-guide/acpi/acpi-lid.rst | 114 +++++++++++++++++++++++++ Documentation/firmware-guide/acpi/index.rst | 1 + 3 files changed, 115 insertions(+), 96 deletions(-) delete mode 100644 Documentation/acpi/acpi-lid.txt create mode 100644 Documentation/firmware-guide/acpi/acpi-lid.rst (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/acpi/acpi-lid.txt b/Documentation/acpi/acpi-lid.txt deleted file mode 100644 index effe7af3a5af..000000000000 --- a/Documentation/acpi/acpi-lid.txt +++ /dev/null @@ -1,96 +0,0 @@ -Special Usage Model of the ACPI Control Method Lid Device - -Copyright (C) 2016, Intel Corporation -Author: Lv Zheng - - -Abstract: - -Platforms containing lids convey lid state (open/close) to OSPMs using a -control method lid device. To implement this, the AML tables issue -Notify(lid_device, 0x80) to notify the OSPMs whenever the lid state has -changed. The _LID control method for the lid device must be implemented to -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 -taken into account. This document describes the restrictions and the -expections of the Linux ACPI lid device driver. - - -1. Restrictions of the returning value of the _LID control method - -The _LID control method is described to return the "current" lid state. -However the word of "current" has ambiguity, some buggy AML tables return -the lid state upon the last lid notification instead of returning the lid -state upon the last _LID evaluation. There won't be difference when the -_LID control method is evaluated during the runtime, the problem is its -initial returning value. When the AML tables implement this control method -with cached value, the initial returning value is likely not reliable. -There are platforms always retun "closed" as initial lid state. - -2. Restrictions of the lid state change notifications - -There are buggy AML tables never notifying when the lid device state is -changed to "opened". Thus the "opened" notification is not guaranteed. But -it is guaranteed that the AML tables always notify "closed" when the lid -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. - -3. Expections for the userspace users of the ACPI lid device driver - -The ACPI button driver exports the lid state to the userspace via the -following file: - /proc/acpi/button/lid/LID0/state -This file actually calls the _LID control method described above. And given -the previous explanation, it is not reliable enough on some platforms. So -it is advised for the userspace program to not to solely rely on this file -to determine the actual lid state. - -The ACPI button driver emits the following input event to the userspace: - SW_LID -The ACPI lid device driver is implemented to try to deliver the platform -triggered events to the userspace. However, given the fact that the buggy -firmware cannot make sure "opened"/"closed" events are paired, the ACPI -button driver uses the following 3 modes in order not to trigger issues. - -If the userspace hasn't been prepared to ignore the unreliable "opened" -events and the unreliable initial state notification, Linux users can use -the following kernel parameters to handle the possible issues: -A. button.lid_init_state=method: - When this option is specified, the ACPI button driver reports the - initial lid state using the returning value of the _LID control method - and whether the "opened"/"closed" events are paired fully relies on the - firmware implementation. - This option can be used to fix some platforms where the returning value - of the _LID control method is reliable but the initial lid state - notification is missing. - This option is the default behavior during the period the userspace - isn't ready to handle the buggy AML tables. -B. button.lid_init_state=open: - When this option is specified, the ACPI button driver always reports the - initial lid state as "opened" and whether the "opened"/"closed" events - are paired fully relies on the firmware implementation. - This may fix some platforms where the returning value of the _LID - control method is not reliable and the initial lid state notification is - missing. - -If the userspace has been prepared to ignore the unreliable "opened" events -and the unreliable initial state notification, Linux users should always -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 - 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 - opens given that some AML tables do not send "opened" notifications - reliably. - In this mode, if everything is correctly implemented by the platform - firmware, the old userspace programs should still work. Otherwise, the - new userspace programs are required to work with the ACPI button driver. - This option will be the default behavior after the userspace is ready to - handle the buggy AML tables. diff --git a/Documentation/firmware-guide/acpi/acpi-lid.rst b/Documentation/firmware-guide/acpi/acpi-lid.rst new file mode 100644 index 000000000000..874ce0ed340d --- /dev/null +++ b/Documentation/firmware-guide/acpi/acpi-lid.rst @@ -0,0 +1,114 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +========================================================= +Special Usage Model of the ACPI Control Method Lid Device +========================================================= + +:Copyright: |copy| 2016, Intel Corporation + +:Author: Lv Zheng + +Abstract +======== +Platforms containing lids convey lid state (open/close) to OSPMs +using a control method lid device. To implement this, the AML tables issue +Notify(lid_device, 0x80) to notify the OSPMs whenever the lid state has +changed. The _LID control method for the lid device must be implemented to +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 +taken into account. This document describes the restrictions and the +expections of the Linux ACPI lid device driver. + + +Restrictions of the returning value of the _LID control method +============================================================== + +The _LID control method is described to return the "current" lid state. +However the word of "current" has ambiguity, some buggy AML tables return +the lid state upon the last lid notification instead of returning the lid +state upon the last _LID evaluation. There won't be difference when the +_LID control method is evaluated during the runtime, the problem is its +initial returning value. When the AML tables implement this control method +with cached value, the initial returning value is likely not reliable. +There are platforms always retun "closed" as initial lid state. + +Restrictions of the lid state change notifications +================================================== + +There are buggy AML tables never notifying when the lid device state is +changed to "opened". Thus the "opened" notification is not guaranteed. But +it is guaranteed that the AML tables always notify "closed" when the lid +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 +================================================================ + +The ACPI button driver exports the lid state to the userspace via the +following file:: + + /proc/acpi/button/lid/LID0/state + +This file actually calls the _LID control method described above. And given +the previous explanation, it is not reliable enough on some platforms. So +it is advised for the userspace program to not to solely rely on this file +to determine the actual lid state. + +The ACPI button driver emits the following input event to the userspace: + * SW_LID + +The ACPI lid device driver is implemented to try to deliver the platform +triggered events to the userspace. However, given the fact that the buggy +firmware cannot make sure "opened"/"closed" events are paired, the ACPI +button driver uses the following 3 modes in order not to trigger issues. + +If the userspace hasn't been prepared to ignore the unreliable "opened" +events and the unreliable initial state notification, Linux users can use +the following kernel parameters to handle the possible issues: + +A. button.lid_init_state=method: + When this option is specified, the ACPI button driver reports the + initial lid state using the returning value of the _LID control method + and whether the "opened"/"closed" events are paired fully relies on the + firmware implementation. + + This option can be used to fix some platforms where the returning value + of the _LID control method is reliable but the initial lid state + notification is missing. + + This option is the default behavior during the period the userspace + isn't ready to handle the buggy AML tables. + +B. button.lid_init_state=open: + When this option is specified, the ACPI button driver always reports the + initial lid state as "opened" and whether the "opened"/"closed" events + are paired fully relies on the firmware implementation. + + This may fix some platforms where the returning value of the _LID + control method is not reliable and the initial lid state notification is + missing. + +If the userspace has been prepared to ignore the unreliable "opened" events +and the unreliable initial state notification, Linux users should always +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 + 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 + opens given that some AML tables do not send "opened" notifications + reliably. + + In this mode, if everything is correctly implemented by the platform + firmware, the old userspace programs should still work. Otherwise, the + new userspace programs are required to work with the ACPI button driver. + This option will be the default behavior after the userspace is ready to + handle the buggy AML tables. diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index 1c89888f6ee8..bedcb0b242a2 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -14,3 +14,4 @@ ACPI Support DSD-properties-rules gpio-properties i2c-muxes + acpi-lid \ No newline at end of file -- cgit v1.2.3-59-g8ed1b From f2dde1ed0f2818405b371c2b65a98fece221b7a0 Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 25 Apr 2019 01:52:56 +0800 Subject: Documentation: ACPI: move dsd/graph.txt to firmware-guide/acpi and convert to reST This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/dsd/graph.txt | 174 ----------------------- Documentation/firmware-guide/acpi/dsd/graph.rst | 177 ++++++++++++++++++++++++ Documentation/firmware-guide/acpi/index.rst | 1 + 3 files changed, 178 insertions(+), 174 deletions(-) delete mode 100644 Documentation/acpi/dsd/graph.txt create mode 100644 Documentation/firmware-guide/acpi/dsd/graph.rst (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/acpi/dsd/graph.txt b/Documentation/acpi/dsd/graph.txt deleted file mode 100644 index b9ce910781dc..000000000000 --- a/Documentation/acpi/dsd/graph.txt +++ /dev/null @@ -1,174 +0,0 @@ -Graphs - - -_DSD ----- - -_DSD (Device Specific Data) [7] is a predefined ACPI device -configuration object that can be used to convey information on -hardware features which are not specifically covered by the ACPI -specification [1][6]. There are two _DSD extensions that are relevant -for graphs: property [4] and hierarchical data extensions [5]. The -property extension provides generic key-value pairs whereas the -hierarchical data extension supports nodes with references to other -nodes, forming a tree. The nodes in the tree may contain properties as -defined by the property extension. The two extensions together provide -a tree-like structure with zero or more properties (key-value pairs) -in each node of the tree. - -The data structure may be accessed at runtime by using the device_* -and fwnode_* functions defined in include/linux/fwnode.h . - -Fwnode represents a generic firmware node object. It is independent on -the firmware type. In ACPI, fwnodes are _DSD hierarchical data -extensions objects. A device's _DSD object is represented by an -fwnode. - -The data structure may be referenced to elsewhere in the ACPI tables -by using a hard reference to the device itself and an index to the -hierarchical data extension array on each depth. - - -Ports and endpoints -------------------- - -The port and endpoint concepts are very similar to those in Devicetree -[3]. A port represents an interface in a device, and an endpoint -represents a connection to that interface. - -All port nodes are located under the device's "_DSD" node in the hierarchical -data extension tree. The data extension related to each port node must begin -with "port" and must be followed by the "@" character and the number of the port -as its key. The target object it refers to should be called "PRTX", where "X" is -the number of the port. An example of such a package would be: - - Package() { "port@4", PRT4 } - -Further on, endpoints are located under the port nodes. The hierarchical -data extension key of the endpoint nodes must begin with -"endpoint" and must be followed by the "@" character and the number of the -endpoint. The object it refers to should be called "EPXY", where "X" is the -number of the port and "Y" is the number of the endpoint. An example of such a -package would be: - - Package() { "endpoint@0", EP40 } - -Each port node contains a property extension key "port", the value of which is -the number of the port. Each endpoint is similarly numbered with a property -extension key "reg", the value of which is the number of the endpoint. Port -numbers must be unique within a device and endpoint numbers must be unique -within a port. If a device object may only has a single port, then the number -of that port shall be zero. Similarly, if a port may only have a single -endpoint, the number of that endpoint shall be zero. - -The endpoint reference uses property extension with "remote-endpoint" property -name followed by a reference in the same package. Such references consist of the -the remote device reference, the first package entry of the port data extension -reference under the device and finally the first package entry of the endpoint -data extension reference under the port. Individual references thus appear as: - - Package() { device, "port@X", "endpoint@Y" } - -In the above example, "X" is the number of the port and "Y" is the number of the -endpoint. - -The references to endpoints must be always done both ways, to the -remote endpoint and back from the referred remote endpoint node. - -A simple example of this is show below: - - Scope (\_SB.PCI0.I2C2) - { - Device (CAM0) - { - Name (_DSD, Package () { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () { - Package () { "compatible", Package () { "nokia,smia" } }, - }, - ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), - Package () { - Package () { "port@0", PRT0 }, - } - }) - Name (PRT0, Package() { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () { - Package () { "reg", 0 }, - }, - ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), - Package () { - Package () { "endpoint@0", EP00 }, - } - }) - Name (EP00, Package() { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () { - Package () { "reg", 0 }, - Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } }, - } - }) - } - } - - Scope (\_SB.PCI0) - { - Device (ISP) - { - Name (_DSD, Package () { - ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), - Package () { - Package () { "port@4", PRT4 }, - } - }) - - Name (PRT4, Package() { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () { - Package () { "reg", 4 }, /* CSI-2 port number */ - }, - ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), - Package () { - Package () { "endpoint@0", EP40 }, - } - }) - - Name (EP40, Package() { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () { - Package () { "reg", 0 }, - Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } }, - } - }) - } - } - -Here, the port 0 of the "CAM0" device is connected to the port 4 of -the "ISP" device and vice versa. - - -References ----------- - -[1] _DSD (Device Specific Data) Implementation Guide. - , - referenced 2016-10-03. - -[2] Devicetree. , referenced 2016-10-03. - -[3] Documentation/devicetree/bindings/graph.txt - -[4] Device Properties UUID For _DSD. - , - referenced 2016-10-04. - -[5] Hierarchical Data Extension UUID For _DSD. - , - referenced 2016-10-04. - -[6] Advanced Configuration and Power Interface Specification. - , - referenced 2016-10-04. - -[7] _DSD Device Properties Usage Rules. - Documentation/acpi/DSD-properties-rules.txt diff --git a/Documentation/firmware-guide/acpi/dsd/graph.rst b/Documentation/firmware-guide/acpi/dsd/graph.rst new file mode 100644 index 000000000000..e0baed35b037 --- /dev/null +++ b/Documentation/firmware-guide/acpi/dsd/graph.rst @@ -0,0 +1,177 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====== +Graphs +====== + +_DSD +==== + +_DSD (Device Specific Data) [7] is a predefined ACPI device +configuration object that can be used to convey information on +hardware features which are not specifically covered by the ACPI +specification [1][6]. There are two _DSD extensions that are relevant +for graphs: property [4] and hierarchical data extensions [5]. The +property extension provides generic key-value pairs whereas the +hierarchical data extension supports nodes with references to other +nodes, forming a tree. The nodes in the tree may contain properties as +defined by the property extension. The two extensions together provide +a tree-like structure with zero or more properties (key-value pairs) +in each node of the tree. + +The data structure may be accessed at runtime by using the device_* +and fwnode_* functions defined in include/linux/fwnode.h . + +Fwnode represents a generic firmware node object. It is independent on +the firmware type. In ACPI, fwnodes are _DSD hierarchical data +extensions objects. A device's _DSD object is represented by an +fwnode. + +The data structure may be referenced to elsewhere in the ACPI tables +by using a hard reference to the device itself and an index to the +hierarchical data extension array on each depth. + + +Ports and endpoints +=================== + +The port and endpoint concepts are very similar to those in Devicetree +[3]. A port represents an interface in a device, and an endpoint +represents a connection to that interface. + +All port nodes are located under the device's "_DSD" node in the hierarchical +data extension tree. The data extension related to each port node must begin +with "port" and must be followed by the "@" character and the number of the +port as its key. The target object it refers to should be called "PRTX", where +"X" is the number of the port. An example of such a package would be:: + + Package() { "port@4", PRT4 } + +Further on, endpoints are located under the port nodes. The hierarchical +data extension key of the endpoint nodes must begin with +"endpoint" and must be followed by the "@" character and the number of the +endpoint. The object it refers to should be called "EPXY", where "X" is the +number of the port and "Y" is the number of the endpoint. An example of such a +package would be:: + + Package() { "endpoint@0", EP40 } + +Each port node contains a property extension key "port", the value of which is +the number of the port. Each endpoint is similarly numbered with a property +extension key "reg", the value of which is the number of the endpoint. Port +numbers must be unique within a device and endpoint numbers must be unique +within a port. If a device object may only has a single port, then the number +of that port shall be zero. Similarly, if a port may only have a single +endpoint, the number of that endpoint shall be zero. + +The endpoint reference uses property extension with "remote-endpoint" property +name followed by a reference in the same package. Such references consist of +the remote device reference, the first package entry of the port data extension +reference under the device and finally the first package entry of the endpoint +data extension reference under the port. Individual references thus appear as:: + + Package() { device, "port@X", "endpoint@Y" } + +In the above example, "X" is the number of the port and "Y" is the number of +the endpoint. + +The references to endpoints must be always done both ways, to the +remote endpoint and back from the referred remote endpoint node. + +A simple example of this is show below:: + + Scope (\_SB.PCI0.I2C2) + { + Device (CAM0) + { + Name (_DSD, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "compatible", Package () { "nokia,smia" } }, + }, + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "port@0", PRT0 }, + } + }) + Name (PRT0, Package() { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reg", 0 }, + }, + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "endpoint@0", EP00 }, + } + }) + Name (EP00, Package() { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reg", 0 }, + Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } }, + } + }) + } + } + + Scope (\_SB.PCI0) + { + Device (ISP) + { + Name (_DSD, Package () { + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "port@4", PRT4 }, + } + }) + + Name (PRT4, Package() { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reg", 4 }, /* CSI-2 port number */ + }, + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "endpoint@0", EP40 }, + } + }) + + Name (EP40, Package() { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reg", 0 }, + Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } }, + } + }) + } + } + +Here, the port 0 of the "CAM0" device is connected to the port 4 of +the "ISP" device and vice versa. + + +References +========== + +[1] _DSD (Device Specific Data) Implementation Guide. + http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm, + referenced 2016-10-03. + +[2] Devicetree. http://www.devicetree.org, referenced 2016-10-03. + +[3] Documentation/devicetree/bindings/graph.txt + +[4] Device Properties UUID For _DSD. + http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf, + referenced 2016-10-04. + +[5] Hierarchical Data Extension UUID For _DSD. + http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf, + referenced 2016-10-04. + +[6] Advanced Configuration and Power Interface Specification. + http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf, + referenced 2016-10-04. + +[7] _DSD Device Properties Usage Rules. + :doc:`../DSD-properties-rules` diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index bedcb0b242a2..f81cfbcb6878 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -8,6 +8,7 @@ ACPI Support :maxdepth: 1 namespace + dsd/graph enumeration osi method-customizing -- cgit v1.2.3-59-g8ed1b From 05000042f33dd8b2afbeedc1d8fd499486d14b0d Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 25 Apr 2019 01:52:57 +0800 Subject: Documentation: ACPI: move dsd/data-node-references.txt to firmware-guide/acpi and convert to reST This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/dsd/data-node-references.txt | 89 --------------------- .../acpi/dsd/data-node-references.rst | 93 ++++++++++++++++++++++ Documentation/firmware-guide/acpi/index.rst | 1 + 3 files changed, 94 insertions(+), 89 deletions(-) delete mode 100644 Documentation/acpi/dsd/data-node-references.txt create mode 100644 Documentation/firmware-guide/acpi/dsd/data-node-references.rst (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/acpi/dsd/data-node-references.txt b/Documentation/acpi/dsd/data-node-references.txt deleted file mode 100644 index c3871565c8cf..000000000000 --- a/Documentation/acpi/dsd/data-node-references.txt +++ /dev/null @@ -1,89 +0,0 @@ -Copyright (C) 2018 Intel Corporation -Author: Sakari Ailus - - -Referencing hierarchical data nodes ------------------------------------ - -ACPI in general allows referring to device objects in the tree only. -Hierarchical data extension nodes may not be referred to directly, hence this -document defines a scheme to implement such references. - -A reference consist of the device object name followed by one or more -hierarchical data extension [1] keys. Specifically, the hierarchical data -extension node which is referred to by the key shall lie directly under the -parent object i.e. either the device object or another hierarchical data -extension node. - -The keys in the hierarchical data nodes shall consist of the name of the node, -"@" character and the number of the node in hexadecimal notation (without pre- -or postfixes). The same ACPI object shall include the _DSD property extension -with a property "reg" that shall have the same numerical value as the number of -the node. - -In case a hierarchical data extensions node has no numerical value, then the -"reg" property shall be omitted from the ACPI object's _DSD properties and the -"@" character and the number shall be omitted from the hierarchical data -extension key. - - -Example -------- - - In the ASL snippet below, the "reference" _DSD property [2] contains a - device object reference to DEV0 and under that device object, a - hierarchical data extension key "node@1" referring to the NOD1 object - and lastly, a hierarchical data extension key "anothernode" referring to - the ANOD object which is also the final target node of the reference. - - Device (DEV0) - { - Name (_DSD, Package () { - ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), - Package () { - Package () { "node@0", NOD0 }, - Package () { "node@1", NOD1 }, - } - }) - Name (NOD0, Package() { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () { - Package () { "random-property", 3 }, - } - }) - Name (NOD1, Package() { - ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), - Package () { - Package () { "anothernode", ANOD }, - } - }) - Name (ANOD, Package() { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () { - Package () { "random-property", 0 }, - } - }) - } - - Device (DEV1) - { - Name (_DSD, Package () { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () { - Package () { "reference", ^DEV0, "node@1", "anothernode" }, - } - }) - } - -Please also see a graph example in graph.txt . - -References ----------- - -[1] Hierarchical Data Extension UUID For _DSD. - , - referenced 2018-07-17. - -[2] Device Properties UUID For _DSD. - , - referenced 2016-10-04. diff --git a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst new file mode 100644 index 000000000000..1351984e767c --- /dev/null +++ b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst @@ -0,0 +1,93 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +=================================== +Referencing hierarchical data nodes +=================================== + +:Copyright: |copy| 2018 Intel Corporation +:Author: Sakari Ailus + +ACPI in general allows referring to device objects in the tree only. +Hierarchical data extension nodes may not be referred to directly, hence this +document defines a scheme to implement such references. + +A reference consist of the device object name followed by one or more +hierarchical data extension [1] keys. Specifically, the hierarchical data +extension node which is referred to by the key shall lie directly under the +parent object i.e. either the device object or another hierarchical data +extension node. + +The keys in the hierarchical data nodes shall consist of the name of the node, +"@" character and the number of the node in hexadecimal notation (without pre- +or postfixes). The same ACPI object shall include the _DSD property extension +with a property "reg" that shall have the same numerical value as the number of +the node. + +In case a hierarchical data extensions node has no numerical value, then the +"reg" property shall be omitted from the ACPI object's _DSD properties and the +"@" character and the number shall be omitted from the hierarchical data +extension key. + + +Example +======= + +In the ASL snippet below, the "reference" _DSD property [2] contains a +device object reference to DEV0 and under that device object, a +hierarchical data extension key "node@1" referring to the NOD1 object +and lastly, a hierarchical data extension key "anothernode" referring to +the ANOD object which is also the final target node of the reference. +:: + + Device (DEV0) + { + Name (_DSD, Package () { + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "node@0", NOD0 }, + Package () { "node@1", NOD1 }, + } + }) + Name (NOD0, Package() { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "random-property", 3 }, + } + }) + Name (NOD1, Package() { + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "anothernode", ANOD }, + } + }) + Name (ANOD, Package() { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "random-property", 0 }, + } + }) + } + + Device (DEV1) + { + Name (_DSD, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reference", ^DEV0, "node@1", "anothernode" }, + } + }) + } + +Please also see a graph example in :doc:`graph`. + +References +========== + +[1] Hierarchical Data Extension UUID For _DSD. +, +referenced 2018-07-17. + +[2] Device Properties UUID For _DSD. +, +referenced 2016-10-04. diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index f81cfbcb6878..6d4e0df4f063 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -9,6 +9,7 @@ ACPI Support namespace dsd/graph + dsd/data-node-references enumeration osi method-customizing -- cgit v1.2.3-59-g8ed1b From 99ed6bfaa5a0a4bffc10ff3ffe9c599bcf59236e Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 25 Apr 2019 01:52:58 +0800 Subject: Documentation: ACPI: move debug.txt to firmware-guide/acpi and convert to reST This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/debug.txt | 148 --------------------------- Documentation/firmware-guide/acpi/debug.rst | 151 ++++++++++++++++++++++++++++ Documentation/firmware-guide/acpi/index.rst | 3 +- 3 files changed, 153 insertions(+), 149 deletions(-) delete mode 100644 Documentation/acpi/debug.txt create mode 100644 Documentation/firmware-guide/acpi/debug.rst (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/acpi/debug.txt b/Documentation/acpi/debug.txt deleted file mode 100644 index 65bf47c46b6d..000000000000 --- a/Documentation/acpi/debug.txt +++ /dev/null @@ -1,148 +0,0 @@ - ACPI Debug Output - - -The ACPI CA, the Linux ACPI core, and some ACPI drivers can generate debug -output. This document describes how to use this facility. - -Compile-time configuration --------------------------- - -ACPI debug output is globally enabled by CONFIG_ACPI_DEBUG. If this config -option is turned off, the debug messages are not even built into the -kernel. - -Boot- and run-time configuration --------------------------------- - -When CONFIG_ACPI_DEBUG=y, you can select the component and level of messages -you're interested in. At boot-time, use the acpi.debug_layer and -acpi.debug_level kernel command line options. After boot, you can use the -debug_layer and debug_level files in /sys/module/acpi/parameters/ to control -the debug messages. - -debug_layer (component) ------------------------ - -The "debug_layer" is a mask that selects components of interest, e.g., a -specific driver or part of the ACPI interpreter. To build the debug_layer -bitmask, look for the "#define _COMPONENT" in an ACPI source file. - -You can set the debug_layer mask at boot-time using the acpi.debug_layer -command line argument, and you can change it after boot by writing values -to /sys/module/acpi/parameters/debug_layer. - -The possible components are defined in include/acpi/acoutput.h and -include/acpi/acpi_drivers.h. Reading /sys/module/acpi/parameters/debug_layer -shows the supported mask values, currently these: - - ACPI_UTILITIES 0x00000001 - ACPI_HARDWARE 0x00000002 - ACPI_EVENTS 0x00000004 - ACPI_TABLES 0x00000008 - ACPI_NAMESPACE 0x00000010 - ACPI_PARSER 0x00000020 - ACPI_DISPATCHER 0x00000040 - ACPI_EXECUTER 0x00000080 - ACPI_RESOURCES 0x00000100 - ACPI_CA_DEBUGGER 0x00000200 - ACPI_OS_SERVICES 0x00000400 - ACPI_CA_DISASSEMBLER 0x00000800 - ACPI_COMPILER 0x00001000 - ACPI_TOOLS 0x00002000 - ACPI_BUS_COMPONENT 0x00010000 - ACPI_AC_COMPONENT 0x00020000 - ACPI_BATTERY_COMPONENT 0x00040000 - ACPI_BUTTON_COMPONENT 0x00080000 - ACPI_SBS_COMPONENT 0x00100000 - ACPI_FAN_COMPONENT 0x00200000 - ACPI_PCI_COMPONENT 0x00400000 - ACPI_POWER_COMPONENT 0x00800000 - ACPI_CONTAINER_COMPONENT 0x01000000 - ACPI_SYSTEM_COMPONENT 0x02000000 - ACPI_THERMAL_COMPONENT 0x04000000 - ACPI_MEMORY_DEVICE_COMPONENT 0x08000000 - ACPI_VIDEO_COMPONENT 0x10000000 - ACPI_PROCESSOR_COMPONENT 0x20000000 - -debug_level ------------ - -The "debug_level" is a mask that selects different types of messages, e.g., -those related to initialization, method execution, informational messages, etc. -To build debug_level, look at the level specified in an ACPI_DEBUG_PRINT() -statement. - -The ACPI interpreter uses several different levels, but the Linux -ACPI core and ACPI drivers generally only use ACPI_LV_INFO. - -You can set the debug_level mask at boot-time using the acpi.debug_level -command line argument, and you can change it after boot by writing values -to /sys/module/acpi/parameters/debug_level. - -The possible levels are defined in include/acpi/acoutput.h. Reading -/sys/module/acpi/parameters/debug_level shows the supported mask values, -currently these: - - ACPI_LV_INIT 0x00000001 - ACPI_LV_DEBUG_OBJECT 0x00000002 - ACPI_LV_INFO 0x00000004 - ACPI_LV_INIT_NAMES 0x00000020 - ACPI_LV_PARSE 0x00000040 - ACPI_LV_LOAD 0x00000080 - ACPI_LV_DISPATCH 0x00000100 - ACPI_LV_EXEC 0x00000200 - ACPI_LV_NAMES 0x00000400 - ACPI_LV_OPREGION 0x00000800 - ACPI_LV_BFIELD 0x00001000 - ACPI_LV_TABLES 0x00002000 - ACPI_LV_VALUES 0x00004000 - ACPI_LV_OBJECTS 0x00008000 - ACPI_LV_RESOURCES 0x00010000 - ACPI_LV_USER_REQUESTS 0x00020000 - ACPI_LV_PACKAGE 0x00040000 - ACPI_LV_ALLOCATIONS 0x00100000 - ACPI_LV_FUNCTIONS 0x00200000 - ACPI_LV_OPTIMIZATIONS 0x00400000 - ACPI_LV_MUTEX 0x01000000 - ACPI_LV_THREADS 0x02000000 - ACPI_LV_IO 0x04000000 - ACPI_LV_INTERRUPTS 0x08000000 - ACPI_LV_AML_DISASSEMBLE 0x10000000 - ACPI_LV_VERBOSE_INFO 0x20000000 - ACPI_LV_FULL_TABLES 0x40000000 - ACPI_LV_EVENTS 0x80000000 - -Examples --------- - -For example, drivers/acpi/bus.c contains this: - - #define _COMPONENT ACPI_BUS_COMPONENT - ... - ACPI_DEBUG_PRINT((ACPI_DB_INFO, "Device insertion detected\n")); - -To turn on this message, set the ACPI_BUS_COMPONENT bit in acpi.debug_layer -and the ACPI_LV_INFO bit in acpi.debug_level. (The ACPI_DEBUG_PRINT -statement uses ACPI_DB_INFO, which is macro based on the ACPI_LV_INFO -definition.) - -Enable all AML "Debug" output (stores to the Debug object while interpreting -AML) during boot: - - acpi.debug_layer=0xffffffff acpi.debug_level=0x2 - -Enable PCI and PCI interrupt routing debug messages: - - acpi.debug_layer=0x400000 acpi.debug_level=0x4 - -Enable all ACPI hardware-related messages: - - acpi.debug_layer=0x2 acpi.debug_level=0xffffffff - -Enable all ACPI_DB_INFO messages after boot: - - # echo 0x4 > /sys/module/acpi/parameters/debug_level - -Show all valid component values: - - # cat /sys/module/acpi/parameters/debug_layer diff --git a/Documentation/firmware-guide/acpi/debug.rst b/Documentation/firmware-guide/acpi/debug.rst new file mode 100644 index 000000000000..1a152dd1d765 --- /dev/null +++ b/Documentation/firmware-guide/acpi/debug.rst @@ -0,0 +1,151 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================= +ACPI Debug Output +================= + +The ACPI CA, the Linux ACPI core, and some ACPI drivers can generate debug +output. This document describes how to use this facility. + +Compile-time configuration +========================== + +ACPI debug output is globally enabled by CONFIG_ACPI_DEBUG. If this config +option is turned off, the debug messages are not even built into the +kernel. + +Boot- and run-time configuration +================================ + +When CONFIG_ACPI_DEBUG=y, you can select the component and level of messages +you're interested in. At boot-time, use the acpi.debug_layer and +acpi.debug_level kernel command line options. After boot, you can use the +debug_layer and debug_level files in /sys/module/acpi/parameters/ to control +the debug messages. + +debug_layer (component) +======================= + +The "debug_layer" is a mask that selects components of interest, e.g., a +specific driver or part of the ACPI interpreter. To build the debug_layer +bitmask, look for the "#define _COMPONENT" in an ACPI source file. + +You can set the debug_layer mask at boot-time using the acpi.debug_layer +command line argument, and you can change it after boot by writing values +to /sys/module/acpi/parameters/debug_layer. + +The possible components are defined in include/acpi/acoutput.h and +include/acpi/acpi_drivers.h. Reading /sys/module/acpi/parameters/debug_layer +shows the supported mask values, currently these:: + + ACPI_UTILITIES 0x00000001 + ACPI_HARDWARE 0x00000002 + ACPI_EVENTS 0x00000004 + ACPI_TABLES 0x00000008 + ACPI_NAMESPACE 0x00000010 + ACPI_PARSER 0x00000020 + ACPI_DISPATCHER 0x00000040 + ACPI_EXECUTER 0x00000080 + ACPI_RESOURCES 0x00000100 + ACPI_CA_DEBUGGER 0x00000200 + ACPI_OS_SERVICES 0x00000400 + ACPI_CA_DISASSEMBLER 0x00000800 + ACPI_COMPILER 0x00001000 + ACPI_TOOLS 0x00002000 + ACPI_BUS_COMPONENT 0x00010000 + ACPI_AC_COMPONENT 0x00020000 + ACPI_BATTERY_COMPONENT 0x00040000 + ACPI_BUTTON_COMPONENT 0x00080000 + ACPI_SBS_COMPONENT 0x00100000 + ACPI_FAN_COMPONENT 0x00200000 + ACPI_PCI_COMPONENT 0x00400000 + ACPI_POWER_COMPONENT 0x00800000 + ACPI_CONTAINER_COMPONENT 0x01000000 + ACPI_SYSTEM_COMPONENT 0x02000000 + ACPI_THERMAL_COMPONENT 0x04000000 + ACPI_MEMORY_DEVICE_COMPONENT 0x08000000 + ACPI_VIDEO_COMPONENT 0x10000000 + ACPI_PROCESSOR_COMPONENT 0x20000000 + +debug_level +=========== + +The "debug_level" is a mask that selects different types of messages, e.g., +those related to initialization, method execution, informational messages, etc. +To build debug_level, look at the level specified in an ACPI_DEBUG_PRINT() +statement. + +The ACPI interpreter uses several different levels, but the Linux +ACPI core and ACPI drivers generally only use ACPI_LV_INFO. + +You can set the debug_level mask at boot-time using the acpi.debug_level +command line argument, and you can change it after boot by writing values +to /sys/module/acpi/parameters/debug_level. + +The possible levels are defined in include/acpi/acoutput.h. Reading +/sys/module/acpi/parameters/debug_level shows the supported mask values, +currently these:: + + ACPI_LV_INIT 0x00000001 + ACPI_LV_DEBUG_OBJECT 0x00000002 + ACPI_LV_INFO 0x00000004 + ACPI_LV_INIT_NAMES 0x00000020 + ACPI_LV_PARSE 0x00000040 + ACPI_LV_LOAD 0x00000080 + ACPI_LV_DISPATCH 0x00000100 + ACPI_LV_EXEC 0x00000200 + ACPI_LV_NAMES 0x00000400 + ACPI_LV_OPREGION 0x00000800 + ACPI_LV_BFIELD 0x00001000 + ACPI_LV_TABLES 0x00002000 + ACPI_LV_VALUES 0x00004000 + ACPI_LV_OBJECTS 0x00008000 + ACPI_LV_RESOURCES 0x00010000 + ACPI_LV_USER_REQUESTS 0x00020000 + ACPI_LV_PACKAGE 0x00040000 + ACPI_LV_ALLOCATIONS 0x00100000 + ACPI_LV_FUNCTIONS 0x00200000 + ACPI_LV_OPTIMIZATIONS 0x00400000 + ACPI_LV_MUTEX 0x01000000 + ACPI_LV_THREADS 0x02000000 + ACPI_LV_IO 0x04000000 + ACPI_LV_INTERRUPTS 0x08000000 + ACPI_LV_AML_DISASSEMBLE 0x10000000 + ACPI_LV_VERBOSE_INFO 0x20000000 + ACPI_LV_FULL_TABLES 0x40000000 + ACPI_LV_EVENTS 0x80000000 + +Examples +======== + +For example, drivers/acpi/bus.c contains this:: + + #define _COMPONENT ACPI_BUS_COMPONENT + ... + ACPI_DEBUG_PRINT((ACPI_DB_INFO, "Device insertion detected\n")); + +To turn on this message, set the ACPI_BUS_COMPONENT bit in acpi.debug_layer +and the ACPI_LV_INFO bit in acpi.debug_level. (The ACPI_DEBUG_PRINT +statement uses ACPI_DB_INFO, which is macro based on the ACPI_LV_INFO +definition.) + +Enable all AML "Debug" output (stores to the Debug object while interpreting +AML) during boot:: + + acpi.debug_layer=0xffffffff acpi.debug_level=0x2 + +Enable PCI and PCI interrupt routing debug messages:: + + acpi.debug_layer=0x400000 acpi.debug_level=0x4 + +Enable all ACPI hardware-related messages:: + + acpi.debug_layer=0x2 acpi.debug_level=0xffffffff + +Enable all ACPI_DB_INFO messages after boot:: + + # echo 0x4 > /sys/module/acpi/parameters/debug_level + +Show all valid component values:: + + # cat /sys/module/acpi/parameters/debug_layer diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index 6d4e0df4f063..a45fea11f998 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -14,6 +14,7 @@ ACPI Support osi method-customizing DSD-properties-rules + debug gpio-properties i2c-muxes - acpi-lid \ No newline at end of file + acpi-lid -- cgit v1.2.3-59-g8ed1b From 3c03a1bde4dcedef8fb287e348de959d81d04ca6 Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 25 Apr 2019 01:52:59 +0800 Subject: Documentation: ACPI: move method-tracing.txt to firmware-guide/acpi and convert to rsST This converts the plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/method-tracing.txt | 192 ----------------- Documentation/firmware-guide/acpi/index.rst | 1 + .../firmware-guide/acpi/method-tracing.rst | 238 +++++++++++++++++++++ 3 files changed, 239 insertions(+), 192 deletions(-) delete mode 100644 Documentation/acpi/method-tracing.txt create mode 100644 Documentation/firmware-guide/acpi/method-tracing.rst (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/acpi/method-tracing.txt b/Documentation/acpi/method-tracing.txt deleted file mode 100644 index 0aba14c8f459..000000000000 --- a/Documentation/acpi/method-tracing.txt +++ /dev/null @@ -1,192 +0,0 @@ -ACPICA Trace Facility - -Copyright (C) 2015, Intel Corporation -Author: Lv Zheng - - -Abstract: - -This document describes the functions and the interfaces of the method -tracing facility. - -1. Functionalities and usage examples: - - ACPICA provides method tracing capability. And two functions are - currently implemented using this capability. - - A. Log reducer - ACPICA subsystem provides debugging outputs when CONFIG_ACPI_DEBUG is - enabled. The debugging messages which are deployed via - ACPI_DEBUG_PRINT() macro can be reduced at 2 levels - per-component - level (known as debug layer, configured via - /sys/module/acpi/parameters/debug_layer) and per-type level (known as - debug level, configured via /sys/module/acpi/parameters/debug_level). - - But when the particular layer/level is applied to the control method - evaluations, the quantity of the debugging outputs may still be too - large to be put into the kernel log buffer. The idea thus is worked out - to only enable the particular debug layer/level (normally more detailed) - logs when the control method evaluation is started, and disable the - detailed logging when the control method evaluation is stopped. - - The following command examples illustrate the usage of the "log reducer" - functionality: - a. Filter out the debug layer/level matched logs when control methods - are being evaluated: - # cd /sys/module/acpi/parameters - # echo "0xXXXXXXXX" > trace_debug_layer - # echo "0xYYYYYYYY" > trace_debug_level - # echo "enable" > trace_state - b. Filter out the debug layer/level matched logs when the specified - control method is being evaluated: - # cd /sys/module/acpi/parameters - # echo "0xXXXXXXXX" > trace_debug_layer - # echo "0xYYYYYYYY" > trace_debug_level - # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name - # echo "method" > /sys/module/acpi/parameters/trace_state - c. Filter out the debug layer/level matched logs when the specified - control method is being evaluated for the first time: - # cd /sys/module/acpi/parameters - # echo "0xXXXXXXXX" > trace_debug_layer - # echo "0xYYYYYYYY" > trace_debug_level - # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name - # echo "method-once" > /sys/module/acpi/parameters/trace_state - Where: - 0xXXXXXXXX/0xYYYYYYYY: Refer to Documentation/acpi/debug.txt for - possible debug layer/level masking values. - \PPPP.AAAA.TTTT.HHHH: Full path of a control method that can be found - in the ACPI namespace. It needn't be an entry - of a control method evaluation. - - B. AML tracer - - There are special log entries added by the method tracing facility at - the "trace points" the AML interpreter starts/stops to execute a control - method, or an AML opcode. Note that the format of the log entries are - subject to change: - [ 0.186427] exdebug-0398 ex_trace_point : Method Begin [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution. - [ 0.186630] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905c88:If] execution. - [ 0.186820] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905cc0:LEqual] execution. - [ 0.187010] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905a20:-NamePath-] execution. - [ 0.187214] exdebug-0398 ex_trace_point : Opcode End [0xf5905a20:-NamePath-] execution. - [ 0.187407] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905f60:One] execution. - [ 0.187594] exdebug-0398 ex_trace_point : Opcode End [0xf5905f60:One] execution. - [ 0.187789] exdebug-0398 ex_trace_point : Opcode End [0xf5905cc0:LEqual] execution. - [ 0.187980] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905cc0:Return] execution. - [ 0.188146] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905f60:One] execution. - [ 0.188334] exdebug-0398 ex_trace_point : Opcode End [0xf5905f60:One] execution. - [ 0.188524] exdebug-0398 ex_trace_point : Opcode End [0xf5905cc0:Return] execution. - [ 0.188712] exdebug-0398 ex_trace_point : Opcode End [0xf5905c88:If] execution. - [ 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 - 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. - - The following command examples illustrate the usage of the "AML tracer" - functionality: - a. Filter out the method start/stop "AML tracer" logs when control - methods are being evaluated: - # cd /sys/module/acpi/parameters - # echo "0x80" > trace_debug_layer - # echo "0x10" > trace_debug_level - # echo "enable" > trace_state - b. Filter out the method start/stop "AML tracer" when the specified - control method is being evaluated: - # cd /sys/module/acpi/parameters - # echo "0x80" > trace_debug_layer - # echo "0x10" > trace_debug_level - # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name - # echo "method" > trace_state - c. Filter out the method start/stop "AML tracer" logs when the specified - control method is being evaluated for the first time: - # cd /sys/module/acpi/parameters - # echo "0x80" > trace_debug_layer - # echo "0x10" > trace_debug_level - # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name - # echo "method-once" > trace_state - d. Filter out the method/opcode start/stop "AML tracer" when the - specified control method is being evaluated: - # cd /sys/module/acpi/parameters - # echo "0x80" > trace_debug_layer - # echo "0x10" > trace_debug_level - # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name - # echo "opcode" > trace_state - e. Filter out the method/opcode start/stop "AML tracer" when the - specified control method is being evaluated for the first time: - # cd /sys/module/acpi/parameters - # echo "0x80" > trace_debug_layer - # echo "0x10" > trace_debug_level - # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name - # echo "opcode-opcode" > trace_state - - Note that all above method tracing facility related module parameters can - be used as the boot parameters, for example: - acpi.trace_debug_layer=0x80 acpi.trace_debug_level=0x10 \ - acpi.trace_method_name=\_SB.LID0._LID acpi.trace_state=opcode-once - -2. Interface descriptions: - - All method tracing functions can be configured via ACPI module - parameters that are accessible at /sys/module/acpi/parameters/: - - trace_method_name - The full path of the AML method that the user wants to trace. - Note that the full path shouldn't contain the trailing "_"s in its - name segments but may contain "\" to form an absolute path. - - trace_debug_layer - The temporary debug_layer used when the tracing feature is enabled. - Using ACPI_EXECUTER (0x80) by default, which is the debug_layer - used to match all "AML tracer" logs. - - trace_debug_level - The temporary debug_level used when the tracing feature is enabled. - Using ACPI_LV_TRACE_POINT (0x10) by default, which is the - debug_level used to match all "AML tracer" logs. - - trace_state - The status of the tracing feature. - Users can enable/disable this debug tracing feature by executing - the following command: - # echo string > /sys/module/acpi/parameters/trace_state - Where "string" should be one of the following: - "disable" - Disable the method tracing feature. - "enable" - Enable the method tracing feature. - ACPICA debugging messages matching - "trace_debug_layer/trace_debug_level" during any method - execution will be logged. - "method" - Enable the method tracing feature. - ACPICA debugging messages matching - "trace_debug_layer/trace_debug_level" during method execution - of "trace_method_name" will be logged. - "method-once" - Enable the method tracing feature. - ACPICA debugging messages matching - "trace_debug_layer/trace_debug_level" during method execution - of "trace_method_name" will be logged only once. - "opcode" - Enable the method tracing feature. - ACPICA debugging messages matching - "trace_debug_layer/trace_debug_level" during method/opcode - execution of "trace_method_name" will be logged. - "opcode-once" - Enable the method tracing feature. - ACPICA debugging messages matching - "trace_debug_layer/trace_debug_level" during method/opcode - execution of "trace_method_name" will be logged only once. - Note that, the difference between the "enable" and other feature - enabling options are: - 1. When "enable" is specified, since - "trace_debug_layer/trace_debug_level" shall apply to all control - method evaluations, after configuring "trace_state" to "enable", - "trace_method_name" will be reset to NULL. - 2. When "method/opcode" is specified, if - "trace_method_name" is NULL when "trace_state" is configured to - these options, the "trace_debug_layer/trace_debug_level" will - apply to all control method evaluations. diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index a45fea11f998..287a7cbd82ac 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -13,6 +13,7 @@ ACPI Support enumeration osi method-customizing + method-tracing DSD-properties-rules debug gpio-properties diff --git a/Documentation/firmware-guide/acpi/method-tracing.rst b/Documentation/firmware-guide/acpi/method-tracing.rst new file mode 100644 index 000000000000..d0b077b73f5f --- /dev/null +++ b/Documentation/firmware-guide/acpi/method-tracing.rst @@ -0,0 +1,238 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +===================== +ACPICA Trace Facility +===================== + +:Copyright: |copy| 2015, Intel Corporation +:Author: Lv Zheng + + +Abstract +======== +This document describes the functions and the interfaces of the +method tracing facility. + +Functionalities and usage examples +================================== + +ACPICA provides method tracing capability. And two functions are +currently implemented using this capability. + +Log reducer +----------- + +ACPICA subsystem provides debugging outputs when CONFIG_ACPI_DEBUG is +enabled. The debugging messages which are deployed via +ACPI_DEBUG_PRINT() macro can be reduced at 2 levels - per-component +level (known as debug layer, configured via +/sys/module/acpi/parameters/debug_layer) and per-type level (known as +debug level, configured via /sys/module/acpi/parameters/debug_level). + +But when the particular layer/level is applied to the control method +evaluations, the quantity of the debugging outputs may still be too +large to be put into the kernel log buffer. The idea thus is worked out +to only enable the particular debug layer/level (normally more detailed) +logs when the control method evaluation is started, and disable the +detailed logging when the control method evaluation is stopped. + +The following command examples illustrate the usage of the "log reducer" +functionality: + +a. Filter out the debug layer/level matched logs when control methods + are being evaluated:: + + # cd /sys/module/acpi/parameters + # echo "0xXXXXXXXX" > trace_debug_layer + # echo "0xYYYYYYYY" > trace_debug_level + # echo "enable" > trace_state + +b. Filter out the debug layer/level matched logs when the specified + control method is being evaluated:: + + # cd /sys/module/acpi/parameters + # echo "0xXXXXXXXX" > trace_debug_layer + # echo "0xYYYYYYYY" > trace_debug_level + # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name + # echo "method" > /sys/module/acpi/parameters/trace_state + +c. Filter out the debug layer/level matched logs when the specified + control method is being evaluated for the first time:: + + # cd /sys/module/acpi/parameters + # echo "0xXXXXXXXX" > trace_debug_layer + # echo "0xYYYYYYYY" > trace_debug_level + # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name + # echo "method-once" > /sys/module/acpi/parameters/trace_state + +Where: + 0xXXXXXXXX/0xYYYYYYYY + Refer to Documentation/acpi/debug.txt for possible debug layer/level + masking values. + \PPPP.AAAA.TTTT.HHHH + Full path of a control method that can be found in the ACPI namespace. + It needn't be an entry of a control method evaluation. + +AML tracer +---------- + +There are special log entries added by the method tracing facility at +the "trace points" the AML interpreter starts/stops to execute a control +method, or an AML opcode. Note that the format of the log entries are +subject to change:: + + [ 0.186427] exdebug-0398 ex_trace_point : Method Begin [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution. + [ 0.186630] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905c88:If] execution. + [ 0.186820] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905cc0:LEqual] execution. + [ 0.187010] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905a20:-NamePath-] execution. + [ 0.187214] exdebug-0398 ex_trace_point : Opcode End [0xf5905a20:-NamePath-] execution. + [ 0.187407] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905f60:One] execution. + [ 0.187594] exdebug-0398 ex_trace_point : Opcode End [0xf5905f60:One] execution. + [ 0.187789] exdebug-0398 ex_trace_point : Opcode End [0xf5905cc0:LEqual] execution. + [ 0.187980] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905cc0:Return] execution. + [ 0.188146] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905f60:One] execution. + [ 0.188334] exdebug-0398 ex_trace_point : Opcode End [0xf5905f60:One] execution. + [ 0.188524] exdebug-0398 ex_trace_point : Opcode End [0xf5905cc0:Return] execution. + [ 0.188712] exdebug-0398 ex_trace_point : Opcode End [0xf5905c88:If] execution. + [ 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 +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. + +The following command examples illustrate the usage of the "AML tracer" +functionality: + +a. Filter out the method start/stop "AML tracer" logs when control + methods are being evaluated:: + + # cd /sys/module/acpi/parameters + # echo "0x80" > trace_debug_layer + # echo "0x10" > trace_debug_level + # echo "enable" > trace_state + +b. Filter out the method start/stop "AML tracer" when the specified + control method is being evaluated:: + + # cd /sys/module/acpi/parameters + # echo "0x80" > trace_debug_layer + # echo "0x10" > trace_debug_level + # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name + # echo "method" > trace_state + +c. Filter out the method start/stop "AML tracer" logs when the specified + control method is being evaluated for the first time:: + + # cd /sys/module/acpi/parameters + # echo "0x80" > trace_debug_layer + # echo "0x10" > trace_debug_level + # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name + # echo "method-once" > trace_state + +d. Filter out the method/opcode start/stop "AML tracer" when the + specified control method is being evaluated:: + + # cd /sys/module/acpi/parameters + # echo "0x80" > trace_debug_layer + # echo "0x10" > trace_debug_level + # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name + # echo "opcode" > trace_state + +e. Filter out the method/opcode start/stop "AML tracer" when the + specified control method is being evaluated for the first time:: + + # cd /sys/module/acpi/parameters + # echo "0x80" > trace_debug_layer + # echo "0x10" > trace_debug_level + # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name + # echo "opcode-opcode" > trace_state + +Note that all above method tracing facility related module parameters can +be used as the boot parameters, for example:: + + acpi.trace_debug_layer=0x80 acpi.trace_debug_level=0x10 \ + acpi.trace_method_name=\_SB.LID0._LID acpi.trace_state=opcode-once + + +Interface descriptions +====================== + +All method tracing functions can be configured via ACPI module +parameters that are accessible at /sys/module/acpi/parameters/: + +trace_method_name + The full path of the AML method that the user wants to trace. + + Note that the full path shouldn't contain the trailing "_"s in its + name segments but may contain "\" to form an absolute path. + +trace_debug_layer + The temporary debug_layer used when the tracing feature is enabled. + + Using ACPI_EXECUTER (0x80) by default, which is the debug_layer + used to match all "AML tracer" logs. + +trace_debug_level + The temporary debug_level used when the tracing feature is enabled. + + Using ACPI_LV_TRACE_POINT (0x10) by default, which is the + debug_level used to match all "AML tracer" logs. + +trace_state + The status of the tracing feature. + + Users can enable/disable this debug tracing feature by executing + the following command:: + + # echo string > /sys/module/acpi/parameters/trace_state + +Where "string" should be one of the following: + +"disable" + Disable the method tracing feature. + +"enable" + Enable the method tracing feature. + + ACPICA debugging messages matching "trace_debug_layer/trace_debug_level" + during any method execution will be logged. + +"method" + Enable the method tracing feature. + + ACPICA debugging messages matching "trace_debug_layer/trace_debug_level" + during method execution of "trace_method_name" will be logged. + +"method-once" + Enable the method tracing feature. + + ACPICA debugging messages matching "trace_debug_layer/trace_debug_level" + during method execution of "trace_method_name" will be logged only once. + +"opcode" + Enable the method tracing feature. + + ACPICA debugging messages matching "trace_debug_layer/trace_debug_level" + during method/opcode execution of "trace_method_name" will be logged. + +"opcode-once" + Enable the method tracing feature. + + ACPICA debugging messages matching "trace_debug_layer/trace_debug_level" + during method/opcode execution of "trace_method_name" will be logged only + once. + +Note that, the difference between the "enable" and other feature +enabling options are: + +1. When "enable" is specified, since + "trace_debug_layer/trace_debug_level" shall apply to all control + method evaluations, after configuring "trace_state" to "enable", + "trace_method_name" will be reset to NULL. +2. When "method/opcode" is specified, if + "trace_method_name" is NULL when "trace_state" is configured to + these options, the "trace_debug_layer/trace_debug_level" will + apply to all control method evaluations. -- cgit v1.2.3-59-g8ed1b From 472e89b4e1a87cd7f9b5ae99759a635711cf00fb Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 25 Apr 2019 01:53:00 +0800 Subject: Documentation: ACPI: move aml-debugger.txt to firmware-guide/acpi and convert to reST This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/aml-debugger.txt | 66 ------------------- Documentation/firmware-guide/acpi/aml-debugger.rst | 75 ++++++++++++++++++++++ Documentation/firmware-guide/acpi/index.rst | 1 + 3 files changed, 76 insertions(+), 66 deletions(-) delete mode 100644 Documentation/acpi/aml-debugger.txt create mode 100644 Documentation/firmware-guide/acpi/aml-debugger.rst (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/acpi/aml-debugger.txt b/Documentation/acpi/aml-debugger.txt deleted file mode 100644 index 75ebeb64ab29..000000000000 --- a/Documentation/acpi/aml-debugger.txt +++ /dev/null @@ -1,66 +0,0 @@ -The AML Debugger - -Copyright (C) 2016, Intel Corporation -Author: Lv Zheng - - -This document describes the usage of the AML debugger embedded in the Linux -kernel. - -1. Build the debugger - - The following kernel configuration items are required to enable the AML - debugger interface from the Linux kernel: - - CONFIG_ACPI_DEBUGGER=y - CONFIG_ACPI_DEBUGGER_USER=m - - The userspace utilities can be built from the kernel source tree using - the following commands: - - $ cd tools - $ make acpi - - The resultant userspace tool binary is then located at: - - tools/power/acpi/acpidbg - - It can be installed to system directories by running "make install" (as a - sufficiently privileged user). - -2. Start the userspace debugger interface - - After booting the kernel with the debugger built-in, the debugger can be - started by using the following commands: - - # mount -t debugfs none /sys/kernel/debug - # modprobe acpi_dbg - # tools/power/acpi/acpidbg - - That spawns the interactive AML debugger environment where you can execute - debugger commands. - - The commands are documented in the "ACPICA Overview and Programmer Reference" - that can be downloaded from - - https://acpica.org/documentation - - The detailed debugger commands reference is located in Chapter 12 "ACPICA - Debugger Reference". The "help" command can be used for a quick reference. - -3. Stop the userspace debugger interface - - The interactive debugger interface can be closed by pressing Ctrl+C or using - the "quit" or "exit" commands. When finished, unload the module with: - - # rmmod acpi_dbg - - The module unloading may fail if there is an acpidbg instance running. - -4. Run the debugger in a script - - It may be useful to run the AML debugger in a test script. "acpidbg" supports - this in a special "batch" mode. For example, the following command outputs - the entire ACPI namespace: - - # acpidbg -b "namespace" diff --git a/Documentation/firmware-guide/acpi/aml-debugger.rst b/Documentation/firmware-guide/acpi/aml-debugger.rst new file mode 100644 index 000000000000..a889d43bc6c5 --- /dev/null +++ b/Documentation/firmware-guide/acpi/aml-debugger.rst @@ -0,0 +1,75 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +================ +The AML Debugger +================ + +:Copyright: |copy| 2016, Intel Corporation +:Author: Lv Zheng + + +This document describes the usage of the AML debugger embedded in the Linux +kernel. + +1. Build the debugger +===================== + +The following kernel configuration items are required to enable the AML +debugger interface from the Linux kernel:: + + CONFIG_ACPI_DEBUGGER=y + CONFIG_ACPI_DEBUGGER_USER=m + +The userspace utilities can be built from the kernel source tree using +the following commands:: + + $ cd tools + $ make acpi + +The resultant userspace tool binary is then located at:: + + tools/power/acpi/acpidbg + +It can be installed to system directories by running "make install" (as a +sufficiently privileged user). + +2. Start the userspace debugger interface +========================================= + +After booting the kernel with the debugger built-in, the debugger can be +started by using the following commands:: + + # mount -t debugfs none /sys/kernel/debug + # modprobe acpi_dbg + # tools/power/acpi/acpidbg + +That spawns the interactive AML debugger environment where you can execute +debugger commands. + +The commands are documented in the "ACPICA Overview and Programmer Reference" +that can be downloaded from + +https://acpica.org/documentation + +The detailed debugger commands reference is located in Chapter 12 "ACPICA +Debugger Reference". The "help" command can be used for a quick reference. + +3. Stop the userspace debugger interface +======================================== + +The interactive debugger interface can be closed by pressing Ctrl+C or using +the "quit" or "exit" commands. When finished, unload the module with:: + + # rmmod acpi_dbg + +The module unloading may fail if there is an acpidbg instance running. + +4. Run the debugger in a script +=============================== + +It may be useful to run the AML debugger in a test script. "acpidbg" supports +this in a special "batch" mode. For example, the following command outputs +the entire ACPI namespace:: + + # acpidbg -b "namespace" diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index 287a7cbd82ac..e9f253d54897 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -16,6 +16,7 @@ ACPI Support method-tracing DSD-properties-rules debug + aml-debugger gpio-properties i2c-muxes acpi-lid -- cgit v1.2.3-59-g8ed1b From deb95169ef4279362f4c6167c4c59c8d68711d97 Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 25 Apr 2019 01:53:01 +0800 Subject: Documentation: ACPI: move apei/output_format.txt to firmware-guide/acpi and convert to reST This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/apei/output_format.txt | 147 -------------------- .../firmware-guide/acpi/apei/output_format.rst | 150 +++++++++++++++++++++ Documentation/firmware-guide/acpi/index.rst | 1 + 3 files changed, 151 insertions(+), 147 deletions(-) delete mode 100644 Documentation/acpi/apei/output_format.txt create mode 100644 Documentation/firmware-guide/acpi/apei/output_format.rst (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/acpi/apei/output_format.txt b/Documentation/acpi/apei/output_format.txt deleted file mode 100644 index 0c49c197c47a..000000000000 --- a/Documentation/acpi/apei/output_format.txt +++ /dev/null @@ -1,147 +0,0 @@ - APEI output format - ~~~~~~~~~~~~~~~~~~ - -APEI uses printk as hardware error reporting interface, the output -format is as follow. - - := -APEI generic hardware error status -severity: , -section: , severity: , -flags: -
-fru_id: -fru_text: -section_type:
-
- -* := recoverable | fatal | corrected | info - -
# := -[primary][, containment warning][, reset][, threshold exceeded]\ -[, resource not accessible][, latent error] - -
:= generic processor error | memory error | \ -PCIe error | unknown, - -
:= - | | \ - | - - := -[processor_type: , ] -[processor_isa: , ] -[error_type: -] -[operation: , ] -[flags: -] -[level: ] -[version_info: ] -[processor_id: ] -[target_address: ] -[requestor_id: ] -[responder_id: ] -[IP: ] - -* := IA32/X64 | IA64 - -* := IA32 | IA64 | X64 - -# := -[cache error][, TLB error][, bus error][, micro-architectural error] - -* := unknown or generic | data read | data write | \ -instruction execution - -# := -[restartable][, precise IP][, overflow][, corrected] - - := -[error_status: ] -[physical_address: ] -[physical_address_mask: ] -[node: ] -[card: ] -[module: ] -[bank: ] -[device: ] -[row: ] -[column: ] -[bit_position: ] -[requestor_id: ] -[responder_id: ] -[target_id: ] -[error_type: , ] - -* := -unknown | no error | single-bit ECC | multi-bit ECC | \ -single-symbol chipkill ECC | multi-symbol chipkill ECC | master abort | \ -target abort | parity error | watchdog timeout | invalid address | \ -mirror Broken | memory sparing | scrub corrected error | \ -scrub uncorrected error - - := -[port_type: , ] -[version: .] -[command: , status: ] -[device_id: ::. -slot: -secondary_bus: -vendor_id: , device_id: -class_code: ] -[serial number: , ] -[bridge: secondary_status: , control: ] -[aer_status: , aer_mask: - -[aer_uncor_severity: ] -aer_layer=, aer_agent= -aer_tlp_header: ] - -* := PCIe end point | legacy PCI end point | \ -unknown | unknown | root port | upstream switch port | \ -downstream switch port | PCIe to PCI/PCI-X bridge | \ -PCI/PCI-X to PCIe bridge | root complex integrated endpoint device | \ -root complex event collector - -if section severity is fatal or recoverable -# := -unknown | unknown | unknown | unknown | Data Link Protocol | \ -unknown | unknown | unknown | unknown | unknown | unknown | unknown | \ -Poisoned TLP | Flow Control Protocol | Completion Timeout | \ -Completer Abort | Unexpected Completion | Receiver Overflow | \ -Malformed TLP | ECRC | Unsupported Request -else -# := -Receiver Error | unknown | unknown | unknown | unknown | unknown | \ -Bad TLP | Bad DLLP | RELAY_NUM Rollover | unknown | unknown | unknown | \ -Replay Timer Timeout | Advisory Non-Fatal -fi - - := -Physical Layer | Data Link Layer | Transaction Layer - - := -Receiver ID | Requester ID | Completer ID | Transmitter ID - -Where, [] designate corresponding content is optional - -All description with * has the following format: - -field: , - -Where value of should be the position of "string" in description. Otherwise, will be "unknown". - -All description with # has the following format: - -field: - - -Where each string in corresponding to one set bit of -. The bit position is the position of "string" in description. - -For more detailed explanation of every field, please refer to UEFI -specification version 2.3 or later, section Appendix N: Common -Platform Error Record. diff --git a/Documentation/firmware-guide/acpi/apei/output_format.rst b/Documentation/firmware-guide/acpi/apei/output_format.rst new file mode 100644 index 000000000000..c2e7ebddb529 --- /dev/null +++ b/Documentation/firmware-guide/acpi/apei/output_format.rst @@ -0,0 +1,150 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================== +APEI output format +================== + +APEI uses printk as hardware error reporting interface, the output +format is as follow:: + + := + APEI generic hardware error status + severity: , + section: , severity: , + flags: +
+ fru_id: + fru_text: + section_type:
+
+ + * := recoverable | fatal | corrected | info + +
# := + [primary][, containment warning][, reset][, threshold exceeded]\ + [, resource not accessible][, latent error] + +
:= generic processor error | memory error | \ + PCIe error | unknown, + +
:= + | | \ + | + + := + [processor_type: , ] + [processor_isa: , ] + [error_type: + ] + [operation: , ] + [flags: + ] + [level: ] + [version_info: ] + [processor_id: ] + [target_address: ] + [requestor_id: ] + [responder_id: ] + [IP: ] + + * := IA32/X64 | IA64 + + * := IA32 | IA64 | X64 + + # := + [cache error][, TLB error][, bus error][, micro-architectural error] + + * := unknown or generic | data read | data write | \ + instruction execution + + # := + [restartable][, precise IP][, overflow][, corrected] + + := + [error_status: ] + [physical_address: ] + [physical_address_mask: ] + [node: ] + [card: ] + [module: ] + [bank: ] + [device: ] + [row: ] + [column: ] + [bit_position: ] + [requestor_id: ] + [responder_id: ] + [target_id: ] + [error_type: , ] + + * := + unknown | no error | single-bit ECC | multi-bit ECC | \ + single-symbol chipkill ECC | multi-symbol chipkill ECC | master abort | \ + target abort | parity error | watchdog timeout | invalid address | \ + mirror Broken | memory sparing | scrub corrected error | \ + scrub uncorrected error + + := + [port_type: , ] + [version: .] + [command: , status: ] + [device_id: ::. + slot: + secondary_bus: + vendor_id: , device_id: + class_code: ] + [serial number: , ] + [bridge: secondary_status: , control: ] + [aer_status: , aer_mask: + + [aer_uncor_severity: ] + aer_layer=, aer_agent= + aer_tlp_header: ] + + * := PCIe end point | legacy PCI end point | \ + unknown | unknown | root port | upstream switch port | \ + downstream switch port | PCIe to PCI/PCI-X bridge | \ + PCI/PCI-X to PCIe bridge | root complex integrated endpoint device | \ + root complex event collector + + if section severity is fatal or recoverable + # := + unknown | unknown | unknown | unknown | Data Link Protocol | \ + unknown | unknown | unknown | unknown | unknown | unknown | unknown | \ + Poisoned TLP | Flow Control Protocol | Completion Timeout | \ + Completer Abort | Unexpected Completion | Receiver Overflow | \ + Malformed TLP | ECRC | Unsupported Request + else + # := + Receiver Error | unknown | unknown | unknown | unknown | unknown | \ + Bad TLP | Bad DLLP | RELAY_NUM Rollover | unknown | unknown | unknown | \ + Replay Timer Timeout | Advisory Non-Fatal + fi + + := + Physical Layer | Data Link Layer | Transaction Layer + + := + Receiver ID | Requester ID | Completer ID | Transmitter ID + +Where, [] designate corresponding content is optional + +All description with * has the following format:: + + field: , + +Where value of should be the position of "string" in description. Otherwise, will be "unknown". + +All description with # has the following format:: + + field: + + +Where each string in corresponding to one set bit of +. The bit position is the position of "string" in description. + +For more detailed explanation of every field, please refer to UEFI +specification version 2.3 or later, section Appendix N: Common +Platform Error Record. diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index e9f253d54897..869badba6d7a 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -17,6 +17,7 @@ ACPI Support DSD-properties-rules debug aml-debugger + apei/output_format gpio-properties i2c-muxes acpi-lid -- cgit v1.2.3-59-g8ed1b From 440ebec745dcbc44866f6b19e5145a12d4494a5f Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 25 Apr 2019 01:53:02 +0800 Subject: Documentation: ACPI: move apei/einj.txt to firmware-guide/acpi and convert to reST This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/apei/einj.txt | 177 ----------------------- Documentation/firmware-guide/acpi/apei/einj.rst | 185 ++++++++++++++++++++++++ Documentation/firmware-guide/acpi/index.rst | 1 + 3 files changed, 186 insertions(+), 177 deletions(-) delete mode 100644 Documentation/acpi/apei/einj.txt create mode 100644 Documentation/firmware-guide/acpi/apei/einj.rst (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/acpi/apei/einj.txt b/Documentation/acpi/apei/einj.txt deleted file mode 100644 index e550c8b98139..000000000000 --- a/Documentation/acpi/apei/einj.txt +++ /dev/null @@ -1,177 +0,0 @@ - APEI Error INJection - ~~~~~~~~~~~~~~~~~~~~ - -EINJ provides a hardware error injection mechanism. It is very useful -for debugging and testing APEI and RAS features in general. - -You need to check whether your BIOS supports EINJ first. For that, look -for early boot messages similar to this one: - -ACPI: EINJ 0x000000007370A000 000150 (v01 INTEL 00000001 INTL 00000001) - -which shows that the BIOS is exposing an EINJ table - it is the -mechanism through which the injection is done. - -Alternatively, look in /sys/firmware/acpi/tables for an "EINJ" file, -which is a different representation of the same thing. - -It doesn't necessarily mean that EINJ is not supported if those above -don't exist: before you give up, go into BIOS setup to see if the BIOS -has an option to enable error injection. Look for something called WHEA -or similar. Often, you need to enable an ACPI5 support option prior, in -order to see the APEI,EINJ,... functionality supported and exposed by -the BIOS menu. - -To use EINJ, make sure the following are options enabled in your kernel -configuration: - -CONFIG_DEBUG_FS -CONFIG_ACPI_APEI -CONFIG_ACPI_APEI_EINJ - -The EINJ user interface is in /apei/einj. - -The following files belong to it: - -- available_error_type - - This file shows which error types are supported: - - Error Type Value Error Description - ================ ================= - 0x00000001 Processor Correctable - 0x00000002 Processor Uncorrectable non-fatal - 0x00000004 Processor Uncorrectable fatal - 0x00000008 Memory Correctable - 0x00000010 Memory Uncorrectable non-fatal - 0x00000020 Memory Uncorrectable fatal - 0x00000040 PCI Express Correctable - 0x00000080 PCI Express Uncorrectable fatal - 0x00000100 PCI Express Uncorrectable non-fatal - 0x00000200 Platform Correctable - 0x00000400 Platform Uncorrectable non-fatal - 0x00000800 Platform Uncorrectable fatal - - The format of the file contents are as above, except present are only - the available error types. - -- error_type - - Set the value of the error type being injected. Possible error types - are defined in the file available_error_type above. - -- error_inject - - Write any integer to this file to trigger the error injection. Make - sure you have specified all necessary error parameters, i.e. this - write should be the last step when injecting errors. - -- flags - - Present for kernel versions 3.13 and above. Used to specify which - of param{1..4} are valid and should be used by the firmware during - injection. Value is a bitmask as specified in ACPI5.0 spec for the - SET_ERROR_TYPE_WITH_ADDRESS data structure: - - Bit 0 - Processor APIC field valid (see param3 below). - Bit 1 - Memory address and mask valid (param1 and param2). - Bit 2 - PCIe (seg,bus,dev,fn) valid (see param4 below). - - If set to zero, legacy behavior is mimicked where the type of - injection specifies just one bit set, and param1 is multiplexed. - -- param1 - - This file is used to set the first error parameter value. Its effect - depends on the error type specified in error_type. For example, if - error type is memory related type, the param1 should be a valid - physical memory address. [Unless "flag" is set - see above] - -- param2 - - Same use as param1 above. For example, if error type is of memory - related type, then param2 should be a physical memory address mask. - Linux requires page or narrower granularity, say, 0xfffffffffffff000. - -- param3 - - Used when the 0x1 bit is set in "flags" to specify the APIC id - -- param4 - Used when the 0x4 bit is set in "flags" to specify target PCIe device - -- notrigger - - The error injection mechanism is a two-step process. First inject the - error, then perform some actions to trigger it. Setting "notrigger" - to 1 skips the trigger phase, which *may* allow the user to cause the - error in some other context by a simple access to the CPU, memory - location, or device that is the target of the error injection. Whether - this actually works depends on what operations the BIOS actually - includes in the trigger phase. - -BIOS versions based on the ACPI 4.0 specification have limited options -in controlling where the errors are injected. Your BIOS may support an -extension (enabled with the param_extension=1 module parameter, or boot -command line einj.param_extension=1). This allows the address and mask -for memory injections to be specified by the param1 and param2 files in -apei/einj. - -BIOS versions based on the ACPI 5.0 specification have more control over -the target of the injection. For processor-related errors (type 0x1, 0x2 -and 0x4), you can set flags to 0x3 (param3 for bit 0, and param1 and -param2 for bit 1) so that you have more information added to the error -signature being injected. The actual data passed is this: - - memory_address = param1; - memory_address_range = param2; - apicid = param3; - pcie_sbdf = param4; - -For memory errors (type 0x8, 0x10 and 0x20) the address is set using -param1 with a mask in param2 (0x0 is equivalent to all ones). For PCI -express errors (type 0x40, 0x80 and 0x100) the segment, bus, device and -function are specified using param1: - - 31 24 23 16 15 11 10 8 7 0 - +-------------------------------------------------+ - | segment | bus | device | function | reserved | - +-------------------------------------------------+ - -Anyway, you get the idea, if there's doubt just take a look at the code -in drivers/acpi/apei/einj.c. - -An ACPI 5.0 BIOS may also allow vendor-specific errors to be injected. -In this case a file named vendor will contain identifying information -from the BIOS that hopefully will allow an application wishing to use -the vendor-specific extension to tell that they are running on a BIOS -that supports it. All vendor extensions have the 0x80000000 bit set in -error_type. A file vendor_flags controls the interpretation of param1 -and param2 (1 = PROCESSOR, 2 = MEMORY, 4 = PCI). See your BIOS vendor -documentation for details (and expect changes to this API if vendors -creativity in using this feature expands beyond our expectations). - - -An error injection example: - -# cd /sys/kernel/debug/apei/einj -# cat available_error_type # See which errors can be injected -0x00000002 Processor Uncorrectable non-fatal -0x00000008 Memory Correctable -0x00000010 Memory Uncorrectable non-fatal -# echo 0x12345000 > param1 # Set memory address for injection -# echo $((-1 << 12)) > param2 # Mask 0xfffffffffffff000 - anywhere in this page -# echo 0x8 > error_type # Choose correctable memory error -# echo 1 > error_inject # Inject now - -You should see something like this in dmesg: - -[22715.830801] EDAC sbridge MC3: HANDLING MCE MEMORY ERROR -[22715.834759] EDAC sbridge MC3: CPU 0: Machine Check Event: 0 Bank 7: 8c00004000010090 -[22715.834759] EDAC sbridge MC3: TSC 0 -[22715.834759] EDAC sbridge MC3: ADDR 12345000 EDAC sbridge MC3: MISC 144780c86 -[22715.834759] EDAC sbridge MC3: PROCESSOR 0:306e7 TIME 1422553404 SOCKET 0 APIC 0 -[22716.616173] EDAC MC3: 1 CE memory read error on CPU_SrcID#0_Channel#0_DIMM#0 (channel:0 slot:0 page:0x12345 offset:0x0 grain:32 syndrome:0x0 - area:DRAM err_code:0001:0090 socket:0 channel_mask:1 rank:0) - -For more information about EINJ, please refer to ACPI specification -version 4.0, section 17.5 and ACPI 5.0, section 18.6. diff --git a/Documentation/firmware-guide/acpi/apei/einj.rst b/Documentation/firmware-guide/acpi/apei/einj.rst new file mode 100644 index 000000000000..e588bccf5158 --- /dev/null +++ b/Documentation/firmware-guide/acpi/apei/einj.rst @@ -0,0 +1,185 @@ +.. SPDX-License-Identifier: GPL-2.0 + +==================== +APEI Error INJection +==================== + +EINJ provides a hardware error injection mechanism. It is very useful +for debugging and testing APEI and RAS features in general. + +You need to check whether your BIOS supports EINJ first. For that, look +for early boot messages similar to this one:: + + ACPI: EINJ 0x000000007370A000 000150 (v01 INTEL 00000001 INTL 00000001) + +which shows that the BIOS is exposing an EINJ table - it is the +mechanism through which the injection is done. + +Alternatively, look in /sys/firmware/acpi/tables for an "EINJ" file, +which is a different representation of the same thing. + +It doesn't necessarily mean that EINJ is not supported if those above +don't exist: before you give up, go into BIOS setup to see if the BIOS +has an option to enable error injection. Look for something called WHEA +or similar. Often, you need to enable an ACPI5 support option prior, in +order to see the APEI,EINJ,... functionality supported and exposed by +the BIOS menu. + +To use EINJ, make sure the following are options enabled in your kernel +configuration:: + + CONFIG_DEBUG_FS + CONFIG_ACPI_APEI + CONFIG_ACPI_APEI_EINJ + +The EINJ user interface is in /apei/einj. + +The following files belong to it: + +- available_error_type + + This file shows which error types are supported: + + ================ =================================== + Error Type Value Error Description + ================ =================================== + 0x00000001 Processor Correctable + 0x00000002 Processor Uncorrectable non-fatal + 0x00000004 Processor Uncorrectable fatal + 0x00000008 Memory Correctable + 0x00000010 Memory Uncorrectable non-fatal + 0x00000020 Memory Uncorrectable fatal + 0x00000040 PCI Express Correctable + 0x00000080 PCI Express Uncorrectable fatal + 0x00000100 PCI Express Uncorrectable non-fatal + 0x00000200 Platform Correctable + 0x00000400 Platform Uncorrectable non-fatal + 0x00000800 Platform Uncorrectable fatal + ================ =================================== + + The format of the file contents are as above, except present are only + the available error types. + +- error_type + + Set the value of the error type being injected. Possible error types + are defined in the file available_error_type above. + +- error_inject + + Write any integer to this file to trigger the error injection. Make + sure you have specified all necessary error parameters, i.e. this + write should be the last step when injecting errors. + +- flags + + Present for kernel versions 3.13 and above. Used to specify which + of param{1..4} are valid and should be used by the firmware during + injection. Value is a bitmask as specified in ACPI5.0 spec for the + SET_ERROR_TYPE_WITH_ADDRESS data structure: + + Bit 0 + Processor APIC field valid (see param3 below). + Bit 1 + Memory address and mask valid (param1 and param2). + Bit 2 + PCIe (seg,bus,dev,fn) valid (see param4 below). + + If set to zero, legacy behavior is mimicked where the type of + injection specifies just one bit set, and param1 is multiplexed. + +- param1 + + This file is used to set the first error parameter value. Its effect + depends on the error type specified in error_type. For example, if + error type is memory related type, the param1 should be a valid + physical memory address. [Unless "flag" is set - see above] + +- param2 + + Same use as param1 above. For example, if error type is of memory + related type, then param2 should be a physical memory address mask. + Linux requires page or narrower granularity, say, 0xfffffffffffff000. + +- param3 + + Used when the 0x1 bit is set in "flags" to specify the APIC id + +- param4 + Used when the 0x4 bit is set in "flags" to specify target PCIe device + +- notrigger + + The error injection mechanism is a two-step process. First inject the + error, then perform some actions to trigger it. Setting "notrigger" + to 1 skips the trigger phase, which *may* allow the user to cause the + error in some other context by a simple access to the CPU, memory + location, or device that is the target of the error injection. Whether + this actually works depends on what operations the BIOS actually + includes in the trigger phase. + +BIOS versions based on the ACPI 4.0 specification have limited options +in controlling where the errors are injected. Your BIOS may support an +extension (enabled with the param_extension=1 module parameter, or boot +command line einj.param_extension=1). This allows the address and mask +for memory injections to be specified by the param1 and param2 files in +apei/einj. + +BIOS versions based on the ACPI 5.0 specification have more control over +the target of the injection. For processor-related errors (type 0x1, 0x2 +and 0x4), you can set flags to 0x3 (param3 for bit 0, and param1 and +param2 for bit 1) so that you have more information added to the error +signature being injected. The actual data passed is this:: + + memory_address = param1; + memory_address_range = param2; + apicid = param3; + pcie_sbdf = param4; + +For memory errors (type 0x8, 0x10 and 0x20) the address is set using +param1 with a mask in param2 (0x0 is equivalent to all ones). For PCI +express errors (type 0x40, 0x80 and 0x100) the segment, bus, device and +function are specified using param1:: + + 31 24 23 16 15 11 10 8 7 0 + +-------------------------------------------------+ + | segment | bus | device | function | reserved | + +-------------------------------------------------+ + +Anyway, you get the idea, if there's doubt just take a look at the code +in drivers/acpi/apei/einj.c. + +An ACPI 5.0 BIOS may also allow vendor-specific errors to be injected. +In this case a file named vendor will contain identifying information +from the BIOS that hopefully will allow an application wishing to use +the vendor-specific extension to tell that they are running on a BIOS +that supports it. All vendor extensions have the 0x80000000 bit set in +error_type. A file vendor_flags controls the interpretation of param1 +and param2 (1 = PROCESSOR, 2 = MEMORY, 4 = PCI). See your BIOS vendor +documentation for details (and expect changes to this API if vendors +creativity in using this feature expands beyond our expectations). + + +An error injection example:: + + # cd /sys/kernel/debug/apei/einj + # cat available_error_type # See which errors can be injected + 0x00000002 Processor Uncorrectable non-fatal + 0x00000008 Memory Correctable + 0x00000010 Memory Uncorrectable non-fatal + # echo 0x12345000 > param1 # Set memory address for injection + # echo $((-1 << 12)) > param2 # Mask 0xfffffffffffff000 - anywhere in this page + # echo 0x8 > error_type # Choose correctable memory error + # echo 1 > error_inject # Inject now + +You should see something like this in dmesg:: + + [22715.830801] EDAC sbridge MC3: HANDLING MCE MEMORY ERROR + [22715.834759] EDAC sbridge MC3: CPU 0: Machine Check Event: 0 Bank 7: 8c00004000010090 + [22715.834759] EDAC sbridge MC3: TSC 0 + [22715.834759] EDAC sbridge MC3: ADDR 12345000 EDAC sbridge MC3: MISC 144780c86 + [22715.834759] EDAC sbridge MC3: PROCESSOR 0:306e7 TIME 1422553404 SOCKET 0 APIC 0 + [22716.616173] EDAC MC3: 1 CE memory read error on CPU_SrcID#0_Channel#0_DIMM#0 (channel:0 slot:0 page:0x12345 offset:0x0 grain:32 syndrome:0x0 - area:DRAM err_code:0001:0090 socket:0 channel_mask:1 rank:0) + +For more information about EINJ, please refer to ACPI specification +version 4.0, section 17.5 and ACPI 5.0, section 18.6. diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index 869badba6d7a..fca854f017d8 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -18,6 +18,7 @@ ACPI Support debug aml-debugger apei/output_format + apei/einj gpio-properties i2c-muxes acpi-lid -- cgit v1.2.3-59-g8ed1b From 4887954cac779abe38d3ba6446dec341ccca04ea Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 25 Apr 2019 01:53:04 +0800 Subject: Documentation: ACPI: move lpit.txt to firmware-guide/acpi and convert to reST This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/lpit.txt | 25 ---------------------- Documentation/firmware-guide/acpi/index.rst | 1 + Documentation/firmware-guide/acpi/lpit.rst | 33 +++++++++++++++++++++++++++++ 3 files changed, 34 insertions(+), 25 deletions(-) delete mode 100644 Documentation/acpi/lpit.txt create mode 100644 Documentation/firmware-guide/acpi/lpit.rst (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/acpi/lpit.txt b/Documentation/acpi/lpit.txt deleted file mode 100644 index b426398d2e97..000000000000 --- a/Documentation/acpi/lpit.txt +++ /dev/null @@ -1,25 +0,0 @@ -To enumerate platform Low Power Idle states, Intel platforms are using -“Low Power Idle Table” (LPIT). More details about this table can be -downloaded from: -http://www.uefi.org/sites/default/files/resources/Intel_ACPI_Low_Power_S0_Idle.pdf - -Residencies for each low power state can be read via FFH -(Function fixed hardware) or a memory mapped interface. - -On platforms supporting S0ix sleep states, there can be two types of -residencies: -- CPU PKG C10 (Read via FFH interface) -- Platform Controller Hub (PCH) SLP_S0 (Read via memory mapped interface) - -The following attributes are added dynamically to the cpuidle -sysfs attribute group: - /sys/devices/system/cpu/cpuidle/low_power_idle_cpu_residency_us - /sys/devices/system/cpu/cpuidle/low_power_idle_system_residency_us - -The "low_power_idle_cpu_residency_us" attribute shows time spent -by the CPU package in PKG C10 - -The "low_power_idle_system_residency_us" attribute shows SLP_S0 -residency, or system time spent with the SLP_S0# signal asserted. -This is the lowest possible system power state, achieved only when CPU is in -PKG C10 and all functional blocks in PCH are in a low power state. diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index fca854f017d8..0e60f4b7129a 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -22,3 +22,4 @@ ACPI Support gpio-properties i2c-muxes acpi-lid + lpit diff --git a/Documentation/firmware-guide/acpi/lpit.rst b/Documentation/firmware-guide/acpi/lpit.rst new file mode 100644 index 000000000000..aca928fab027 --- /dev/null +++ b/Documentation/firmware-guide/acpi/lpit.rst @@ -0,0 +1,33 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================== +Low Power Idle Table (LPIT) +=========================== + +To enumerate platform Low Power Idle states, Intel platforms are using +“Low Power Idle Table” (LPIT). More details about this table can be +downloaded from: +http://www.uefi.org/sites/default/files/resources/Intel_ACPI_Low_Power_S0_Idle.pdf + +Residencies for each low power state can be read via FFH +(Function fixed hardware) or a memory mapped interface. + +On platforms supporting S0ix sleep states, there can be two types of +residencies: + + - CPU PKG C10 (Read via FFH interface) + - Platform Controller Hub (PCH) SLP_S0 (Read via memory mapped interface) + +The following attributes are added dynamically to the cpuidle +sysfs attribute group:: + + /sys/devices/system/cpu/cpuidle/low_power_idle_cpu_residency_us + /sys/devices/system/cpu/cpuidle/low_power_idle_system_residency_us + +The "low_power_idle_cpu_residency_us" attribute shows time spent +by the CPU package in PKG C10 + +The "low_power_idle_system_residency_us" attribute shows SLP_S0 +residency, or system time spent with the SLP_S0# signal asserted. +This is the lowest possible system power state, achieved only when CPU is in +PKG C10 and all functional blocks in PCH are in a low power state. -- cgit v1.2.3-59-g8ed1b From 7fb091f806c55da593b93bc858d81203a9597257 Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 25 Apr 2019 01:53:06 +0800 Subject: Documentation: ACPI: move video_extension.txt to firmware-guide/acpi and convert to reST This converts the plain text documentation to reStructuredText format and adds it to Sphinx TOC tree. No essential content change. Signed-off-by: Changbin Du Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Rafael J. Wysocki --- Documentation/acpi/video_extension.txt | 106 ------------------ Documentation/firmware-guide/acpi/index.rst | 1 + .../firmware-guide/acpi/video_extension.rst | 121 +++++++++++++++++++++ 3 files changed, 122 insertions(+), 106 deletions(-) delete mode 100644 Documentation/acpi/video_extension.txt create mode 100644 Documentation/firmware-guide/acpi/video_extension.rst (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/acpi/video_extension.txt b/Documentation/acpi/video_extension.txt deleted file mode 100644 index 79bf6a4921be..000000000000 --- a/Documentation/acpi/video_extension.txt +++ /dev/null @@ -1,106 +0,0 @@ -ACPI video extensions -~~~~~~~~~~~~~~~~~~~~~ - -This driver implement the ACPI Extensions For Display Adapters for -integrated graphics devices on motherboard, as specified in ACPI 2.0 -Specification, Appendix B, allowing to perform some basic control like -defining the video POST device, retrieving EDID information or to -setup a video output, etc. Note that this is an ref. implementation -only. It may or may not work for your integrated video device. - -The ACPI video driver does 3 things regarding backlight control: - -1 Export a sysfs interface for user space to control backlight level - -If the ACPI table has a video device, and acpi_backlight=vendor kernel -command line is not present, the driver will register a backlight device -and set the required backlight operation structure for it for the sysfs -interface control. For every registered class device, there will be a -directory named acpi_videoX under /sys/class/backlight. - -The backlight sysfs interface has a standard definition here: -Documentation/ABI/stable/sysfs-class-backlight. - -And what ACPI video driver does is: -actual_brightness: on read, control method _BQC will be evaluated to -get the brightness level the firmware thinks it is at; -bl_power: not implemented, will set the current brightness instead; -brightness: on write, control method _BCM will run to set the requested -brightness level; -max_brightness: Derived from the _BCL package(see below); -type: firmware - -Note that ACPI video backlight driver will always use index for -brightness, actual_brightness and max_brightness. So if we have -the following _BCL package: - -Method (_BCL, 0, NotSerialized) -{ - Return (Package (0x0C) - { - 0x64, - 0x32, - 0x0A, - 0x14, - 0x1E, - 0x28, - 0x32, - 0x3C, - 0x46, - 0x50, - 0x5A, - 0x64 - }) -} - -The first two levels are for when laptop are on AC or on battery and are -not used by Linux currently. The remaining 10 levels are supported levels -that we can choose from. The applicable index values are from 0 (that -corresponds to the 0x0A brightness value) to 9 (that corresponds to the -0x64 brightness value) inclusive. Each of those index values is regarded -as a "brightness level" indicator. Thus from the user space perspective -the range of available brightness levels is from 0 to 9 (max_brightness) -inclusive. - -2 Notify user space about hotkey event - -There are generally two cases for hotkey event reporting: -i) For some laptops, when user presses the hotkey, a scancode will be - generated and sent to user space through the input device created by - the keyboard driver as a key type input event, with proper remap, the - following key code will appear to user space: - - EV_KEY, KEY_BRIGHTNESSUP - EV_KEY, KEY_BRIGHTNESSDOWN - etc. - -For this case, ACPI video driver does not need to do anything(actually, -it doesn't even know this happened). - -ii) For some laptops, the press of the hotkey will not generate the - scancode, instead, firmware will notify the video device ACPI node - about the event. The event value is defined in the ACPI spec. ACPI - video driver will generate an key type input event according to the - notify value it received and send the event to user space through the - input device it created: - - event keycode - 0x86 KEY_BRIGHTNESSUP - 0x87 KEY_BRIGHTNESSDOWN - etc. - -so this would lead to the same effect as case i) now. - -Once user space tool receives this event, it can modify the backlight -level through the sysfs interface. - -3 Change backlight level in the kernel - -This works for machines covered by case ii) in Section 2. Once the driver -received a notification, it will set the backlight level accordingly. This does -not affect the sending of event to user space, they are always sent to user -space regardless of whether or not the video module controls the backlight level -directly. This behaviour can be controlled through the brightness_switch_enabled -module parameter as documented in admin-guide/kernel-parameters.rst. It is recommended to -disable this behaviour once a GUI environment starts up and wants to have full -control of the backlight level. diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index 0e60f4b7129a..ae609eec4679 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -23,3 +23,4 @@ ACPI Support i2c-muxes acpi-lid lpit + video_extension diff --git a/Documentation/firmware-guide/acpi/video_extension.rst b/Documentation/firmware-guide/acpi/video_extension.rst new file mode 100644 index 000000000000..099b8607e07b --- /dev/null +++ b/Documentation/firmware-guide/acpi/video_extension.rst @@ -0,0 +1,121 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +ACPI video extensions +===================== + +This driver implement the ACPI Extensions For Display Adapters for +integrated graphics devices on motherboard, as specified in ACPI 2.0 +Specification, Appendix B, allowing to perform some basic control like +defining the video POST device, retrieving EDID information or to +setup a video output, etc. Note that this is an ref. implementation +only. It may or may not work for your integrated video device. + +The ACPI video driver does 3 things regarding backlight control. + +Export a sysfs interface for user space to control backlight level +================================================================== + +If the ACPI table has a video device, and acpi_backlight=vendor kernel +command line is not present, the driver will register a backlight device +and set the required backlight operation structure for it for the sysfs +interface control. For every registered class device, there will be a +directory named acpi_videoX under /sys/class/backlight. + +The backlight sysfs interface has a standard definition here: +Documentation/ABI/stable/sysfs-class-backlight. + +And what ACPI video driver does is: + +actual_brightness: + on read, control method _BQC will be evaluated to + get the brightness level the firmware thinks it is at; +bl_power: + not implemented, will set the current brightness instead; +brightness: + on write, control method _BCM will run to set the requested brightness level; +max_brightness: + Derived from the _BCL package(see below); +type: + firmware + +Note that ACPI video backlight driver will always use index for +brightness, actual_brightness and max_brightness. So if we have +the following _BCL package:: + + Method (_BCL, 0, NotSerialized) + { + Return (Package (0x0C) + { + 0x64, + 0x32, + 0x0A, + 0x14, + 0x1E, + 0x28, + 0x32, + 0x3C, + 0x46, + 0x50, + 0x5A, + 0x64 + }) + } + +The first two levels are for when laptop are on AC or on battery and are +not used by Linux currently. The remaining 10 levels are supported levels +that we can choose from. The applicable index values are from 0 (that +corresponds to the 0x0A brightness value) to 9 (that corresponds to the +0x64 brightness value) inclusive. Each of those index values is regarded +as a "brightness level" indicator. Thus from the user space perspective +the range of available brightness levels is from 0 to 9 (max_brightness) +inclusive. + +Notify user space about hotkey event +==================================== + +There are generally two cases for hotkey event reporting: + +i) For some laptops, when user presses the hotkey, a scancode will be + generated and sent to user space through the input device created by + the keyboard driver as a key type input event, with proper remap, the + following key code will appear to user space:: + + EV_KEY, KEY_BRIGHTNESSUP + EV_KEY, KEY_BRIGHTNESSDOWN + etc. + +For this case, ACPI video driver does not need to do anything(actually, +it doesn't even know this happened). + +ii) For some laptops, the press of the hotkey will not generate the + scancode, instead, firmware will notify the video device ACPI node + about the event. The event value is defined in the ACPI spec. ACPI + video driver will generate an key type input event according to the + notify value it received and send the event to user space through the + input device it created: + + ===== ================== + event keycode + ===== ================== + 0x86 KEY_BRIGHTNESSUP + 0x87 KEY_BRIGHTNESSDOWN + etc. + ===== ================== + +so this would lead to the same effect as case i) now. + +Once user space tool receives this event, it can modify the backlight +level through the sysfs interface. + +Change backlight level in the kernel +==================================== + +This works for machines covered by case ii) in Section 2. Once the driver +received a notification, it will set the backlight level accordingly. This does +not affect the sending of event to user space, they are always sent to user +space regardless of whether or not the video module controls the backlight level +directly. This behaviour can be controlled through the brightness_switch_enabled +module parameter as documented in admin-guide/kernel-parameters.rst. It is +recommended to disable this behaviour once a GUI environment starts up and +wants to have full control of the backlight level. -- cgit v1.2.3-59-g8ed1b From 5695f51d055057b9db069f0a060fc7c397278c2e Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Fri, 10 May 2019 12:46:02 +0300 Subject: Documentation: ACPI: Use tabs for graph ASL indentation Use tabs to indent the graph documentation, not spaces. Fixes: f2dde1ed0f28 ("Documentation: ACPI: move dsd/graph.txt to firmware-guide/acpi and convert to reST") Signed-off-by: Sakari Ailus Signed-off-by: Rafael J. Wysocki --- Documentation/firmware-guide/acpi/dsd/graph.rst | 116 ++++++++++++------------ 1 file changed, 58 insertions(+), 58 deletions(-) (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/firmware-guide/acpi/dsd/graph.rst b/Documentation/firmware-guide/acpi/dsd/graph.rst index e0baed35b037..8a9019a38b66 100644 --- a/Documentation/firmware-guide/acpi/dsd/graph.rst +++ b/Documentation/firmware-guide/acpi/dsd/graph.rst @@ -82,68 +82,68 @@ A simple example of this is show below:: Scope (\_SB.PCI0.I2C2) { - Device (CAM0) - { - Name (_DSD, Package () { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () { - Package () { "compatible", Package () { "nokia,smia" } }, - }, - ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), - Package () { - Package () { "port@0", PRT0 }, - } - }) - Name (PRT0, Package() { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () { - Package () { "reg", 0 }, - }, - ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), - Package () { - Package () { "endpoint@0", EP00 }, - } - }) - Name (EP00, Package() { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () { - Package () { "reg", 0 }, - Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } }, - } - }) - } + Device (CAM0) + { + Name (_DSD, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "compatible", Package () { "nokia,smia" } }, + }, + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "port@0", PRT0 }, + } + }) + Name (PRT0, Package() { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reg", 0 }, + }, + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "endpoint@0", EP00 }, + } + }) + Name (EP00, Package() { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reg", 0 }, + Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } }, + } + }) + } } Scope (\_SB.PCI0) { - Device (ISP) - { - Name (_DSD, Package () { - ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), - Package () { - Package () { "port@4", PRT4 }, - } - }) - - Name (PRT4, Package() { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () { - Package () { "reg", 4 }, /* CSI-2 port number */ - }, - ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), - Package () { - Package () { "endpoint@0", EP40 }, - } - }) - - Name (EP40, Package() { - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), - Package () { - Package () { "reg", 0 }, - Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } }, - } - }) - } + Device (ISP) + { + Name (_DSD, Package () { + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "port@4", PRT4 }, + } + }) + + Name (PRT4, Package() { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reg", 4 }, /* CSI-2 port number */ + }, + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "endpoint@0", EP40 }, + } + }) + + Name (EP40, Package() { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reg", 0 }, + Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } }, + } + }) + } } Here, the port 0 of the "CAM0" device is connected to the port 4 of -- cgit v1.2.3-59-g8ed1b From a423bd845c6043c205eedc413f40f81c7550e85c Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Fri, 10 May 2019 12:46:03 +0300 Subject: Documentation: ACPI: Direct references are allowed to devices only In ACPI it is possible to make references to device objects only, not to other objects inside a device. In practice this means that hierarchical data extension targets must be in parentheses to make them strings, or an ACPICA warning will be produced. Reported-by: Andy Shevchenko Signed-off-by: Sakari Ailus Reviewed-by: Andy Shevchenko [ rjw: Changelog ] Signed-off-by: Rafael J. Wysocki --- .../firmware-guide/acpi/dsd/data-node-references.rst | 6 +++--- Documentation/firmware-guide/acpi/dsd/graph.rst | 12 ++++++------ 2 files changed, 9 insertions(+), 9 deletions(-) (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst index 1351984e767c..febccbc5689d 100644 --- a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst +++ b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst @@ -45,8 +45,8 @@ the ANOD object which is also the final target node of the reference. Name (_DSD, Package () { ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), Package () { - Package () { "node@0", NOD0 }, - Package () { "node@1", NOD1 }, + Package () { "node@0", "NOD0" }, + Package () { "node@1", "NOD1" }, } }) Name (NOD0, Package() { @@ -58,7 +58,7 @@ the ANOD object which is also the final target node of the reference. Name (NOD1, Package() { ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), Package () { - Package () { "anothernode", ANOD }, + Package () { "anothernode", "ANOD" }, } }) Name (ANOD, Package() { diff --git a/Documentation/firmware-guide/acpi/dsd/graph.rst b/Documentation/firmware-guide/acpi/dsd/graph.rst index 8a9019a38b66..1a6ce7afba5e 100644 --- a/Documentation/firmware-guide/acpi/dsd/graph.rst +++ b/Documentation/firmware-guide/acpi/dsd/graph.rst @@ -45,7 +45,7 @@ with "port" and must be followed by the "@" character and the number of the port as its key. The target object it refers to should be called "PRTX", where "X" is the number of the port. An example of such a package would be:: - Package() { "port@4", PRT4 } + Package() { "port@4", "PRT4" } Further on, endpoints are located under the port nodes. The hierarchical data extension key of the endpoint nodes must begin with @@ -54,7 +54,7 @@ endpoint. The object it refers to should be called "EPXY", where "X" is the number of the port and "Y" is the number of the endpoint. An example of such a package would be:: - Package() { "endpoint@0", EP40 } + Package() { "endpoint@0", "EP40" } Each port node contains a property extension key "port", the value of which is the number of the port. Each endpoint is similarly numbered with a property @@ -91,7 +91,7 @@ A simple example of this is show below:: }, ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), Package () { - Package () { "port@0", PRT0 }, + Package () { "port@0", "PRT0" }, } }) Name (PRT0, Package() { @@ -101,7 +101,7 @@ A simple example of this is show below:: }, ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), Package () { - Package () { "endpoint@0", EP00 }, + Package () { "endpoint@0", "EP00" }, } }) Name (EP00, Package() { @@ -121,7 +121,7 @@ A simple example of this is show below:: Name (_DSD, Package () { ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), Package () { - Package () { "port@4", PRT4 }, + Package () { "port@4", "PRT4" }, } }) @@ -132,7 +132,7 @@ A simple example of this is show below:: }, ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), Package () { - Package () { "endpoint@0", EP40 }, + Package () { "endpoint@0", "EP40" }, } }) -- cgit v1.2.3-59-g8ed1b From bbb30909e0fd9ec01c25b88f635085bf481a7ea9 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 22 May 2019 13:47:23 -0600 Subject: docs: fix multiple doc build warnings in enumeration.rst The conversion of acpi/enumeration.txt to RST included one markup error, leading to many warnings like: .../firmware-guide/acpi/enumeration.rst:430: WARNING: Unexpected indentation. Add the missing colon and create some peace. Fixes: c24bc66e8157 ("Documentation: ACPI: move enumeration.txt to firmware-guide/acpi and convert to reST") Cc: Changbin Du Signed-off-by: Jonathan Corbet --- Documentation/firmware-guide/acpi/enumeration.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/firmware-guide/acpi') diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst index 6b32b7be8c85..850be9696931 100644 --- a/Documentation/firmware-guide/acpi/enumeration.rst +++ b/Documentation/firmware-guide/acpi/enumeration.rst @@ -423,7 +423,7 @@ will be enumerated to depends on the device ID returned by _HID. For example, the following ACPI sample might be used to enumerate an lm75-type I2C temperature sensor and match it to the driver using the Device Tree -namespace link: +namespace link:: Device (TMP0) { -- cgit v1.2.3-59-g8ed1b