Skip to content

L
linux
Commit 10b4768b authored by Rafael J. Wysocki's avatar Rafael J. Wysocki
Browse files
Options

Merge branch 'acpi-doc' 

* acpi-doc: (25 commits)
  Documentation: ACPI: move video_extension.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move ssdt-overlays.txt to admin-guide/acpi and convert to reST
  Documentation: ACPI: move lpit.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move cppc_sysfs.txt to admin-guide/acpi and convert to reST
  Documentation: ACPI: move apei/einj.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move apei/output_format.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move aml-debugger.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move method-tracing.txt to firmware-guide/acpi and convert to rsST
  Documentation: ACPI: move debug.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move dsd/data-node-references.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move dsd/graph.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move acpi-lid.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move i2c-muxes.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move dsdt-override.txt to admin-guide/acpi and convert to reST
  Documentation: ACPI: move initrd_table_override.txt to admin-guide/acpi and convert to reST
  Documentation: ACPI: move method-customizing.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move gpio-properties.txt to firmware-guide/acpi and convert to reST
  Documentation: ACPI: move DSD-properties-rules.txt to firmware-guide/acpi and covert to reST
  Documentation: ACPI: move scan_handlers.txt to driver-api/acpi and convert to reST
  Documentation: ACPI: move linuxized-acpica.txt to driver-api/acpi and convert to reST
  ...
