Merge tag 'acpi-5.2-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm

The AML Debugger

Copyright (C) 2016, Intel Corporation

Author: Lv Zheng <lv.zheng@intel.com>

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"

                     APEI output format

                     ~~~~~~~~~~~~~~~~~~

APEI uses printk as hardware error reporting interface, the output

format is as follow.

<error record> :=

APEI generic hardware error status

severity: <integer>, <severity string>

section: <integer>, severity: <integer>, <severity string>

flags: <integer>

<section flags strings>

fru_id: <uuid string>

fru_text: <string>

section_type: <section type string>

<section data>

<severity string>* := recoverable | fatal | corrected | info

<section flags strings># :=

[primary][, containment warning][, reset][, threshold exceeded]\

[, resource not accessible][, latent error]

<section type string> := generic processor error | memory error | \

PCIe error | unknown, <uuid string>

<section data> :=

<generic processor section data> | <memory section data> | \

<pcie section data> | <null>

<generic processor section data> :=

[processor_type: <integer>, <proc type string>]

[processor_isa: <integer>, <proc isa string>]

[error_type: <integer>

<proc error type strings>]

[operation: <integer>, <proc operation string>]

[flags: <integer>

<proc flags strings>]

[level: <integer>]

[version_info: <integer>]

[processor_id: <integer>]

[target_address: <integer>]

[requestor_id: <integer>]

[responder_id: <integer>]

[IP: <integer>]

<proc type string>* := IA32/X64 | IA64

<proc isa string>* := IA32 | IA64 | X64

<processor error type strings># :=

[cache error][, TLB error][, bus error][, micro-architectural error]

<proc operation string>* := unknown or generic | data read | data write | \

instruction execution

<proc flags strings># :=

[restartable][, precise IP][, overflow][, corrected]

<memory section data> :=

[error_status: <integer>]

[physical_address: <integer>]

[physical_address_mask: <integer>]

[node: <integer>]

[card: <integer>]

[module: <integer>]

[bank: <integer>]

[device: <integer>]

[row: <integer>]

[column: <integer>]

[bit_position: <integer>]

[requestor_id: <integer>]

[responder_id: <integer>]

[target_id: <integer>]

[error_type: <integer>, <mem error type string>]

<mem error type string>* :=

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

<pcie section data> :=

[port_type: <integer>, <pcie port type string>]

[version: <integer>.<integer>]

[command: <integer>, status: <integer>]

[device_id: <integer>:<integer>:<integer>.<integer>

slot: <integer>

secondary_bus: <integer>

vendor_id: <integer>, device_id: <integer>

class_code: <integer>]

[serial number: <integer>, <integer>]

[bridge: secondary_status: <integer>, control: <integer>]

[aer_status: <integer>, aer_mask: <integer>

<aer status string>

[aer_uncor_severity: <integer>]

aer_layer=<aer layer string>, aer_agent=<aer agent string>

aer_tlp_header: <integer> <integer> <integer> <integer>]

<pcie port type string>* := 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

<aer status string># :=

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

<aer status string># :=

Receiver Error | unknown | unknown | unknown | unknown | unknown | \

Bad TLP | Bad DLLP | RELAY_NUM Rollover | unknown | unknown | unknown | \

Replay Timer Timeout | Advisory Non-Fatal

fi

<aer layer string> :=

Physical Layer | Data Link Layer | Transaction Layer

<aer agent string> :=

Receiver ID | Requester ID | Completer ID | Transmitter ID

Where, [] designate corresponding content is optional

All <field string> description with * has the following format:

field: <integer>, <field string>

Where value of <integer> should be the position of "string" in <field

string> description. Otherwise, <field string> will be "unknown".

All <field strings> description with # has the following format:

field: <integer>

<field strings>

Where each string in <fields strings> corresponding to one set bit of

<integer>. The bit position is the position of "string" in <field

strings> 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.

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,,)

                }

            }

        }

    }

}

Linux ACPI Custom Control Method How To

=======================================

Written by Zhang Rui <rui.zhang@intel.com>

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).

ACPICA Trace Facility

Copyright (C) 2015, Intel Corporation

Author: Lv Zheng <lv.zheng@intel.com>

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.