parents 7e8e05fd 7fb091f8
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 1683 additions and 1077 deletions
Documentation/acpi/aml-debugger.txt deleted 100644 → 0
View file @ 7e8e05fd
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"
Documentation/acpi/apei/output_format.txt deleted 100644 → 0
View file @ 7e8e05fd
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.
Documentation/acpi/i2c-muxes.txt deleted 100644 → 0
View file @ 7e8e05fd
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,,)
}
}
}
}
}
Documentation/acpi/method-customizing.txt deleted 100644 → 0
View file @ 7e8e05fd
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).
Documentation/acpi/method-tracing.txt deleted 100644 → 0
View file @ 7e8e05fd
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.
Documentation/acpi/cppc_sysfs.txt → Documentation/admin-guide/acpi/cppc_sysfs.rst
View file @ 10b4768b
.. SPDX-License-Identifier: GPL-2.0
Collaborative Processor Performance Control (CPPC) ==================================================
Collaborative Processor Performance Control (CPPC)
==================================================
CPPC
====
CPPC defined in the ACPI spec describes a mechanism for the OS to manage the CPPC defined in the ACPI spec describes a mechanism for the OS to manage the
performance of a logical processor on a contigious and abstract performance performance of a logical processor on a contigious and abstract performance
...@@ -10,31 +16,28 @@ For more details on CPPC please refer to the ACPI specification at: ...@@ -10,31 +16,28 @@ For more details on CPPC please refer to the ACPI specification at:
http://uefi.org/specifications http://uefi.org/specifications
Some of the CPPC registers are exposed via sysfs under: Some of the CPPC registers are exposed via sysfs under::
/sys/devices/system/cpu/cpuX/acpi_cppc/
for each cpu X
-------------------------------------------------------------------------------- /sys/devices/system/cpu/cpuX/acpi_cppc/
$ ls -lR /sys/devices/system/cpu/cpu0/acpi_cppc/ for each cpu X::
/sys/devices/system/cpu/cpu0/acpi_cppc/:
total 0
-r--r--r-- 1 root root 65536 Mar 5 19:38 feedback_ctrs
-r--r--r-- 1 root root 65536 Mar 5 19:38 highest_perf
-r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_freq
-r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_nonlinear_perf
-r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_perf
-r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_freq
-r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_perf
-r--r--r-- 1 root root 65536 Mar 5 19:38 reference_perf
-r--r--r-- 1 root root 65536 Mar 5 19:38 wraparound_time
-------------------------------------------------------------------------------- $ ls -lR /sys/devices/system/cpu/cpu0/acpi_cppc/
/sys/devices/system/cpu/cpu0/acpi_cppc/:
total 0
-r--r--r-- 1 root root 65536 Mar 5 19:38 feedback_ctrs
-r--r--r-- 1 root root 65536 Mar 5 19:38 highest_perf
-r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_freq
-r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_nonlinear_perf
-r--r--r-- 1 root root 65536 Mar 5 19:38 lowest_perf
-r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_freq
-r--r--r-- 1 root root 65536 Mar 5 19:38 nominal_perf
-r--r--r-- 1 root root 65536 Mar 5 19:38 reference_perf
-r--r--r-- 1 root root 65536 Mar 5 19:38 wraparound_time
* highest_perf : Highest performance of this processor (abstract scale). * highest_perf : Highest performance of this processor (abstract scale).
* nominal_perf : Highest sustained performance of this processor (abstract scale). * nominal_perf : Highest sustained performance of this processor
(abstract scale).
* lowest_nonlinear_perf : Lowest performance of this processor with nonlinear * lowest_nonlinear_perf : Lowest performance of this processor with nonlinear
power savings (abstract scale). power savings (abstract scale).
* lowest_perf : Lowest performance of this processor (abstract scale). * lowest_perf : Lowest performance of this processor (abstract scale).
...@@ -48,22 +51,26 @@ total 0 ...@@ -48,22 +51,26 @@ total 0
* feedback_ctrs : Includes both Reference and delivered performance counter. * feedback_ctrs : Includes both Reference and delivered performance counter.
Reference counter ticks up proportional to processor's reference performance. Reference counter ticks up proportional to processor's reference performance.
Delivered counter ticks up proportional to processor's delivered performance. Delivered counter ticks up proportional to processor's delivered performance.
* wraparound_time: Minimum time for the feedback counters to wraparound (seconds). * wraparound_time: Minimum time for the feedback counters to wraparound
(seconds).
* reference_perf : Performance level at which reference performance counter * reference_perf : Performance level at which reference performance counter
accumulates (abstract scale). accumulates (abstract scale).
--------------------------------------------------------------------------------
Computing Average Delivered Performance Computing Average Delivered Performance
=======================================
Below describes the steps to compute the average performance delivered by
taking two different snapshots of feedback counters at time T1 and T2.
T1: Read feedback_ctrs as fbc_t1
Wait or run some workload
Below describes the steps to compute the average performance delivered by taking T2: Read feedback_ctrs as fbc_t2
two different snapshots of feedback counters at time T1 and T2.
T1: Read feedback_ctrs as fbc_t1 ::
Wait or run some workload
T2: Read feedback_ctrs as fbc_t2
delivered_counter_delta = fbc_t2[del] - fbc_t1[del] delivered_counter_delta = fbc_t2[del] - fbc_t1[del]
reference_counter_delta = fbc_t2[ref] - fbc_t1[ref] reference_counter_delta = fbc_t2[ref] - fbc_t1[ref]
delivered_perf = (refernce_perf x delivered_counter_delta) / reference_counter_delta delivered_perf = (refernce_perf x delivered_counter_delta) / reference_counter_delta
Documentation/acpi/dsdt-override.txt → Documentation/admin-guide/acpi/dsdt-override.rst
View file @ 10b4768b
.. SPDX-License-Identifier: GPL-2.0
===============
Overriding DSDT
===============
Linux supports a method of overriding the BIOS DSDT: Linux supports a method of overriding the BIOS DSDT:
CONFIG_ACPI_CUSTOM_DSDT builds the image into the kernel. CONFIG_ACPI_CUSTOM_DSDT - builds the image into the kernel.
When to use this method is described in detail on the When to use this method is described in detail on the
Linux/ACPI home page: Linux/ACPI home page:
......
Documentation/admin-guide/acpi/index.rst 0 → 100644
View file @ 10b4768b
============
ACPI Support
============
Here we document in detail how to interact with various mechanisms in
the Linux ACPI support.
.. toctree::
:maxdepth: 1
initrd_table_override
dsdt-override
ssdt-overlays
cppc_sysfs
Documentation/acpi/initrd_table_override.txt → Documentation/admin-guide/acpi/initrd_table_override.rst
View file @ 10b4768b
.. SPDX-License-Identifier: GPL-2.0
================================
Upgrading ACPI tables via initrd Upgrading ACPI tables via initrd
================================ ================================
1) Introduction (What is this about) What is this about
2) What is this for ==================
3) How does it work
4) References (Where to retrieve userspace tools)
1) What is this about
---------------------
If the ACPI_TABLE_UPGRADE compile option is true, it is possible to If the ACPI_TABLE_UPGRADE compile option is true, it is possible to
upgrade the ACPI execution environment that is defined by the ACPI tables upgrade the ACPI execution environment that is defined by the ACPI tables
...@@ -19,17 +17,20 @@ ACPI_TABLE_OVERRIDE_VIA_BUILTIN_INITRD should also be true for this ...@@ -19,17 +17,20 @@ ACPI_TABLE_OVERRIDE_VIA_BUILTIN_INITRD should also be true for this
feature to work. feature to work.
For a full list of ACPI tables that can be upgraded/installed, take a look For a full list of ACPI tables that can be upgraded/installed, take a look
at the char *table_sigs[MAX_ACPI_SIGNATURE]; definition in at the char `*table_sigs[MAX_ACPI_SIGNATURE];` definition in
drivers/acpi/tables.c. drivers/acpi/tables.c.
All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should
be overridable, except: be overridable, except:
- ACPI_SIG_RSDP (has a signature of 6 bytes)
- ACPI_SIG_FACS (does not have an ordinary ACPI table header) - ACPI_SIG_RSDP (has a signature of 6 bytes)
- ACPI_SIG_FACS (does not have an ordinary ACPI table header)
Both could get implemented as well. Both could get implemented as well.
2) What is this for What is this for
------------------- ================
Complain to your platform/BIOS vendor if you find a bug which is so severe Complain to your platform/BIOS vendor if you find a bug which is so severe
that a workaround is not accepted in the Linux kernel. And this facility that a workaround is not accepted in the Linux kernel. And this facility
...@@ -47,65 +48,68 @@ It can and should be enabled in any kernel because there is no functional ...@@ -47,65 +48,68 @@ It can and should be enabled in any kernel because there is no functional
change with not instrumented initrds. change with not instrumented initrds.
3) How does it work How does it work
------------------- ================
::
# Extract the machine's ACPI tables:
cd /tmp # Extract the machine's ACPI tables:
acpidump >acpidump cd /tmp
acpixtract -a acpidump acpidump >acpidump
# Disassemble, modify and recompile them: acpixtract -a acpidump
iasl -d *.dat # Disassemble, modify and recompile them:
# For example add this statement into a _PRT (PCI Routing Table) function iasl -d *.dat
# of the DSDT: # For example add this statement into a _PRT (PCI Routing Table) function
Store("HELLO WORLD", debug) # of the DSDT:
# And increase the OEM Revision. For example, before modification: Store("HELLO WORLD", debug)
DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000000) # And increase the OEM Revision. For example, before modification:
# After modification: DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000000)
DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000001) # After modification:
iasl -sa dsdt.dsl DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000001)
# Add the raw ACPI tables to an uncompressed cpio archive. iasl -sa dsdt.dsl
# They must be put into a /kernel/firmware/acpi directory inside the cpio # Add the raw ACPI tables to an uncompressed cpio archive.
# archive. Note that if the table put here matches a platform table # They must be put into a /kernel/firmware/acpi directory inside the cpio
# (similar Table Signature, and similar OEMID, and similar OEM Table ID) # archive. Note that if the table put here matches a platform table
# with a more recent OEM Revision, the platform table will be upgraded by # (similar Table Signature, and similar OEMID, and similar OEM Table ID)
# this table. If the table put here doesn't match a platform table # with a more recent OEM Revision, the platform table will be upgraded by
# (dissimilar Table Signature, or dissimilar OEMID, or dissimilar OEM Table # this table. If the table put here doesn't match a platform table
# ID), this table will be appended. # (dissimilar Table Signature, or dissimilar OEMID, or dissimilar OEM Table
mkdir -p kernel/firmware/acpi # ID), this table will be appended.
cp dsdt.aml kernel/firmware/acpi mkdir -p kernel/firmware/acpi
# A maximum of "NR_ACPI_INITRD_TABLES (64)" tables are currently allowed cp dsdt.aml kernel/firmware/acpi
# (see osl.c): # A maximum of "NR_ACPI_INITRD_TABLES (64)" tables are currently allowed
iasl -sa facp.dsl # (see osl.c):
iasl -sa ssdt1.dsl iasl -sa facp.dsl
cp facp.aml kernel/firmware/acpi iasl -sa ssdt1.dsl
cp ssdt1.aml kernel/firmware/acpi cp facp.aml kernel/firmware/acpi
# The uncompressed cpio archive must be the first. Other, typically cp ssdt1.aml kernel/firmware/acpi
# compressed cpio archives, must be concatenated on top of the uncompressed # The uncompressed cpio archive must be the first. Other, typically
# one. Following command creates the uncompressed cpio archive and # compressed cpio archives, must be concatenated on top of the uncompressed
# concatenates the original initrd on top: # one. Following command creates the uncompressed cpio archive and
find kernel | cpio -H newc --create > /boot/instrumented_initrd # concatenates the original initrd on top:
cat /boot/initrd >>/boot/instrumented_initrd find kernel | cpio -H newc --create > /boot/instrumented_initrd
# reboot with increased acpi debug level, e.g. boot params: cat /boot/initrd >>/boot/instrumented_initrd
acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF # reboot with increased acpi debug level, e.g. boot params:
# and check your syslog: acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF
[ 1.268089] ACPI: PCI Interrupt Routing Table [\_SB_.PCI0._PRT] # and check your syslog:
[ 1.272091] [ACPI Debug] String [0x0B] "HELLO WORLD" [ 1.268089] ACPI: PCI Interrupt Routing Table [\_SB_.PCI0._PRT]
[ 1.272091] [ACPI Debug] String [0x0B] "HELLO WORLD"
iasl is able to disassemble and recompile quite a lot different, iasl is able to disassemble and recompile quite a lot different,
also static ACPI tables. also static ACPI tables.
4) Where to retrieve userspace tools Where to retrieve userspace tools
------------------------------------ =================================
iasl and acpixtract are part of Intel's ACPICA project: iasl and acpixtract are part of Intel's ACPICA project:
http://acpica.org/ http://acpica.org/
and should be packaged by distributions (for example in the acpica package and should be packaged by distributions (for example in the acpica package
on SUSE). on SUSE).
acpidump can be found in Len Browns pmtools: acpidump can be found in Len Browns pmtools:
ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump
This tool is also part of the acpica package on SUSE. This tool is also part of the acpica package on SUSE.
Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels: Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels:
/sys/firmware/acpi/tables /sys/firmware/acpi/tables
Documentation/acpi/ssdt-overlays.txt → Documentation/admin-guide/acpi/ssdt-overlays.rst
View file @ 10b4768b
.. SPDX-License-Identifier: GPL-2.0
=============
SSDT Overlays
=============
In order to support ACPI open-ended hardware configurations (e.g. development In order to support ACPI open-ended hardware configurations (e.g. development
boards) we need a way to augment the ACPI configuration provided by the firmware boards) we need a way to augment the ACPI configuration provided by the firmware
...@@ -15,55 +20,56 @@ user defined SSDT tables that contain the board specific information. ...@@ -15,55 +20,56 @@ user defined SSDT tables that contain the board specific information.
For example, to enumerate a Bosch BMA222E accelerometer on the I2C bus of the For example, to enumerate a Bosch BMA222E accelerometer on the I2C bus of the
Minnowboard MAX development board exposed via the LSE connector [1], the Minnowboard MAX development board exposed via the LSE connector [1], the
following ASL code can be used: following ASL code can be used::
DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003)
{
External (\_SB.I2C6, DeviceObj)
Scope (\_SB.I2C6) DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003)
{ {
Device (STAC) External (\_SB.I2C6, DeviceObj)
{
Name (_ADR, Zero)
Name (_HID, "BMA222E")
Method (_CRS, 0, Serialized) Scope (\_SB.I2C6)
{
Device (STAC)
{ {
Name (RBUF, ResourceTemplate () Name (_ADR, Zero)
Name (_HID, "BMA222E")
Method (_CRS, 0, Serialized)
{ {
I2cSerialBus (0x0018, ControllerInitiated, 0x00061A80, Name (RBUF, ResourceTemplate ()
AddressingMode7Bit, "\\_SB.I2C6", 0x00, {
ResourceConsumer, ,) I2cSerialBus (0x0018, ControllerInitiated, 0x00061A80,
GpioInt (Edge, ActiveHigh, Exclusive, PullDown, 0x0000, AddressingMode7Bit, "\\_SB.I2C6", 0x00,
"\\_SB.GPO2", 0x00, ResourceConsumer, , ) ResourceConsumer, ,)
{ // Pin list GpioInt (Edge, ActiveHigh, Exclusive, PullDown, 0x0000,
0 "\\_SB.GPO2", 0x00, ResourceConsumer, , )
} { // Pin list
}) 0
Return (RBUF) }
})
Return (RBUF)
}
} }
} }
} }
}
which can then be compiled to AML binary format: which can then be compiled to AML binary format::
$ iasl minnowmax.asl $ iasl minnowmax.asl
Intel ACPI Component Architecture Intel ACPI Component Architecture
ASL Optimizing Compiler version 20140214-64 [Mar 29 2014] ASL Optimizing Compiler version 20140214-64 [Mar 29 2014]
Copyright (c) 2000 - 2014 Intel Corporation Copyright (c) 2000 - 2014 Intel Corporation
ASL Input: minnomax.asl - 30 lines, 614 bytes, 7 keywords ASL Input: minnomax.asl - 30 lines, 614 bytes, 7 keywords
AML Output: minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes AML Output: minnowmax.aml - 165 bytes, 6 named objects, 1 executable opcodes
[1] http://wiki.minnowboard.org/MinnowBoard_MAX#Low_Speed_Expansion_Connector_.28Top.29 [1] http://wiki.minnowboard.org/MinnowBoard_MAX#Low_Speed_Expansion_Connector_.28Top.29
The resulting AML code can then be loaded by the kernel using one of the methods The resulting AML code can then be loaded by the kernel using one of the methods
below. below.
== Loading ACPI SSDTs from initrd == Loading ACPI SSDTs from initrd
==============================
This option allows loading of user defined SSDTs from initrd and it is useful This option allows loading of user defined SSDTs from initrd and it is useful
when the system does not support EFI or when there is not enough EFI storage. when the system does not support EFI or when there is not enough EFI storage.
...@@ -74,23 +80,24 @@ aml code must be placed in the first, uncompressed, initrd under the ...@@ -74,23 +80,24 @@ aml code must be placed in the first, uncompressed, initrd under the
in loading multiple tables. Only SSDT and OEM tables are allowed. See in loading multiple tables. Only SSDT and OEM tables are allowed. See
initrd_table_override.txt for more details. initrd_table_override.txt for more details.
Here is an example: Here is an example::
# Add the raw ACPI tables to an uncompressed cpio archive. # Add the raw ACPI tables to an uncompressed cpio archive.
# They must be put into a /kernel/firmware/acpi directory inside the # They must be put into a /kernel/firmware/acpi directory inside the
# cpio archive. # cpio archive.
# The uncompressed cpio archive must be the first. # The uncompressed cpio archive must be the first.
# Other, typically compressed cpio archives, must be # Other, typically compressed cpio archives, must be
# concatenated on top of the uncompressed one. # concatenated on top of the uncompressed one.
mkdir -p kernel/firmware/acpi mkdir -p kernel/firmware/acpi
cp ssdt.aml kernel/firmware/acpi cp ssdt.aml kernel/firmware/acpi
# Create the uncompressed cpio archive and concatenate the original initrd # Create the uncompressed cpio archive and concatenate the original initrd
# on top: # on top:
find kernel | cpio -H newc --create > /boot/instrumented_initrd find kernel | cpio -H newc --create > /boot/instrumented_initrd
cat /boot/initrd >>/boot/instrumented_initrd cat /boot/initrd >>/boot/instrumented_initrd
== Loading ACPI SSDTs from EFI variables == Loading ACPI SSDTs from EFI variables
=====================================
This is the preferred method, when EFI is supported on the platform, because it This is the preferred method, when EFI is supported on the platform, because it
allows a persistent, OS independent way of storing the user defined SSDTs. There allows a persistent, OS independent way of storing the user defined SSDTs. There
...@@ -116,48 +123,49 @@ include/linux/efi.h). Writing to the file must also be done with one write ...@@ -116,48 +123,49 @@ include/linux/efi.h). Writing to the file must also be done with one write
operation. operation.
For example, you can use the following bash script to create/update an EFI For example, you can use the following bash script to create/update an EFI
variable with the content from a given file: variable with the content from a given file::
#!/bin/sh -e #!/bin/sh -e
while ! [ -z "$1" ]; do while ! [ -z "$1" ]; do
case "$1" in case "$1" in
"-f") filename="$2"; shift;; "-f") filename="$2"; shift;;
"-g") guid="$2"; shift;; "-g") guid="$2"; shift;;
*) name="$1";; *) name="$1";;
esac esac
shift shift
done done
usage() usage()
{ {
echo "Syntax: ${0##*/} -f filename [ -g guid ] name" echo "Syntax: ${0##*/} -f filename [ -g guid ] name"
exit 1 exit 1
} }
[ -n "$name" -a -f "$filename" ] || usage [ -n "$name" -a -f "$filename" ] || usage
EFIVARFS="/sys/firmware/efi/efivars" EFIVARFS="/sys/firmware/efi/efivars"
[ -d "$EFIVARFS" ] || exit 2 [ -d "$EFIVARFS" ] || exit 2
if stat -tf $EFIVARFS | grep -q -v de5e81e4; then if stat -tf $EFIVARFS | grep -q -v de5e81e4; then
mount -t efivarfs none $EFIVARFS mount -t efivarfs none $EFIVARFS
fi fi
# try to pick up an existing GUID # try to pick up an existing GUID
[ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-) [ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-)
# use a randomly generated GUID # use a randomly generated GUID
[ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)" [ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)"
# efivarfs expects all of the data in one write # efivarfs expects all of the data in one write
tmp=$(mktemp) tmp=$(mktemp)
/bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp /bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp
dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp) dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp)
rm $tmp rm $tmp
== Loading ACPI SSDTs from configfs == Loading ACPI SSDTs from configfs
================================
This option allows loading of user defined SSDTs from userspace via the configfs This option allows loading of user defined SSDTs from userspace via the configfs
interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be interface. The CONFIG_ACPI_CONFIGFS option must be select and configfs must be
...@@ -165,8 +173,8 @@ mounted. In the following examples, we assume that configfs has been mounted in ...@@ -165,8 +173,8 @@ mounted. In the following examples, we assume that configfs has been mounted in
/config. /config.
New tables can be loading by creating new directories in /config/acpi/table/ and New tables can be loading by creating new directories in /config/acpi/table/ and
writing the SSDT aml code in the aml attribute: writing the SSDT aml code in the aml attribute::
cd /config/acpi/table cd /config/acpi/table
mkdir my_ssdt mkdir my_ssdt
cat ~/ssdt.aml > my_ssdt/aml cat ~/ssdt.aml > my_ssdt/aml
Documentation/admin-guide/index.rst
View file @ 10b4768b
...@@ -77,6 +77,7 @@ configure specific aspects of kernel behavior to your liking. ...@@ -77,6 +77,7 @@ configure specific aspects of kernel behavior to your liking.
LSM/index LSM/index
mm/index mm/index
perf-security perf-security
acpi/index
.. only:: subproject and html .. only:: subproject and html
......
Documentation/driver-api/acpi/index.rst 0 → 100644
View file @ 10b4768b
============
ACPI Support
============
.. toctree::
:maxdepth: 2
linuxized-acpica
scan_handlers
Documentation/acpi/linuxized-acpica.txt → Documentation/driver-api/acpi/linuxized-acpica.rst
View file @ 10b4768b
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
============================================================
Linuxized ACPICA - Introduction to ACPICA Release Automation Linuxized ACPICA - Introduction to ACPICA Release Automation
============================================================
Copyright (C) 2013-2016, Intel Corporation :Copyright: |copy| 2013-2016, Intel Corporation
Author: Lv Zheng <lv.zheng@intel.com>
:Author: Lv Zheng <lv.zheng@intel.com>
Abstract:
Abstract
========
This document describes the ACPICA project and the relationship between This document describes the ACPICA project and the relationship between
ACPICA and Linux. It also describes how ACPICA code in drivers/acpi/acpica, ACPICA and Linux. It also describes how ACPICA code in drivers/acpi/acpica,
include/acpi and tools/power/acpi is automatically updated to follow the include/acpi and tools/power/acpi is automatically updated to follow the
upstream. upstream.
ACPICA Project
==============
1. ACPICA Project The ACPI Component Architecture (ACPICA) project provides an operating
system (OS)-independent reference implementation of the Advanced
The ACPI Component Architecture (ACPICA) project provides an operating Configuration and Power Interface Specification (ACPI). It has been
system (OS)-independent reference implementation of the Advanced adapted by various host OSes. By directly integrating ACPICA, Linux can
Configuration and Power Interface Specification (ACPI). It has been also benefit from the application experiences of ACPICA from other host
adapted by various host OSes. By directly integrating ACPICA, Linux can OSes.
also benefit from the application experiences of ACPICA from other host
OSes.
The homepage of ACPICA project is: www.acpica.org, it is maintained and The homepage of ACPICA project is: www.acpica.org, it is maintained and
supported by Intel Corporation. supported by Intel Corporation.
The following figure depicts the Linux ACPI subsystem where the ACPICA The following figure depicts the Linux ACPI subsystem where the ACPICA
adaptation is included: adaptation is included::
+---------------------------------------------------------+ +---------------------------------------------------------+
| | | |
...@@ -71,21 +77,27 @@ upstream. ...@@ -71,21 +77,27 @@ upstream.
Figure 1. Linux ACPI Software Components Figure 1. Linux ACPI Software Components
NOTE: .. note::
A. OS Service Layer - Provided by Linux to offer OS dependent A. OS Service Layer - Provided by Linux to offer OS dependent
implementation of the predefined ACPICA interfaces (acpi_os_*). implementation of the predefined ACPICA interfaces (acpi_os_*).
::
include/acpi/acpiosxf.h include/acpi/acpiosxf.h
drivers/acpi/osl.c drivers/acpi/osl.c
include/acpi/platform include/acpi/platform
include/asm/acenv.h include/asm/acenv.h
B. ACPICA Functionality - Released from ACPICA code base to offer B. ACPICA Functionality - Released from ACPICA code base to offer
OS independent implementation of the ACPICA interfaces (acpi_*). OS independent implementation of the ACPICA interfaces (acpi_*).
::
drivers/acpi/acpica drivers/acpi/acpica
include/acpi/ac*.h include/acpi/ac*.h
tools/power/acpi tools/power/acpi
C. Linux/ACPI Functionality - Providing Linux specific ACPI C. Linux/ACPI Functionality - Providing Linux specific ACPI
functionality to the other Linux kernel subsystems and user space functionality to the other Linux kernel subsystems and user space
programs. programs.
::
drivers/acpi drivers/acpi
include/linux/acpi.h include/linux/acpi.h
include/linux/acpi*.h include/linux/acpi*.h
...@@ -95,24 +107,27 @@ upstream. ...@@ -95,24 +107,27 @@ upstream.
ACPI subsystem to offer architecture specific implementation of the ACPI subsystem to offer architecture specific implementation of the
ACPI interfaces. They are Linux specific components and are out of ACPI interfaces. They are Linux specific components and are out of
the scope of this document. the scope of this document.
::
include/asm/acpi.h include/asm/acpi.h
include/asm/acpi*.h include/asm/acpi*.h
arch/*/acpi arch/*/acpi
2. ACPICA Release ACPICA Release
==============
The ACPICA project maintains its code base at the following repository URL: The ACPICA project maintains its code base at the following repository URL:
https://github.com/acpica/acpica.git. As a rule, a release is made every https://github.com/acpica/acpica.git. As a rule, a release is made every
month. month.
As the coding style adopted by the ACPICA project is not acceptable by As the coding style adopted by the ACPICA project is not acceptable by
Linux, there is a release process to convert the ACPICA git commits into Linux, there is a release process to convert the ACPICA git commits into
Linux patches. The patches generated by this process are referred to as Linux patches. The patches generated by this process are referred to as
"linuxized ACPICA patches". The release process is carried out on a local "linuxized ACPICA patches". The release process is carried out on a local
copy the ACPICA git repository. Each commit in the monthly release is copy the ACPICA git repository. Each commit in the monthly release is
converted into a linuxized ACPICA patch. Together, they form the monthly converted into a linuxized ACPICA patch. Together, they form the monthly
ACPICA release patchset for the Linux ACPI community. This process is ACPICA release patchset for the Linux ACPI community. This process is
illustrated in the following figure: illustrated in the following figure::
+-----------------------------+ +-----------------------------+
| acpica / master (-) commits | | acpica / master (-) commits |
...@@ -153,7 +168,7 @@ upstream. ...@@ -153,7 +168,7 @@ upstream.
Figure 2. ACPICA -> Linux Upstream Process Figure 2. ACPICA -> Linux Upstream Process
NOTE: .. note::
A. Linuxize Utilities - Provided by the ACPICA repository, including a A. Linuxize Utilities - Provided by the ACPICA repository, including a
utility located in source/tools/acpisrc folder and a number of utility located in source/tools/acpisrc folder and a number of
scripts located in generate/linux folder. scripts located in generate/linux folder.
...@@ -170,19 +185,20 @@ upstream. ...@@ -170,19 +185,20 @@ upstream.
following kernel configuration options: following kernel configuration options:
CONFIG_ACPI/CONFIG_ACPI_DEBUG/CONFIG_ACPI_DEBUGGER CONFIG_ACPI/CONFIG_ACPI_DEBUG/CONFIG_ACPI_DEBUGGER
3. ACPICA Divergences ACPICA Divergences
==================
Ideally, all of the ACPICA commits should be converted into Linux patches Ideally, all of the ACPICA commits should be converted into Linux patches
automatically without manual modifications, the "linux / master" tree should automatically without manual modifications, the "linux / master" tree should
contain the ACPICA code that exactly corresponds to the ACPICA code contain the ACPICA code that exactly corresponds to the ACPICA code
contained in "new linuxized acpica" tree and it should be possible to run contained in "new linuxized acpica" tree and it should be possible to run
the release process fully automatically. the release process fully automatically.
As a matter of fact, however, there are source code differences between As a matter of fact, however, there are source code differences between
the ACPICA code in Linux and the upstream ACPICA code, referred to as the ACPICA code in Linux and the upstream ACPICA code, referred to as
"ACPICA Divergences". "ACPICA Divergences".
The various sources of ACPICA divergences include: The various sources of ACPICA divergences include:
1. Legacy divergences - Before the current ACPICA release process was 1. Legacy divergences - Before the current ACPICA release process was
established, there already had been divergences between Linux and established, there already had been divergences between Linux and
ACPICA. Over the past several years those divergences have been greatly ACPICA. Over the past several years those divergences have been greatly
...@@ -213,11 +229,12 @@ upstream. ...@@ -213,11 +229,12 @@ upstream.
rebased on the ACPICA side in order to offer better solutions, new ACPICA rebased on the ACPICA side in order to offer better solutions, new ACPICA
divergences are generated. divergences are generated.
4. ACPICA Development ACPICA Development
==================
This paragraph guides Linux developers to use the ACPICA upstream release This paragraph guides Linux developers to use the ACPICA upstream release
utilities to obtain Linux patches corresponding to upstream ACPICA commits utilities to obtain Linux patches corresponding to upstream ACPICA commits
before they become available from the ACPICA release process. before they become available from the ACPICA release process.
1. Cherry-pick an ACPICA commit 1. Cherry-pick an ACPICA commit
...@@ -225,7 +242,7 @@ upstream. ...@@ -225,7 +242,7 @@ upstream.
you want to cherry pick must be committed into the local repository. you want to cherry pick must be committed into the local repository.
Then the gen-patch.sh command can help to cherry-pick an ACPICA commit Then the gen-patch.sh command can help to cherry-pick an ACPICA commit
from the ACPICA local repository: from the ACPICA local repository::
$ git clone https://github.com/acpica/acpica $ git clone https://github.com/acpica/acpica
$ cd acpica $ cd acpica
...@@ -240,7 +257,7 @@ upstream. ...@@ -240,7 +257,7 @@ upstream.
changes that haven't been applied to Linux yet. changes that haven't been applied to Linux yet.
You can generate the ACPICA release series yourself and rebase your code on You can generate the ACPICA release series yourself and rebase your code on
top of the generated ACPICA release patches: top of the generated ACPICA release patches::
$ git clone https://github.com/acpica/acpica $ git clone https://github.com/acpica/acpica
$ cd acpica $ cd acpica
...@@ -254,7 +271,7 @@ upstream. ...@@ -254,7 +271,7 @@ upstream.
3. Inspect the current divergences 3. Inspect the current divergences
If you have local copies of both Linux and upstream ACPICA, you can generate If you have local copies of both Linux and upstream ACPICA, you can generate
a diff file indicating the state of the current divergences: a diff file indicating the state of the current divergences::
# git clone https://github.com/acpica/acpica # git clone https://github.com/acpica/acpica
# git clone http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git # git clone http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
......
Documentation/acpi/scan_handlers.txt → Documentation/driver-api/acpi/scan_handlers.rst
View file @ 10b4768b
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
==================
ACPI Scan Handlers ACPI Scan Handlers
==================
:Copyright: |copy| 2012, Intel Corporation
Copyright (C) 2012, Intel Corporation :Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
During system initialization and ACPI-based device hot-add, the ACPI namespace During system initialization and ACPI-based device hot-add, the ACPI namespace
is scanned in search of device objects that generally represent various pieces is scanned in search of device objects that generally represent various pieces
...@@ -30,14 +36,14 @@ to configure that link so that the kernel can use it. ...@@ -30,14 +36,14 @@ to configure that link so that the kernel can use it.
Those additional configuration tasks usually depend on the type of the hardware Those additional configuration tasks usually depend on the type of the hardware
component represented by the given device node which can be determined on the component represented by the given device node which can be determined on the
basis of the device node's hardware ID (HID). They are performed by objects basis of the device node's hardware ID (HID). They are performed by objects
called ACPI scan handlers represented by the following structure: called ACPI scan handlers represented by the following structure::
struct acpi_scan_handler { struct acpi_scan_handler {
const struct acpi_device_id *ids; const struct acpi_device_id *ids;
struct list_head list_node; struct list_head list_node;
int (*attach)(struct acpi_device *dev, const struct acpi_device_id *id); int (*attach)(struct acpi_device *dev, const struct acpi_device_id *id);
void (*detach)(struct acpi_device *dev); void (*detach)(struct acpi_device *dev);
}; };
where ids is the list of IDs of device nodes the given handler is supposed to where ids is the list of IDs of device nodes the given handler is supposed to
take care of, list_node is the hook to the global list of ACPI scan handlers take care of, list_node is the hook to the global list of ACPI scan handlers
......
Documentation/driver-api/index.rst
View file @ 10b4768b
...@@ -56,6 +56,7 @@ available subsections can be seen below. ...@@ -56,6 +56,7 @@ available subsections can be seen below.
slimbus slimbus
soundwire/index soundwire/index
fpga/index fpga/index
acpi/index
.. only:: subproject and html .. only:: subproject and html
......
Documentation/acpi/DSD-properties-rules.txt → Documentation/firmware-guide/acpi/DSD-properties-rules.rst
View file @ 10b4768b
.. SPDX-License-Identifier: GPL-2.0
==================================
_DSD Device Properties Usage Rules _DSD Device Properties Usage Rules
---------------------------------- ==================================
Properties, Property Sets and Property Subsets Properties, Property Sets and Property Subsets
---------------------------------------------- ==============================================
The _DSD (Device Specific Data) configuration object, introduced in ACPI 5.1, 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 allows any type of device configuration data to be provided via the ACPI
...@@ -18,7 +21,7 @@ specific type) associated with it. ...@@ -18,7 +21,7 @@ specific type) associated with it.
In the ACPI _DSD context it is an element of the sub-package following the 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 generic Device Properties UUID in the _DSD return package as specified in the
Device Properties UUID definition document [1]. Device Properties UUID definition document [1]_.
It also may be regarded as the definition of a key and the associated data type 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 that can be returned by _DSD in the Device Properties UUID sub-package for a
...@@ -33,14 +36,14 @@ Property subsets are nested collections of properties. Each of them is ...@@ -33,14 +36,14 @@ Property subsets are nested collections of properties. Each of them is
associated with an additional key (name) allowing the subset to be referred 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 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 representation of property subsets is via the mechanism specified in the
Hierarchical Properties Extension UUID definition document [2]. Hierarchical Properties Extension UUID definition document [2]_.
Property sets may be hierarchical. That is, a property set may contain Property sets may be hierarchical. That is, a property set may contain
multiple property subsets that each may contain property subsets of its multiple property subsets that each may contain property subsets of its
own and so on. own and so on.
General Validity Rule for Property Sets General Validity Rule for Property Sets
--------------------------------------- =======================================
Valid property sets must follow the guidance given by the Device Properties UUID Valid property sets must follow the guidance given by the Device Properties UUID
definition document [1]. definition document [1].
...@@ -73,7 +76,7 @@ suitable for the ACPI environment and consequently they cannot belong to a valid ...@@ -73,7 +76,7 @@ suitable for the ACPI environment and consequently they cannot belong to a valid
property set. property set.
Property Sets and Device Tree Bindings Property Sets and Device Tree Bindings
-------------------------------------- ======================================
It often is useful to make _DSD return property sets that follow Device Tree It often is useful to make _DSD return property sets that follow Device Tree
bindings. bindings.
...@@ -91,7 +94,7 @@ expected to automatically work in the ACPI environment regardless of their ...@@ -91,7 +94,7 @@ expected to automatically work in the ACPI environment regardless of their
contents. contents.
References References
---------- ==========
[1] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf .. [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 .. [2] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf
Documentation/acpi/acpi-lid.txt → Documentation/firmware-guide/acpi/acpi-lid.rst
View file @ 10b4768b
Special Usage Model of the ACPI Control Method Lid Device .. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
Copyright (C) 2016, Intel Corporation =========================================================
Author: Lv Zheng <lv.zheng@intel.com> Special Usage Model of the ACPI Control Method Lid Device
=========================================================
:Copyright: |copy| 2016, Intel Corporation
Abstract: :Author: Lv Zheng <lv.zheng@intel.com>
Platforms containing lids convey lid state (open/close) to OSPMs using a Abstract
control method lid device. To implement this, the AML tables issue ========
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 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 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". report the "current" state of the lid as either "opened" or "closed".
...@@ -19,7 +24,8 @@ taken into account. This document describes the restrictions and the ...@@ -19,7 +24,8 @@ taken into account. This document describes the restrictions and the
expections of the Linux ACPI lid device driver. expections of the Linux ACPI lid device driver.
1. Restrictions of the returning value of the _LID control method Restrictions of the returning value of the _LID control method
==============================================================
The _LID control method is described to return the "current" lid state. The _LID control method is described to return the "current" lid state.
However the word of "current" has ambiguity, some buggy AML tables return However the word of "current" has ambiguity, some buggy AML tables return
...@@ -30,7 +36,8 @@ initial returning value. When the AML tables implement this control method ...@@ -30,7 +36,8 @@ initial returning value. When the AML tables implement this control method
with cached value, the initial returning value is likely not reliable. with cached value, the initial returning value is likely not reliable.
There are platforms always retun "closed" as initial lid state. There are platforms always retun "closed" as initial lid state.
2. Restrictions of the lid state change notifications Restrictions of the lid state change notifications
==================================================
There are buggy AML tables never notifying when the lid device state is There are buggy AML tables never notifying when the lid device state is
changed to "opened". Thus the "opened" notification is not guaranteed. But changed to "opened". Thus the "opened" notification is not guaranteed. But
...@@ -39,18 +46,22 @@ state is changed to "closed". The "closed" notification is normally used to ...@@ -39,18 +46,22 @@ state is changed to "closed". The "closed" notification is normally used to
trigger some system power saving operations on Windows. Since it is fully trigger some system power saving operations on Windows. Since it is fully
tested, it is reliable from all AML tables. tested, it is reliable from all AML tables.
3. Expections for the userspace users of the ACPI lid device driver Expections for the userspace users of the ACPI lid device driver
================================================================
The ACPI button driver exports the lid state to the userspace via the The ACPI button driver exports the lid state to the userspace via the
following file: following file::
/proc/acpi/button/lid/LID0/state /proc/acpi/button/lid/LID0/state
This file actually calls the _LID control method described above. And given This file actually calls the _LID control method described above. And given
the previous explanation, it is not reliable enough on some platforms. So 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 it is advised for the userspace program to not to solely rely on this file
to determine the actual lid state. to determine the actual lid state.
The ACPI button driver emits the following input event to the userspace: The ACPI button driver emits the following input event to the userspace:
SW_LID * SW_LID
The ACPI lid device driver is implemented to try to deliver the platform 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 triggered events to the userspace. However, given the fact that the buggy
firmware cannot make sure "opened"/"closed" events are paired, the ACPI firmware cannot make sure "opened"/"closed" events are paired, the ACPI
...@@ -59,20 +70,25 @@ button driver uses the following 3 modes in order not to trigger issues. ...@@ -59,20 +70,25 @@ 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" If the userspace hasn't been prepared to ignore the unreliable "opened"
events and the unreliable initial state notification, Linux users can use events and the unreliable initial state notification, Linux users can use
the following kernel parameters to handle the possible issues: the following kernel parameters to handle the possible issues:
A. button.lid_init_state=method: A. button.lid_init_state=method:
When this option is specified, the ACPI button driver reports the When this option is specified, the ACPI button driver reports the
initial lid state using the returning value of the _LID control method initial lid state using the returning value of the _LID control method
and whether the "opened"/"closed" events are paired fully relies on the and whether the "opened"/"closed" events are paired fully relies on the
firmware implementation. firmware implementation.
This option can be used to fix some platforms where the returning value 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 of the _LID control method is reliable but the initial lid state
notification is missing. notification is missing.
This option is the default behavior during the period the userspace This option is the default behavior during the period the userspace
isn't ready to handle the buggy AML tables. isn't ready to handle the buggy AML tables.
B. button.lid_init_state=open: B. button.lid_init_state=open:
When this option is specified, the ACPI button driver always reports the When this option is specified, the ACPI button driver always reports the
initial lid state as "opened" and whether the "opened"/"closed" events initial lid state as "opened" and whether the "opened"/"closed" events
are paired fully relies on the firmware implementation. are paired fully relies on the firmware implementation.
This may fix some platforms where the returning value of the _LID This may fix some platforms where the returning value of the _LID
control method is not reliable and the initial lid state notification is control method is not reliable and the initial lid state notification is
missing. missing.
...@@ -80,6 +96,7 @@ B. button.lid_init_state=open: ...@@ -80,6 +96,7 @@ B. button.lid_init_state=open:
If the userspace has been prepared to ignore the unreliable "opened" events If the userspace has been prepared to ignore the unreliable "opened" events
and the unreliable initial state notification, Linux users should always and the unreliable initial state notification, Linux users should always
use the following kernel parameter: use the following kernel parameter:
C. button.lid_init_state=ignore: C. button.lid_init_state=ignore:
When this option is specified, the ACPI button driver never reports the When this option is specified, the ACPI button driver never reports the
initial lid state and there is a compensation mechanism implemented to initial lid state and there is a compensation mechanism implemented to
...@@ -89,6 +106,7 @@ C. button.lid_init_state=ignore: ...@@ -89,6 +106,7 @@ C. button.lid_init_state=ignore:
notifications can be delivered to the userspace when the lid is actually notifications can be delivered to the userspace when the lid is actually
opens given that some AML tables do not send "opened" notifications opens given that some AML tables do not send "opened" notifications
reliably. reliably.
In this mode, if everything is correctly implemented by the platform In this mode, if everything is correctly implemented by the platform
firmware, the old userspace programs should still work. Otherwise, the firmware, the old userspace programs should still work. Otherwise, the
new userspace programs are required to work with the ACPI button driver. new userspace programs are required to work with the ACPI button driver.
......
Documentation/firmware-guide/acpi/aml-debugger.rst 0 → 100644
View file @ 10b4768b
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
================
The AML Debugger
================
:Copyright: |copy| 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"
Documentation/acpi/apei/einj.txt → Documentation/firmware-guide/acpi/apei/einj.rst
View file @ 10b4768b
APEI Error INJection .. SPDX-License-Identifier: GPL-2.0
~~~~~~~~~~~~~~~~~~~~
====================
APEI Error INJection
====================
EINJ provides a hardware error injection mechanism. It is very useful EINJ provides a hardware error injection mechanism. It is very useful
for debugging and testing APEI and RAS features in general. for debugging and testing APEI and RAS features in general.
You need to check whether your BIOS supports EINJ first. For that, look You need to check whether your BIOS supports EINJ first. For that, look
for early boot messages similar to this one: for early boot messages similar to this one::
ACPI: EINJ 0x000000007370A000 000150 (v01 INTEL 00000001 INTL 00000001) ACPI: EINJ 0x000000007370A000 000150 (v01 INTEL 00000001 INTL 00000001)
which shows that the BIOS is exposing an EINJ table - it is the which shows that the BIOS is exposing an EINJ table - it is the
mechanism through which the injection is done. mechanism through which the injection is done.
...@@ -23,11 +26,11 @@ order to see the APEI,EINJ,... functionality supported and exposed by ...@@ -23,11 +26,11 @@ order to see the APEI,EINJ,... functionality supported and exposed by
the BIOS menu. the BIOS menu.
To use EINJ, make sure the following are options enabled in your kernel To use EINJ, make sure the following are options enabled in your kernel
configuration: configuration::
CONFIG_DEBUG_FS CONFIG_DEBUG_FS
CONFIG_ACPI_APEI CONFIG_ACPI_APEI
CONFIG_ACPI_APEI_EINJ CONFIG_ACPI_APEI_EINJ
The EINJ user interface is in <debugfs mount point>/apei/einj. The EINJ user interface is in <debugfs mount point>/apei/einj.
...@@ -37,20 +40,22 @@ The following files belong to it: ...@@ -37,20 +40,22 @@ The following files belong to it:
This file shows which error types are supported: This file shows which error types are supported:
================ ===================================
Error Type Value Error Description Error Type Value Error Description
================ ================= ================ ===================================
0x00000001 Processor Correctable 0x00000001 Processor Correctable
0x00000002 Processor Uncorrectable non-fatal 0x00000002 Processor Uncorrectable non-fatal
0x00000004 Processor Uncorrectable fatal 0x00000004 Processor Uncorrectable fatal
0x00000008 Memory Correctable 0x00000008 Memory Correctable
0x00000010 Memory Uncorrectable non-fatal 0x00000010 Memory Uncorrectable non-fatal
0x00000020 Memory Uncorrectable fatal 0x00000020 Memory Uncorrectable fatal
0x00000040 PCI Express Correctable 0x00000040 PCI Express Correctable
0x00000080 PCI Express Uncorrectable fatal 0x00000080 PCI Express Uncorrectable fatal
0x00000100 PCI Express Uncorrectable non-fatal 0x00000100 PCI Express Uncorrectable non-fatal
0x00000200 Platform Correctable 0x00000200 Platform Correctable
0x00000400 Platform Uncorrectable non-fatal 0x00000400 Platform Uncorrectable non-fatal
0x00000800 Platform Uncorrectable fatal 0x00000800 Platform Uncorrectable fatal
================ ===================================
The format of the file contents are as above, except present are only The format of the file contents are as above, except present are only
the available error types. the available error types.
...@@ -73,9 +78,12 @@ The following files belong to it: ...@@ -73,9 +78,12 @@ The following files belong to it:
injection. Value is a bitmask as specified in ACPI5.0 spec for the injection. Value is a bitmask as specified in ACPI5.0 spec for the
SET_ERROR_TYPE_WITH_ADDRESS data structure: SET_ERROR_TYPE_WITH_ADDRESS data structure:
Bit 0 - Processor APIC field valid (see param3 below). Bit 0
Bit 1 - Memory address and mask valid (param1 and param2). Processor APIC field valid (see param3 below).
Bit 2 - PCIe (seg,bus,dev,fn) valid (see param4 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 If set to zero, legacy behavior is mimicked where the type of
injection specifies just one bit set, and param1 is multiplexed. injection specifies just one bit set, and param1 is multiplexed.
...@@ -121,7 +129,7 @@ BIOS versions based on the ACPI 5.0 specification have more control over ...@@ -121,7 +129,7 @@ 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 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 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 param2 for bit 1) so that you have more information added to the error
signature being injected. The actual data passed is this: signature being injected. The actual data passed is this::
memory_address = param1; memory_address = param1;
memory_address_range = param2; memory_address_range = param2;
...@@ -131,7 +139,7 @@ signature being injected. The actual data passed is this: ...@@ -131,7 +139,7 @@ signature being injected. The actual data passed is this:
For memory errors (type 0x8, 0x10 and 0x20) the address is set using 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 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 express errors (type 0x40, 0x80 and 0x100) the segment, bus, device and
function are specified using param1: function are specified using param1::
31 24 23 16 15 11 10 8 7 0 31 24 23 16 15 11 10 8 7 0
+-------------------------------------------------+ +-------------------------------------------------+
...@@ -152,26 +160,26 @@ documentation for details (and expect changes to this API if vendors ...@@ -152,26 +160,26 @@ documentation for details (and expect changes to this API if vendors
creativity in using this feature expands beyond our expectations). creativity in using this feature expands beyond our expectations).
An error injection example: An error injection example::
# cd /sys/kernel/debug/apei/einj # cd /sys/kernel/debug/apei/einj
# cat available_error_type # See which errors can be injected # cat available_error_type # See which errors can be injected
0x00000002 Processor Uncorrectable non-fatal 0x00000002 Processor Uncorrectable non-fatal
0x00000008 Memory Correctable 0x00000008 Memory Correctable
0x00000010 Memory Uncorrectable non-fatal 0x00000010 Memory Uncorrectable non-fatal
# echo 0x12345000 > param1 # Set memory address for injection # echo 0x12345000 > param1 # Set memory address for injection
# echo $((-1 << 12)) > param2 # Mask 0xfffffffffffff000 - anywhere in this page # echo $((-1 << 12)) > param2 # Mask 0xfffffffffffff000 - anywhere in this page
# echo 0x8 > error_type # Choose correctable memory error # echo 0x8 > error_type # Choose correctable memory error
# echo 1 > error_inject # Inject now # echo 1 > error_inject # Inject now
You should see something like this in dmesg: You should see something like this in dmesg::
[22715.830801] EDAC sbridge MC3: HANDLING MCE MEMORY ERROR [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: CPU 0: Machine Check Event: 0 Bank 7: 8c00004000010090
[22715.834759] EDAC sbridge MC3: TSC 0 [22715.834759] EDAC sbridge MC3: TSC 0
[22715.834759] EDAC sbridge MC3: ADDR 12345000 EDAC sbridge MC3: MISC 144780c86 [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 [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) [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 For more information about EINJ, please refer to ACPI specification
version 4.0, section 17.5 and ACPI 5.0, section 18.6. version 4.0, section 17.5 and ACPI 5.0, section 18.6.
Documentation/firmware-guide/acpi/apei/output_format.rst 0 → 100644
View file @ 10b4768b
.. SPDX-License-Identifier: GPL-2.0
==================
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.
Documentation/acpi/debug.txt → Documentation/firmware-guide/acpi/debug.rst
View file @ 10b4768b
ACPI Debug Output .. SPDX-License-Identifier: GPL-2.0
=================
ACPI Debug Output
=================
The ACPI CA, the Linux ACPI core, and some ACPI drivers can generate debug The ACPI CA, the Linux ACPI core, and some ACPI drivers can generate debug
output. This document describes how to use this facility. output. This document describes how to use this facility.
Compile-time configuration Compile-time configuration
-------------------------- ==========================
ACPI debug output is globally enabled by CONFIG_ACPI_DEBUG. If this config 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 option is turned off, the debug messages are not even built into the
kernel. kernel.
Boot- and run-time configuration Boot- and run-time configuration
-------------------------------- ================================
When CONFIG_ACPI_DEBUG=y, you can select the component and level of messages 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 you're interested in. At boot-time, use the acpi.debug_layer and
...@@ -21,7 +24,7 @@ debug_layer and debug_level files in /sys/module/acpi/parameters/ to control ...@@ -21,7 +24,7 @@ debug_layer and debug_level files in /sys/module/acpi/parameters/ to control
the debug messages. the debug messages.
debug_layer (component) debug_layer (component)
----------------------- =======================
The "debug_layer" is a mask that selects components of interest, e.g., a 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 specific driver or part of the ACPI interpreter. To build the debug_layer
...@@ -33,7 +36,7 @@ to /sys/module/acpi/parameters/debug_layer. ...@@ -33,7 +36,7 @@ to /sys/module/acpi/parameters/debug_layer.
The possible components are defined in include/acpi/acoutput.h and The possible components are defined in include/acpi/acoutput.h and
include/acpi/acpi_drivers.h. Reading /sys/module/acpi/parameters/debug_layer include/acpi/acpi_drivers.h. Reading /sys/module/acpi/parameters/debug_layer
shows the supported mask values, currently these: shows the supported mask values, currently these::
ACPI_UTILITIES 0x00000001 ACPI_UTILITIES 0x00000001
ACPI_HARDWARE 0x00000002 ACPI_HARDWARE 0x00000002
...@@ -65,7 +68,7 @@ shows the supported mask values, currently these: ...@@ -65,7 +68,7 @@ shows the supported mask values, currently these:
ACPI_PROCESSOR_COMPONENT 0x20000000 ACPI_PROCESSOR_COMPONENT 0x20000000
debug_level debug_level
----------- ===========
The "debug_level" is a mask that selects different types of messages, e.g., The "debug_level" is a mask that selects different types of messages, e.g.,
those related to initialization, method execution, informational messages, etc. those related to initialization, method execution, informational messages, etc.
...@@ -81,7 +84,7 @@ to /sys/module/acpi/parameters/debug_level. ...@@ -81,7 +84,7 @@ to /sys/module/acpi/parameters/debug_level.
The possible levels are defined in include/acpi/acoutput.h. Reading The possible levels are defined in include/acpi/acoutput.h. Reading
/sys/module/acpi/parameters/debug_level shows the supported mask values, /sys/module/acpi/parameters/debug_level shows the supported mask values,
currently these: currently these::
ACPI_LV_INIT 0x00000001 ACPI_LV_INIT 0x00000001
ACPI_LV_DEBUG_OBJECT 0x00000002 ACPI_LV_DEBUG_OBJECT 0x00000002
...@@ -113,9 +116,9 @@ currently these: ...@@ -113,9 +116,9 @@ currently these:
ACPI_LV_EVENTS 0x80000000 ACPI_LV_EVENTS 0x80000000
Examples Examples
-------- ========
For example, drivers/acpi/bus.c contains this: For example, drivers/acpi/bus.c contains this::
#define _COMPONENT ACPI_BUS_COMPONENT #define _COMPONENT ACPI_BUS_COMPONENT
... ...
...@@ -127,22 +130,22 @@ statement uses ACPI_DB_INFO, which is macro based on the ACPI_LV_INFO ...@@ -127,22 +130,22 @@ statement uses ACPI_DB_INFO, which is macro based on the ACPI_LV_INFO
definition.) definition.)
Enable all AML "Debug" output (stores to the Debug object while interpreting Enable all AML "Debug" output (stores to the Debug object while interpreting
AML) during boot: AML) during boot::
acpi.debug_layer=0xffffffff acpi.debug_level=0x2 acpi.debug_layer=0xffffffff acpi.debug_level=0x2
Enable PCI and PCI interrupt routing debug messages: Enable PCI and PCI interrupt routing debug messages::
acpi.debug_layer=0x400000 acpi.debug_level=0x4 acpi.debug_layer=0x400000 acpi.debug_level=0x4
Enable all ACPI hardware-related messages: Enable all ACPI hardware-related messages::
acpi.debug_layer=0x2 acpi.debug_level=0xffffffff acpi.debug_layer=0x2 acpi.debug_level=0xffffffff
Enable all ACPI_DB_INFO messages after boot: Enable all ACPI_DB_INFO messages after boot::
# echo 0x4 > /sys/module/acpi/parameters/debug_level # echo 0x4 > /sys/module/acpi/parameters/debug_level
Show all valid component values: Show all valid component values::
# cat /sys/module/acpi/parameters/debug_layer # cat /sys/module/acpi/parameters/debug_layer
Documentation/acpi/dsd/data-node-references.txt → Documentation/firmware-guide/acpi/dsd/data-node-references.rst
View file @ 10b4768b
Copyright (C) 2018 Intel Corporation .. SPDX-License-Identifier: GPL-2.0
Author: Sakari Ailus <sakari.ailus@linux.intel.com> .. include:: <isonum.txt>
===================================
Referencing hierarchical data nodes Referencing hierarchical data nodes
----------------------------------- ===================================
:Copyright: |copy| 2018 Intel Corporation
:Author: Sakari Ailus <sakari.ailus@linux.intel.com>
ACPI in general allows referring to device objects in the tree only. ACPI in general allows referring to device objects in the tree only.
Hierarchical data extension nodes may not be referred to directly, hence this Hierarchical data extension nodes may not be referred to directly, hence this
...@@ -28,13 +31,14 @@ extension key. ...@@ -28,13 +31,14 @@ extension key.
Example Example
------- =======
In the ASL snippet below, the "reference" _DSD property [2] contains a In the ASL snippet below, the "reference" _DSD property [2] contains a
device object reference to DEV0 and under that device object, a device object reference to DEV0 and under that device object, a
hierarchical data extension key "node@1" referring to the NOD1 object hierarchical data extension key "node@1" referring to the NOD1 object
and lastly, a hierarchical data extension key "anothernode" referring to and lastly, a hierarchical data extension key "anothernode" referring to
the ANOD object which is also the final target node of the reference. the ANOD object which is also the final target node of the reference.
::
Device (DEV0) Device (DEV0)
{ {
...@@ -75,15 +79,15 @@ Example ...@@ -75,15 +79,15 @@ Example
}) })
} }
Please also see a graph example in graph.txt . Please also see a graph example in :doc:`graph`.
References References
---------- ==========
[1] Hierarchical Data Extension UUID For _DSD. [1] Hierarchical Data Extension UUID For _DSD.
<URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, <http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
referenced 2018-07-17. referenced 2018-07-17.
[2] Device Properties UUID For _DSD. [2] Device Properties UUID For _DSD.
<URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, <http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
referenced 2016-10-04. referenced 2016-10-04.
Documentation/acpi/dsd/graph.txt → Documentation/firmware-guide/acpi/dsd/graph.rst
View file @ 10b4768b
Graphs .. SPDX-License-Identifier: GPL-2.0
======
Graphs
======
_DSD _DSD
---- ====
_DSD (Device Specific Data) [7] is a predefined ACPI device _DSD (Device Specific Data) [7] is a predefined ACPI device
configuration object that can be used to convey information on configuration object that can be used to convey information on
...@@ -30,7 +33,7 @@ hierarchical data extension array on each depth. ...@@ -30,7 +33,7 @@ hierarchical data extension array on each depth.
Ports and endpoints Ports and endpoints
------------------- ===================
The port and endpoint concepts are very similar to those in Devicetree The port and endpoint concepts are very similar to those in Devicetree
[3]. A port represents an interface in a device, and an endpoint [3]. A port represents an interface in a device, and an endpoint
...@@ -38,9 +41,9 @@ represents a connection to that interface. ...@@ -38,9 +41,9 @@ represents a connection to that interface.
All port nodes are located under the device's "_DSD" node in the hierarchical 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 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 with "port" and must be followed by the "@" character and the number of the
as its key. The target object it refers to should be called "PRTX", where "X" is port as its key. The target object it refers to should be called "PRTX", where
the number of the port. An example of such a package would be: "X" is the number of the port. An example of such a package would be::
Package() { "port@4", PRT4 } Package() { "port@4", PRT4 }
...@@ -49,7 +52,7 @@ data extension key of the endpoint nodes must begin with ...@@ -49,7 +52,7 @@ data extension key of the endpoint nodes must begin with
"endpoint" and must be followed by the "@" character and the number of the "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 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 number of the port and "Y" is the number of the endpoint. An example of such a
package would be: package would be::
Package() { "endpoint@0", EP40 } Package() { "endpoint@0", EP40 }
...@@ -62,85 +65,85 @@ of that port shall be zero. Similarly, if a port may only have a single ...@@ -62,85 +65,85 @@ of that port shall be zero. Similarly, if a port may only have a single
endpoint, the number of that endpoint shall be zero. endpoint, the number of that endpoint shall be zero.
The endpoint reference uses property extension with "remote-endpoint" property The endpoint reference uses property extension with "remote-endpoint" property
name followed by a reference in the same package. Such references consist of the 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 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 reference under the device and finally the first package entry of the endpoint
data extension reference under the port. Individual references thus appear as: data extension reference under the port. Individual references thus appear as::
Package() { device, "port@X", "endpoint@Y" } Package() { device, "port@X", "endpoint@Y" }
In the above example, "X" is the number of the port and "Y" is the number of the In the above example, "X" is the number of the port and "Y" is the number of
endpoint. the endpoint.
The references to endpoints must be always done both ways, to the The references to endpoints must be always done both ways, to the
remote endpoint and back from the referred remote endpoint node. remote endpoint and back from the referred remote endpoint node.
A simple example of this is show below: A simple example of this is show below::
Scope (\_SB.PCI0.I2C2) Scope (\_SB.PCI0.I2C2)
{ {
Device (CAM0) Device (CAM0)
{ {
Name (_DSD, Package () { Name (_DSD, Package () {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () { Package () {
Package () { "compatible", Package () { "nokia,smia" } }, Package () { "compatible", Package () { "nokia,smia" } },
}, },
ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
Package () { Package () {
Package () { "port@0", PRT0 }, Package () { "port@0", PRT0 },
} }
}) })
Name (PRT0, Package() { Name (PRT0, Package() {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () { Package () {
Package () { "reg", 0 }, Package () { "reg", 0 },
}, },
ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
Package () { Package () {
Package () { "endpoint@0", EP00 }, Package () { "endpoint@0", EP00 },
} }
}) })
Name (EP00, Package() { Name (EP00, Package() {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () { Package () {
Package () { "reg", 0 }, Package () { "reg", 0 },
Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } }, Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } },
} }
}) })
} }
} }
Scope (\_SB.PCI0) Scope (\_SB.PCI0)
{ {
Device (ISP) Device (ISP)
{ {
Name (_DSD, Package () { Name (_DSD, Package () {
ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
Package () { Package () {
Package () { "port@4", PRT4 }, Package () { "port@4", PRT4 },
} }
}) })
Name (PRT4, Package() { Name (PRT4, Package() {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () { Package () {
Package () { "reg", 4 }, /* CSI-2 port number */ Package () { "reg", 4 }, /* CSI-2 port number */
}, },
ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
Package () { Package () {
Package () { "endpoint@0", EP40 }, Package () { "endpoint@0", EP40 },
} }
}) })
Name (EP40, Package() { Name (EP40, Package() {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () { Package () {
Package () { "reg", 0 }, Package () { "reg", 0 },
Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@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 Here, the port 0 of the "CAM0" device is connected to the port 4 of
...@@ -148,27 +151,27 @@ the "ISP" device and vice versa. ...@@ -148,27 +151,27 @@ the "ISP" device and vice versa.
References References
---------- ==========
[1] _DSD (Device Specific Data) Implementation Guide. [1] _DSD (Device Specific Data) Implementation Guide.
<URL:http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm>, http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm,
referenced 2016-10-03. referenced 2016-10-03.
[2] Devicetree. <URL:http://www.devicetree.org>, referenced 2016-10-03. [2] Devicetree. http://www.devicetree.org, referenced 2016-10-03.
[3] Documentation/devicetree/bindings/graph.txt [3] Documentation/devicetree/bindings/graph.txt
[4] Device Properties UUID For _DSD. [4] Device Properties UUID For _DSD.
<URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf,
referenced 2016-10-04. referenced 2016-10-04.
[5] Hierarchical Data Extension UUID For _DSD. [5] Hierarchical Data Extension UUID For _DSD.
<URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf,
referenced 2016-10-04. referenced 2016-10-04.
[6] Advanced Configuration and Power Interface Specification. [6] Advanced Configuration and Power Interface Specification.
<URL:http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf>, http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf,
referenced 2016-10-04. referenced 2016-10-04.
[7] _DSD Device Properties Usage Rules. [7] _DSD Device Properties Usage Rules.
Documentation/acpi/DSD-properties-rules.txt :doc:`../DSD-properties-rules`
Documentation/acpi/gpio-properties.txt → Documentation/firmware-guide/acpi/gpio-properties.rst
View file @ 10b4768b
.. SPDX-License-Identifier: GPL-2.0
======================================
_DSD Device Properties Related to GPIO _DSD Device Properties Related to GPIO
-------------------------------------- ======================================
With the release of ACPI 5.1, the _DSD configuration object finally 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 allows names to be given to GPIOs (and other things as well) returned
...@@ -8,7 +11,7 @@ the corresponding GPIO, which is pretty error prone (it depends on ...@@ -8,7 +11,7 @@ the corresponding GPIO, which is pretty error prone (it depends on
the _CRS output ordering, for example). the _CRS output ordering, for example).
With _DSD we can now query GPIOs using a name instead of an integer With _DSD we can now query GPIOs using a name instead of an integer
index, like the ASL example below shows: index, like the ASL example below shows::
// Bluetooth device with reset and shutdown GPIOs // Bluetooth device with reset and shutdown GPIOs
Device (BTH) Device (BTH)
...@@ -34,15 +37,19 @@ index, like the ASL example below shows: ...@@ -34,15 +37,19 @@ index, like the ASL example below shows:
}) })
} }
The format of the supported GPIO property is: The format of the supported GPIO property is::
Package () { "name", Package () { ref, index, pin, active_low }} Package () { "name", Package () { ref, index, pin, active_low }}
ref - The device that has _CRS containing GpioIo()/GpioInt() resources, ref
typically this is the device itself (BTH in our case). The device that has _CRS containing GpioIo()/GpioInt() resources,
index - Index of the GpioIo()/GpioInt() resource in _CRS starting from zero. typically this is the device itself (BTH in our case).
pin - Pin in the GpioIo()/GpioInt() resource. Typically this is zero. index
active_low - If 1 the GPIO is marked as active_low. 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 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 active low or high, the "active_low" argument can be used here. Setting
...@@ -55,7 +62,7 @@ It is possible to leave holes in the array of GPIOs. This is useful in ...@@ -55,7 +62,7 @@ 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 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 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 controller can have chip selects 0 and 2 implemented as GPIOs and 1 as
native: native::
Package () { Package () {
"cs-gpios", "cs-gpios",
...@@ -67,7 +74,7 @@ native: ...@@ -67,7 +74,7 @@ native:
} }
Other supported properties Other supported properties
-------------------------- ==========================
Following Device Tree compatible device properties are also supported by Following Device Tree compatible device properties are also supported by
_DSD device properties for GPIO controllers: _DSD device properties for GPIO controllers:
...@@ -78,7 +85,7 @@ _DSD device properties for GPIO controllers: ...@@ -78,7 +85,7 @@ _DSD device properties for GPIO controllers:
- input - input
- line-name - line-name
Example: Example::
Name (_DSD, Package () { Name (_DSD, Package () {
// _DSD Hierarchical Properties Extension UUID // _DSD Hierarchical Properties Extension UUID
...@@ -100,7 +107,7 @@ Example: ...@@ -100,7 +107,7 @@ Example:
- gpio-line-names - gpio-line-names
Example: Example::
Package () { Package () {
"gpio-line-names", "gpio-line-names",
...@@ -114,7 +121,7 @@ See Documentation/devicetree/bindings/gpio/gpio.txt for more information ...@@ -114,7 +121,7 @@ See Documentation/devicetree/bindings/gpio/gpio.txt for more information
about these properties. about these properties.
ACPI GPIO Mappings Provided by Drivers ACPI GPIO Mappings Provided by Drivers
-------------------------------------- ======================================
There are systems in which the ACPI tables do not contain _DSD but provide _CRS 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 with GpioIo()/GpioInt() resources and device drivers still need to work with
...@@ -139,16 +146,16 @@ line in that resource starting from zero, and the active-low flag for that line, ...@@ -139,16 +146,16 @@ 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. respectively, in analogy with the _DSD GPIO property format specified above.
For the example Bluetooth device discussed previously the data structures in For the example Bluetooth device discussed previously the data structures in
question would look like this: question would look like this::
static const struct acpi_gpio_params reset_gpio = { 1, 1, false }; 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_params shutdown_gpio = { 0, 0, false };
static const struct acpi_gpio_mapping bluetooth_acpi_gpios[] = { static const struct acpi_gpio_mapping bluetooth_acpi_gpios[] = {
{ "reset-gpios", &reset_gpio, 1 }, { "reset-gpios", &reset_gpio, 1 },
{ "shutdown-gpios", &shutdown_gpio, 1 }, { "shutdown-gpios", &shutdown_gpio, 1 },
{ }, { },
}; };
Next, the mapping table needs to be passed as the second argument to 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 acpi_dev_add_driver_gpios() that will register it with the ACPI device object
...@@ -158,12 +165,12 @@ calling acpi_dev_remove_driver_gpios() on the ACPI device object where that ...@@ -158,12 +165,12 @@ calling acpi_dev_remove_driver_gpios() on the ACPI device object where that
table was previously registered. table was previously registered.
Using the _CRS fallback Using the _CRS fallback
----------------------- =======================
If a device does not have _DSD or the driver does not create ACPI GPIO 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 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 because the driver does not know what it actually gets. For example if we
have a device like below: have a device like below::
Device (BTH) Device (BTH)
{ {
...@@ -177,7 +184,7 @@ have a device like below: ...@@ -177,7 +184,7 @@ have a device like below:
}) })
} }
The driver might expect to get the right GPIO when it does: The driver might expect to get the right GPIO when it does::
desc = gpiod_get(dev, "reset", GPIOD_OUT_LOW); desc = gpiod_get(dev, "reset", GPIOD_OUT_LOW);
...@@ -193,22 +200,25 @@ the ACPI GPIO mapping tables are hardly linked to ACPI ID and certain ...@@ -193,22 +200,25 @@ 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. objects, as listed in the above chapter, of the device in question.
Getting GPIO descriptor Getting GPIO descriptor
----------------------- =======================
There are two main approaches to get GPIO resource from ACPI::
There are two main approaches to get GPIO resource from ACPI: desc = gpiod_get(dev, connection_id, flags);
desc = gpiod_get(dev, connection_id, flags); desc = gpiod_get_index(dev, connection_id, index, flags);
desc = gpiod_get_index(dev, connection_id, index, flags);
We may consider two different cases here, i.e. when connection ID is We may consider two different cases here, i.e. when connection ID is
provided and otherwise. provided and otherwise.
Case 1: Case 1::
desc = gpiod_get(dev, "non-null-connection-id", flags);
desc = gpiod_get_index(dev, "non-null-connection-id", index, flags); desc = gpiod_get(dev, "non-null-connection-id", flags);
desc = gpiod_get_index(dev, "non-null-connection-id", index, flags);
Case 2::
Case 2: desc = gpiod_get(dev, NULL, flags);
desc = gpiod_get(dev, NULL, flags); desc = gpiod_get_index(dev, NULL, index, flags);
desc = gpiod_get_index(dev, NULL, index, flags);
Case 1 assumes that corresponding ACPI device description must have Case 1 assumes that corresponding ACPI device description must have
defined device properties and will prevent to getting any GPIO resources defined device properties and will prevent to getting any GPIO resources
......
Documentation/firmware-guide/acpi/i2c-muxes.rst 0 → 100644
View file @ 10b4768b
.. 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,,)
}
}
}
}
}
Documentation/firmware-guide/acpi/index.rst 0 → 100644
View file @ 10b4768b
.. SPDX-License-Identifier: GPL-2.0
============
ACPI Support
============
.. toctree::
:maxdepth: 1
namespace
dsd/graph
dsd/data-node-references
enumeration
osi
method-customizing
method-tracing
DSD-properties-rules
debug
aml-debugger
apei/output_format
apei/einj
gpio-properties
i2c-muxes
acpi-lid
lpit
video_extension
Documentation/acpi/lpit.txt → Documentation/firmware-guide/acpi/lpit.rst
View file @ 10b4768b
.. SPDX-License-Identifier: GPL-2.0
===========================
Low Power Idle Table (LPIT)
===========================
To enumerate platform Low Power Idle states, Intel platforms are using To enumerate platform Low Power Idle states, Intel platforms are using
“Low Power Idle Table” (LPIT). More details about this table can be “Low Power Idle Table” (LPIT). More details about this table can be
downloaded from: downloaded from:
...@@ -8,13 +14,15 @@ Residencies for each low power state can be read via FFH ...@@ -8,13 +14,15 @@ Residencies for each low power state can be read via FFH
On platforms supporting S0ix sleep states, there can be two types of On platforms supporting S0ix sleep states, there can be two types of
residencies: residencies:
- CPU PKG C10 (Read via FFH interface)
- Platform Controller Hub (PCH) SLP_S0 (Read via memory mapped interface) - 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 The following attributes are added dynamically to the cpuidle
sysfs attribute group: 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 /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 The "low_power_idle_cpu_residency_us" attribute shows time spent
by the CPU package in PKG C10 by the CPU package in PKG C10
......
Documentation/firmware-guide/acpi/method-customizing.rst 0 → 100644
View file @ 10b4768b
.. SPDX-License-Identifier: GPL-2.0
=======================================
Linux ACPI Custom Control Method How To
=======================================
:Author: 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.
- 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).
Documentation/firmware-guide/acpi/method-tracing.rst 0 → 100644
View file @ 10b4768b
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
=====================
ACPICA Trace Facility
=====================
:Copyright: |copy| 2015, Intel Corporation
:Author: Lv Zheng <lv.zheng@intel.com>
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.
Documentation/acpi/osi.txt → Documentation/firmware-guide/acpi/osi.rst
View file @ 10b4768b
.. SPDX-License-Identifier: GPL-2.0
==========================
ACPI _OSI and _REV methods ACPI _OSI and _REV methods
-------------------------- ==========================
An ACPI BIOS can use the "Operating System Interfaces" method (_OSI) An ACPI BIOS can use the "Operating System Interfaces" method (_OSI)
to find out what the operating system supports. Eg. If BIOS to find out what the operating system supports. Eg. If BIOS
...@@ -14,7 +17,7 @@ This document explains how and why the BIOS and Linux should use these methods. ...@@ -14,7 +17,7 @@ This document explains how and why the BIOS and Linux should use these methods.
It also explains how and why they are widely misused. It also explains how and why they are widely misused.
How to use _OSI How to use _OSI
--------------- ===============
Linux runs on two groups of machines -- those that are tested by the OEM 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, to be compatible with Linux, and those that were never tested with Linux,
...@@ -62,7 +65,7 @@ the string when that support is added to the kernel. ...@@ -62,7 +65,7 @@ the string when that support is added to the kernel.
That was easy. Read on, to find out how to do it wrong. That was easy. Read on, to find out how to do it wrong.
Before _OSI, there was _OS Before _OSI, there was _OS
-------------------------- ==========================
ACPI 1.0 specified "_OS" as an ACPI 1.0 specified "_OS" as an
"object that evaluates to a string that identifies the operating system." "object that evaluates to a string that identifies the operating system."
...@@ -96,7 +99,7 @@ That is the *only* viable strategy, as that is what modern Windows does, ...@@ -96,7 +99,7 @@ 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. and so doing otherwise could steer the BIOS down an untested path.
_OSI is born, and immediately misused _OSI is born, and immediately misused
-------------------------------------- =====================================
With _OSI, the *BIOS* provides the string describing an interface, With _OSI, the *BIOS* provides the string describing an interface,
and asks the OS: "YES/NO, are you compatible with this interface?" and asks the OS: "YES/NO, are you compatible with this interface?"
...@@ -144,7 +147,7 @@ catastrophic failure resulting from the BIOS taking paths that ...@@ -144,7 +147,7 @@ catastrophic failure resulting from the BIOS taking paths that
were never validated under *any* OS. were never validated under *any* OS.
Do not use _REV Do not use _REV
--------------- ===============
Since _OSI("Linux") went away, some BIOS writers used _REV Since _OSI("Linux") went away, some BIOS writers used _REV
to support Linux and Windows differences in the same BIOS. to support Linux and Windows differences in the same BIOS.
...@@ -164,7 +167,7 @@ from mid-2015 onward. The ACPI specification will also be updated ...@@ -164,7 +167,7 @@ from mid-2015 onward. The ACPI specification will also be updated
to reflect that _REV is deprecated, and always returns 2. to reflect that _REV is deprecated, and always returns 2.
Apple Mac and _OSI("Darwin") Apple Mac and _OSI("Darwin")
---------------------------- ============================
On Apple's Mac platforms, the ACPI BIOS invokes _OSI("Darwin") On Apple's Mac platforms, the ACPI BIOS invokes _OSI("Darwin")
to determine if the machine is running Apple OSX. to determine if the machine is running Apple OSX.
......
Documentation/acpi/video_extension.txt → Documentation/firmware-guide/acpi/video_extension.rst
View file @ 10b4768b
.. SPDX-License-Identifier: GPL-2.0
=====================
ACPI video extensions ACPI video extensions
~~~~~~~~~~~~~~~~~~~~~ =====================
This driver implement the ACPI Extensions For Display Adapters for This driver implement the ACPI Extensions For Display Adapters for
integrated graphics devices on motherboard, as specified in ACPI 2.0 integrated graphics devices on motherboard, as specified in ACPI 2.0
...@@ -8,9 +11,10 @@ defining the video POST device, retrieving EDID information or to ...@@ -8,9 +11,10 @@ defining the video POST device, retrieving EDID information or to
setup a video output, etc. Note that this is an ref. implementation setup a video output, etc. Note that this is an ref. implementation
only. It may or may not work for your integrated video device. only. It may or may not work for your integrated video device.
The ACPI video driver does 3 things regarding backlight control: The ACPI video driver does 3 things regarding backlight control.
1 Export a sysfs interface for user space to control backlight level Export a sysfs interface for user space to control backlight level
==================================================================
If the ACPI table has a video device, and acpi_backlight=vendor kernel 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 command line is not present, the driver will register a backlight device
...@@ -22,36 +26,41 @@ The backlight sysfs interface has a standard definition here: ...@@ -22,36 +26,41 @@ The backlight sysfs interface has a standard definition here:
Documentation/ABI/stable/sysfs-class-backlight. Documentation/ABI/stable/sysfs-class-backlight.
And what ACPI video driver does is: 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; actual_brightness:
bl_power: not implemented, will set the current brightness instead; on read, control method _BQC will be evaluated to
brightness: on write, control method _BCM will run to set the requested get the brightness level the firmware thinks it is at;
brightness level; bl_power:
max_brightness: Derived from the _BCL package(see below); not implemented, will set the current brightness instead;
type: firmware 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 Note that ACPI video backlight driver will always use index for
brightness, actual_brightness and max_brightness. So if we have brightness, actual_brightness and max_brightness. So if we have
the following _BCL package: the following _BCL package::
Method (_BCL, 0, NotSerialized) Method (_BCL, 0, NotSerialized)
{
Return (Package (0x0C)
{ {
0x64, Return (Package (0x0C)
0x32, {
0x0A, 0x64,
0x14, 0x32,
0x1E, 0x0A,
0x28, 0x14,
0x32, 0x1E,
0x3C, 0x28,
0x46, 0x32,
0x50, 0x3C,
0x5A, 0x46,
0x64 0x50,
}) 0x5A,
} 0x64
})
}
The first two levels are for when laptop are on AC or on battery and are 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 not used by Linux currently. The remaining 10 levels are supported levels
...@@ -62,13 +71,15 @@ as a "brightness level" indicator. Thus from the user space perspective ...@@ -62,13 +71,15 @@ as a "brightness level" indicator. Thus from the user space perspective
the range of available brightness levels is from 0 to 9 (max_brightness) the range of available brightness levels is from 0 to 9 (max_brightness)
inclusive. inclusive.
2 Notify user space about hotkey event Notify user space about hotkey event
====================================
There are generally two cases for hotkey event reporting: There are generally two cases for hotkey event reporting:
i) For some laptops, when user presses the hotkey, a scancode will be 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 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 the keyboard driver as a key type input event, with proper remap, the
following key code will appear to user space: following key code will appear to user space::
EV_KEY, KEY_BRIGHTNESSUP EV_KEY, KEY_BRIGHTNESSUP
EV_KEY, KEY_BRIGHTNESSDOWN EV_KEY, KEY_BRIGHTNESSDOWN
...@@ -84,23 +95,27 @@ ii) For some laptops, the press of the hotkey will not generate the ...@@ -84,23 +95,27 @@ ii) For some laptops, the press of the hotkey will not generate the
notify value it received and send the event to user space through the notify value it received and send the event to user space through the
input device it created: input device it created:
===== ==================
event keycode event keycode
===== ==================
0x86 KEY_BRIGHTNESSUP 0x86 KEY_BRIGHTNESSUP
0x87 KEY_BRIGHTNESSDOWN 0x87 KEY_BRIGHTNESSDOWN
etc. etc.
===== ==================
so this would lead to the same effect as case i) now. so this would lead to the same effect as case i) now.
Once user space tool receives this event, it can modify the backlight Once user space tool receives this event, it can modify the backlight
level through the sysfs interface. level through the sysfs interface.
3 Change backlight level in the kernel Change backlight level in the kernel
====================================
This works for machines covered by case ii) in Section 2. Once the driver 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 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 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 space regardless of whether or not the video module controls the backlight level
directly. This behaviour can be controlled through the brightness_switch_enabled 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 module parameter as documented in admin-guide/kernel-parameters.rst. It is
disable this behaviour once a GUI environment starts up and wants to have full recommended to disable this behaviour once a GUI environment starts up and
control of the backlight level. wants to have full control of the backlight level.
Documentation/firmware-guide/index.rst 0 → 100644
View file @ 10b4768b
.. SPDX-License-Identifier: GPL-2.0
===============================
The Linux kernel firmware guide
===============================
This section describes the ACPI subsystem in Linux from firmware perspective.
.. toctree::
:maxdepth: 1
acpi/index
Documentation/index.rst
View file @ 10b4768b
...@@ -35,6 +35,16 @@ trying to get it to work optimally on a given system. ...@@ -35,6 +35,16 @@ trying to get it to work optimally on a given system.
admin-guide/index admin-guide/index
Firmware-related documentation
------------------------------
The following holds information on the kernel's expectations regarding the
platform firmwares.
.. toctree::
:maxdepth: 2
firmware-guide/index
Application-developer documentation Application-developer documentation
----------------------------------- -----------------------------------
......
MAINTAINERS
View file @ 10b4768b
...@@ -6594,7 +6594,7 @@ M: Andy Shevchenko <andriy.shevchenko@linux.intel.com> ...@@ -6594,7 +6594,7 @@ M: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
L: linux-gpio@vger.kernel.org L: linux-gpio@vger.kernel.org
L: linux-acpi@vger.kernel.org L: linux-acpi@vger.kernel.org
S: Maintained S: Maintained
F: Documentation/acpi/gpio-properties.txt F: Documentation/firmware-guide/acpi/gpio-properties.rst
F: drivers/gpio/gpiolib-acpi.c F: drivers/gpio/gpiolib-acpi.c
GPIO IR Transmitter GPIO IR Transmitter
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7