mirror of
https://github.com/linux-msm/laptops-kernel.git
synced 2026-08-13 14:19:53 -07:00
Merge tag 'acpi-5.2-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm
Pull ACPI updates from Rafael Wysocki:
"These rearrange the ACPI documentation by converting it to the .rst
format and splitting it into clear categories (admin guide, driver
API, firmware guide), switch over multiple users of a problematic
library function to a new better one, update the ACPICA code in the
kernel to a new upstream release, fix a few issues, improve power
device management diagnostics and do some cleanups.
Specifics:
- Convert the ACPI documentation in the kernel source tree to the
.rst format and split it into the admin guide, driver API and
firmware guide parts (Changbin Du).
- Add a PRP0001 usage example to the ACPI documentation (Thomas
Preston).
- Switch over the users of the acpi_dev_get_first_match_name()
library function which turned out to be problematic to a new,
better one called acpi_dev_get_first_match_dev() (Andy Shevchenko,
YueHaibing).
- Update the ACPICA code in the kernel to upstream release 20190405
including:
* Null pointer dereference check in acpi_ns_delete_node() (Erik
Schmauss).
* Multiple macro and function name changes (Bob Moore).
* Predefined operation region name fix (Erik Schmauss).
- Fix hibernation issue on systems using the Baytrail and Cherrytrail
Intel SoCs introduced during the 4.20 development cycle (Hans de
Goede).
- Add Sony VPCEH3U1E to the backlight quirk list (Zhang Rui).
- Fix button handling during system resume (Zhang Rui).
- Add a device PM diagnostic message (Rafael Wysocki).
- Clean up the code, comments and white space in multiple places
(Bjorn Helgaas, Gustavo Silva, Kefeng Wang)"
* tag 'acpi-5.2-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm: (53 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
...
This commit is contained in:
Linus Torvalds
@@ -1,66 +0,0 @@
|
||||
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"
|
||||
@@ -1,147 +0,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.
|
||||
@@ -1,58 +0,0 @@
|
||||
ACPI I2C Muxes
|
||||
--------------
|
||||
|
||||
Describing an I2C device hierarchy that includes I2C muxes requires an ACPI
|
||||
Device () scope per mux channel.
|
||||
|
||||
Consider this topology:
|
||||
|
||||
+------+ +------+
|
||||
| SMB1 |-->| MUX0 |--CH00--> i2c client A (0x50)
|
||||
| | | 0x70 |--CH01--> i2c client B (0x50)
|
||||
+------+ +------+
|
||||
|
||||
which corresponds to the following ASL:
|
||||
|
||||
Device (SMB1)
|
||||
{
|
||||
Name (_HID, ...)
|
||||
Device (MUX0)
|
||||
{
|
||||
Name (_HID, ...)
|
||||
Name (_CRS, ResourceTemplate () {
|
||||
I2cSerialBus (0x70, ControllerInitiated, I2C_SPEED,
|
||||
AddressingMode7Bit, "^SMB1", 0x00,
|
||||
ResourceConsumer,,)
|
||||
}
|
||||
|
||||
Device (CH00)
|
||||
{
|
||||
Name (_ADR, 0)
|
||||
|
||||
Device (CLIA)
|
||||
{
|
||||
Name (_HID, ...)
|
||||
Name (_CRS, ResourceTemplate () {
|
||||
I2cSerialBus (0x50, ControllerInitiated, I2C_SPEED,
|
||||
AddressingMode7Bit, "^CH00", 0x00,
|
||||
ResourceConsumer,,)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Device (CH01)
|
||||
{
|
||||
Name (_ADR, 1)
|
||||
|
||||
Device (CLIB)
|
||||
{
|
||||
Name (_HID, ...)
|
||||
Name (_CRS, ResourceTemplate () {
|
||||
I2cSerialBus (0x50, ControllerInitiated, I2C_SPEED,
|
||||
AddressingMode7Bit, "^CH01", 0x00,
|
||||
ResourceConsumer,,)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,111 +0,0 @@
|
||||
Upgrading ACPI tables via initrd
|
||||
================================
|
||||
|
||||
1) Introduction (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
|
||||
upgrade the ACPI execution environment that is defined by the ACPI tables
|
||||
via upgrading the ACPI tables provided by the BIOS with an instrumented,
|
||||
modified, more recent version one, or installing brand new ACPI tables.
|
||||
|
||||
When building initrd with kernel in a single image, option
|
||||
ACPI_TABLE_OVERRIDE_VIA_BUILTIN_INITRD should also be true for this
|
||||
feature to work.
|
||||
|
||||
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
|
||||
drivers/acpi/tables.c.
|
||||
All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should
|
||||
be overridable, except:
|
||||
- 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.
|
||||
|
||||
|
||||
2) What is this for
|
||||
-------------------
|
||||
|
||||
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
|
||||
allows you to upgrade the buggy tables before your platform/BIOS vendor
|
||||
releases an upgraded BIOS binary.
|
||||
|
||||
This facility can be used by platform/BIOS vendors to provide a Linux
|
||||
compatible environment without modifying the underlying platform firmware.
|
||||
|
||||
This facility also provides a powerful feature to easily debug and test
|
||||
ACPI BIOS table compatibility with the Linux kernel by modifying old
|
||||
platform provided ACPI tables or inserting new ACPI tables.
|
||||
|
||||
It can and should be enabled in any kernel because there is no functional
|
||||
change with not instrumented initrds.
|
||||
|
||||
|
||||
3) How does it work
|
||||
-------------------
|
||||
|
||||
# Extract the machine's ACPI tables:
|
||||
cd /tmp
|
||||
acpidump >acpidump
|
||||
acpixtract -a acpidump
|
||||
# Disassemble, modify and recompile them:
|
||||
iasl -d *.dat
|
||||
# For example add this statement into a _PRT (PCI Routing Table) function
|
||||
# of the DSDT:
|
||||
Store("HELLO WORLD", debug)
|
||||
# And increase the OEM Revision. For example, before modification:
|
||||
DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000000)
|
||||
# After modification:
|
||||
DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000001)
|
||||
iasl -sa dsdt.dsl
|
||||
# Add the raw ACPI tables to an uncompressed cpio archive.
|
||||
# They must be put into a /kernel/firmware/acpi directory inside the cpio
|
||||
# archive. Note that if the table put here matches a platform table
|
||||
# (similar Table Signature, and similar OEMID, and similar OEM Table ID)
|
||||
# with a more recent OEM Revision, the platform table will be upgraded by
|
||||
# this table. If the table put here doesn't match a platform table
|
||||
# (dissimilar Table Signature, or dissimilar OEMID, or dissimilar OEM Table
|
||||
# ID), this table will be appended.
|
||||
mkdir -p kernel/firmware/acpi
|
||||
cp dsdt.aml kernel/firmware/acpi
|
||||
# A maximum of "NR_ACPI_INITRD_TABLES (64)" tables are currently allowed
|
||||
# (see osl.c):
|
||||
iasl -sa facp.dsl
|
||||
iasl -sa ssdt1.dsl
|
||||
cp facp.aml kernel/firmware/acpi
|
||||
cp ssdt1.aml kernel/firmware/acpi
|
||||
# The uncompressed cpio archive must be the first. Other, typically
|
||||
# compressed cpio archives, must be concatenated on top of the uncompressed
|
||||
# one. Following command creates the uncompressed cpio archive and
|
||||
# concatenates the original initrd on top:
|
||||
find kernel | cpio -H newc --create > /boot/instrumented_initrd
|
||||
cat /boot/initrd >>/boot/instrumented_initrd
|
||||
# reboot with increased acpi debug level, e.g. boot params:
|
||||
acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF
|
||||
# and check your syslog:
|
||||
[ 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,
|
||||
also static ACPI tables.
|
||||
|
||||
|
||||
4) Where to retrieve userspace tools
|
||||
------------------------------------
|
||||
|
||||
iasl and acpixtract are part of Intel's ACPICA project:
|
||||
http://acpica.org/
|
||||
and should be packaged by distributions (for example in the acpica package
|
||||
on SUSE).
|
||||
|
||||
acpidump can be found in Len Browns pmtools:
|
||||
ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump
|
||||
This tool is also part of the acpica package on SUSE.
|
||||
Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels:
|
||||
/sys/firmware/acpi/tables
|
||||
@@ -1,73 +0,0 @@
|
||||
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).
|
||||
@@ -1,192 +0,0 @@
|
||||
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.
|
||||
@@ -1,172 +0,0 @@
|
||||
|
||||
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
|
||||
image. A common example is connecting sensors on I2C / SPI buses on development
|
||||
boards.
|
||||
|
||||
Although this can be accomplished by creating a kernel platform driver or
|
||||
recompiling the firmware image with updated ACPI tables, neither is practical:
|
||||
the former proliferates board specific kernel code while the latter requires
|
||||
access to firmware tools which are often not publicly available.
|
||||
|
||||
Because ACPI supports external references in AML code a more practical
|
||||
way to augment firmware ACPI configuration is by dynamically loading
|
||||
user defined SSDT tables that contain the board specific information.
|
||||
|
||||
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
|
||||
following ASL code can be used:
|
||||
|
||||
DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003)
|
||||
{
|
||||
External (\_SB.I2C6, DeviceObj)
|
||||
|
||||
Scope (\_SB.I2C6)
|
||||
{
|
||||
Device (STAC)
|
||||
{
|
||||
Name (_ADR, Zero)
|
||||
Name (_HID, "BMA222E")
|
||||
|
||||
Method (_CRS, 0, Serialized)
|
||||
{
|
||||
Name (RBUF, ResourceTemplate ()
|
||||
{
|
||||
I2cSerialBus (0x0018, ControllerInitiated, 0x00061A80,
|
||||
AddressingMode7Bit, "\\_SB.I2C6", 0x00,
|
||||
ResourceConsumer, ,)
|
||||
GpioInt (Edge, ActiveHigh, Exclusive, PullDown, 0x0000,
|
||||
"\\_SB.GPO2", 0x00, ResourceConsumer, , )
|
||||
{ // Pin list
|
||||
0
|
||||
}
|
||||
})
|
||||
Return (RBUF)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
which can then be compiled to AML binary format:
|
||||
|
||||
$ iasl minnowmax.asl
|
||||
|
||||
Intel ACPI Component Architecture
|
||||
ASL Optimizing Compiler version 20140214-64 [Mar 29 2014]
|
||||
Copyright (c) 2000 - 2014 Intel Corporation
|
||||
|
||||
ASL Input: minnomax.asl - 30 lines, 614 bytes, 7 keywords
|
||||
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
|
||||
|
||||
The resulting AML code can then be loaded by the kernel using one of the methods
|
||||
below.
|
||||
|
||||
== Loading ACPI SSDTs from initrd ==
|
||||
|
||||
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.
|
||||
|
||||
It works in a similar way with initrd based ACPI tables override/upgrade: SSDT
|
||||
aml code must be placed in the first, uncompressed, initrd under the
|
||||
"kernel/firmware/acpi" path. Multiple files can be used and this will translate
|
||||
in loading multiple tables. Only SSDT and OEM tables are allowed. See
|
||||
initrd_table_override.txt for more details.
|
||||
|
||||
Here is an example:
|
||||
|
||||
# Add the raw ACPI tables to an uncompressed cpio archive.
|
||||
# They must be put into a /kernel/firmware/acpi directory inside the
|
||||
# cpio archive.
|
||||
# The uncompressed cpio archive must be the first.
|
||||
# Other, typically compressed cpio archives, must be
|
||||
# concatenated on top of the uncompressed one.
|
||||
mkdir -p kernel/firmware/acpi
|
||||
cp ssdt.aml kernel/firmware/acpi
|
||||
|
||||
# Create the uncompressed cpio archive and concatenate the original initrd
|
||||
# on top:
|
||||
find kernel | cpio -H newc --create > /boot/instrumented_initrd
|
||||
cat /boot/initrd >>/boot/instrumented_initrd
|
||||
|
||||
== Loading ACPI SSDTs from EFI variables ==
|
||||
|
||||
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
|
||||
is also work underway to implement EFI support for loading user defined SSDTs
|
||||
and using this method will make it easier to convert to the EFI loading
|
||||
mechanism when that will arrive.
|
||||
|
||||
In order to load SSDTs from an EFI variable the efivar_ssdt kernel command line
|
||||
parameter can be used. The argument for the option is the variable name to
|
||||
use. If there are multiple variables with the same name but with different
|
||||
vendor GUIDs, all of them will be loaded.
|
||||
|
||||
In order to store the AML code in an EFI variable the efivarfs filesystem can be
|
||||
used. It is enabled and mounted by default in /sys/firmware/efi/efivars in all
|
||||
recent distribution.
|
||||
|
||||
Creating a new file in /sys/firmware/efi/efivars will automatically create a new
|
||||
EFI variable. Updating a file in /sys/firmware/efi/efivars will update the EFI
|
||||
variable. Please note that the file name needs to be specially formatted as
|
||||
"Name-GUID" and that the first 4 bytes in the file (little-endian format)
|
||||
represent the attributes of the EFI variable (see EFI_VARIABLE_MASK in
|
||||
include/linux/efi.h). Writing to the file must also be done with one write
|
||||
operation.
|
||||
|
||||
For example, you can use the following bash script to create/update an EFI
|
||||
variable with the content from a given file:
|
||||
|
||||
#!/bin/sh -e
|
||||
|
||||
while ! [ -z "$1" ]; do
|
||||
case "$1" in
|
||||
"-f") filename="$2"; shift;;
|
||||
"-g") guid="$2"; shift;;
|
||||
*) name="$1";;
|
||||
esac
|
||||
shift
|
||||
done
|
||||
|
||||
usage()
|
||||
{
|
||||
echo "Syntax: ${0##*/} -f filename [ -g guid ] name"
|
||||
exit 1
|
||||
}
|
||||
|
||||
[ -n "$name" -a -f "$filename" ] || usage
|
||||
|
||||
EFIVARFS="/sys/firmware/efi/efivars"
|
||||
|
||||
[ -d "$EFIVARFS" ] || exit 2
|
||||
|
||||
if stat -tf $EFIVARFS | grep -q -v de5e81e4; then
|
||||
mount -t efivarfs none $EFIVARFS
|
||||
fi
|
||||
|
||||
# try to pick up an existing GUID
|
||||
[ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-)
|
||||
|
||||
# use a randomly generated GUID
|
||||
[ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)"
|
||||
|
||||
# efivarfs expects all of the data in one write
|
||||
tmp=$(mktemp)
|
||||
/bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp
|
||||
dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp)
|
||||
rm $tmp
|
||||
|
||||
== Loading ACPI SSDTs from 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
|
||||
mounted. In the following examples, we assume that configfs has been mounted in
|
||||
/config.
|
||||
|
||||
New tables can be loading by creating new directories in /config/acpi/table/ and
|
||||
writing the SSDT aml code in the aml attribute:
|
||||
|
||||
cd /config/acpi/table
|
||||
mkdir my_ssdt
|
||||
cat ~/ssdt.aml > my_ssdt/aml
|
||||
@@ -1,5 +1,11 @@
|
||||
.. 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
|
||||
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:
|
||||
|
||||
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/
|
||||
/sys/devices/system/cpu/cpuX/acpi_cppc/
|
||||
|
||||
for each cpu X
|
||||
for each cpu X::
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
$ 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
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
$ 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).
|
||||
* 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
|
||||
power savings (abstract scale).
|
||||
* lowest_perf : Lowest performance of this processor (abstract scale).
|
||||
@@ -48,22 +51,26 @@ total 0
|
||||
* feedback_ctrs : Includes both Reference and delivered performance counter.
|
||||
Reference counter ticks up proportional to processor's reference 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
|
||||
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.
|
||||
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
|
||||
T2: Read feedback_ctrs as fbc_t2
|
||||
T1: Read feedback_ctrs as fbc_t1
|
||||
Wait or run some workload
|
||||
|
||||
delivered_counter_delta = fbc_t2[del] - fbc_t1[del]
|
||||
reference_counter_delta = fbc_t2[ref] - fbc_t1[ref]
|
||||
T2: Read feedback_ctrs as fbc_t2
|
||||
|
||||
delivered_perf = (refernce_perf x delivered_counter_delta) / reference_counter_delta
|
||||
::
|
||||
|
||||
delivered_counter_delta = fbc_t2[del] - fbc_t1[del]
|
||||
reference_counter_delta = fbc_t2[ref] - fbc_t1[ref]
|
||||
|
||||
delivered_perf = (refernce_perf x delivered_counter_delta) / reference_counter_delta
|
||||
+7
-1
@@ -1,6 +1,12 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
===============
|
||||
Overriding 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
|
||||
Linux/ACPI home page:
|
||||
@@ -0,0 +1,14 @@
|
||||
============
|
||||
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
|
||||
@@ -0,0 +1,115 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
================================
|
||||
Upgrading ACPI tables via initrd
|
||||
================================
|
||||
|
||||
What is this about
|
||||
==================
|
||||
|
||||
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
|
||||
via upgrading the ACPI tables provided by the BIOS with an instrumented,
|
||||
modified, more recent version one, or installing brand new ACPI tables.
|
||||
|
||||
When building initrd with kernel in a single image, option
|
||||
ACPI_TABLE_OVERRIDE_VIA_BUILTIN_INITRD should also be true for this
|
||||
feature to work.
|
||||
|
||||
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
|
||||
drivers/acpi/tables.c.
|
||||
|
||||
All ACPI tables iasl (Intel's ACPI compiler and disassembler) knows should
|
||||
be overridable, except:
|
||||
|
||||
- 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.
|
||||
|
||||
|
||||
What is this for
|
||||
================
|
||||
|
||||
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
|
||||
allows you to upgrade the buggy tables before your platform/BIOS vendor
|
||||
releases an upgraded BIOS binary.
|
||||
|
||||
This facility can be used by platform/BIOS vendors to provide a Linux
|
||||
compatible environment without modifying the underlying platform firmware.
|
||||
|
||||
This facility also provides a powerful feature to easily debug and test
|
||||
ACPI BIOS table compatibility with the Linux kernel by modifying old
|
||||
platform provided ACPI tables or inserting new ACPI tables.
|
||||
|
||||
It can and should be enabled in any kernel because there is no functional
|
||||
change with not instrumented initrds.
|
||||
|
||||
|
||||
How does it work
|
||||
================
|
||||
::
|
||||
|
||||
# Extract the machine's ACPI tables:
|
||||
cd /tmp
|
||||
acpidump >acpidump
|
||||
acpixtract -a acpidump
|
||||
# Disassemble, modify and recompile them:
|
||||
iasl -d *.dat
|
||||
# For example add this statement into a _PRT (PCI Routing Table) function
|
||||
# of the DSDT:
|
||||
Store("HELLO WORLD", debug)
|
||||
# And increase the OEM Revision. For example, before modification:
|
||||
DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000000)
|
||||
# After modification:
|
||||
DefinitionBlock ("DSDT.aml", "DSDT", 2, "INTEL ", "TEMPLATE", 0x00000001)
|
||||
iasl -sa dsdt.dsl
|
||||
# Add the raw ACPI tables to an uncompressed cpio archive.
|
||||
# They must be put into a /kernel/firmware/acpi directory inside the cpio
|
||||
# archive. Note that if the table put here matches a platform table
|
||||
# (similar Table Signature, and similar OEMID, and similar OEM Table ID)
|
||||
# with a more recent OEM Revision, the platform table will be upgraded by
|
||||
# this table. If the table put here doesn't match a platform table
|
||||
# (dissimilar Table Signature, or dissimilar OEMID, or dissimilar OEM Table
|
||||
# ID), this table will be appended.
|
||||
mkdir -p kernel/firmware/acpi
|
||||
cp dsdt.aml kernel/firmware/acpi
|
||||
# A maximum of "NR_ACPI_INITRD_TABLES (64)" tables are currently allowed
|
||||
# (see osl.c):
|
||||
iasl -sa facp.dsl
|
||||
iasl -sa ssdt1.dsl
|
||||
cp facp.aml kernel/firmware/acpi
|
||||
cp ssdt1.aml kernel/firmware/acpi
|
||||
# The uncompressed cpio archive must be the first. Other, typically
|
||||
# compressed cpio archives, must be concatenated on top of the uncompressed
|
||||
# one. Following command creates the uncompressed cpio archive and
|
||||
# concatenates the original initrd on top:
|
||||
find kernel | cpio -H newc --create > /boot/instrumented_initrd
|
||||
cat /boot/initrd >>/boot/instrumented_initrd
|
||||
# reboot with increased acpi debug level, e.g. boot params:
|
||||
acpi.debug_level=0x2 acpi.debug_layer=0xFFFFFFFF
|
||||
# and check your syslog:
|
||||
[ 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,
|
||||
also static ACPI tables.
|
||||
|
||||
|
||||
Where to retrieve userspace tools
|
||||
=================================
|
||||
|
||||
iasl and acpixtract are part of Intel's ACPICA project:
|
||||
http://acpica.org/
|
||||
|
||||
and should be packaged by distributions (for example in the acpica package
|
||||
on SUSE).
|
||||
|
||||
acpidump can be found in Len Browns pmtools:
|
||||
ftp://kernel.org/pub/linux/kernel/people/lenb/acpi/utils/pmtools/acpidump
|
||||
|
||||
This tool is also part of the acpica package on SUSE.
|
||||
Alternatively, used ACPI tables can be retrieved via sysfs in latest kernels:
|
||||
/sys/firmware/acpi/tables
|
||||
@@ -0,0 +1,180 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
=============
|
||||
SSDT Overlays
|
||||
=============
|
||||
|
||||
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
|
||||
image. A common example is connecting sensors on I2C / SPI buses on development
|
||||
boards.
|
||||
|
||||
Although this can be accomplished by creating a kernel platform driver or
|
||||
recompiling the firmware image with updated ACPI tables, neither is practical:
|
||||
the former proliferates board specific kernel code while the latter requires
|
||||
access to firmware tools which are often not publicly available.
|
||||
|
||||
Because ACPI supports external references in AML code a more practical
|
||||
way to augment firmware ACPI configuration is by dynamically loading
|
||||
user defined SSDT tables that contain the board specific information.
|
||||
|
||||
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
|
||||
following ASL code can be used::
|
||||
|
||||
DefinitionBlock ("minnowmax.aml", "SSDT", 1, "Vendor", "Accel", 0x00000003)
|
||||
{
|
||||
External (\_SB.I2C6, DeviceObj)
|
||||
|
||||
Scope (\_SB.I2C6)
|
||||
{
|
||||
Device (STAC)
|
||||
{
|
||||
Name (_ADR, Zero)
|
||||
Name (_HID, "BMA222E")
|
||||
|
||||
Method (_CRS, 0, Serialized)
|
||||
{
|
||||
Name (RBUF, ResourceTemplate ()
|
||||
{
|
||||
I2cSerialBus (0x0018, ControllerInitiated, 0x00061A80,
|
||||
AddressingMode7Bit, "\\_SB.I2C6", 0x00,
|
||||
ResourceConsumer, ,)
|
||||
GpioInt (Edge, ActiveHigh, Exclusive, PullDown, 0x0000,
|
||||
"\\_SB.GPO2", 0x00, ResourceConsumer, , )
|
||||
{ // Pin list
|
||||
0
|
||||
}
|
||||
})
|
||||
Return (RBUF)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
which can then be compiled to AML binary format::
|
||||
|
||||
$ iasl minnowmax.asl
|
||||
|
||||
Intel ACPI Component Architecture
|
||||
ASL Optimizing Compiler version 20140214-64 [Mar 29 2014]
|
||||
Copyright (c) 2000 - 2014 Intel Corporation
|
||||
|
||||
ASL Input: minnomax.asl - 30 lines, 614 bytes, 7 keywords
|
||||
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
|
||||
|
||||
The resulting AML code can then be loaded by the kernel using one of the methods
|
||||
below.
|
||||
|
||||
Loading ACPI SSDTs from initrd
|
||||
==============================
|
||||
|
||||
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.
|
||||
|
||||
It works in a similar way with initrd based ACPI tables override/upgrade: SSDT
|
||||
aml code must be placed in the first, uncompressed, initrd under the
|
||||
"kernel/firmware/acpi" path. Multiple files can be used and this will translate
|
||||
in loading multiple tables. Only SSDT and OEM tables are allowed. See
|
||||
initrd_table_override.txt for more details.
|
||||
|
||||
Here is an example::
|
||||
|
||||
# Add the raw ACPI tables to an uncompressed cpio archive.
|
||||
# They must be put into a /kernel/firmware/acpi directory inside the
|
||||
# cpio archive.
|
||||
# The uncompressed cpio archive must be the first.
|
||||
# Other, typically compressed cpio archives, must be
|
||||
# concatenated on top of the uncompressed one.
|
||||
mkdir -p kernel/firmware/acpi
|
||||
cp ssdt.aml kernel/firmware/acpi
|
||||
|
||||
# Create the uncompressed cpio archive and concatenate the original initrd
|
||||
# on top:
|
||||
find kernel | cpio -H newc --create > /boot/instrumented_initrd
|
||||
cat /boot/initrd >>/boot/instrumented_initrd
|
||||
|
||||
Loading ACPI SSDTs from EFI variables
|
||||
=====================================
|
||||
|
||||
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
|
||||
is also work underway to implement EFI support for loading user defined SSDTs
|
||||
and using this method will make it easier to convert to the EFI loading
|
||||
mechanism when that will arrive.
|
||||
|
||||
In order to load SSDTs from an EFI variable the efivar_ssdt kernel command line
|
||||
parameter can be used. The argument for the option is the variable name to
|
||||
use. If there are multiple variables with the same name but with different
|
||||
vendor GUIDs, all of them will be loaded.
|
||||
|
||||
In order to store the AML code in an EFI variable the efivarfs filesystem can be
|
||||
used. It is enabled and mounted by default in /sys/firmware/efi/efivars in all
|
||||
recent distribution.
|
||||
|
||||
Creating a new file in /sys/firmware/efi/efivars will automatically create a new
|
||||
EFI variable. Updating a file in /sys/firmware/efi/efivars will update the EFI
|
||||
variable. Please note that the file name needs to be specially formatted as
|
||||
"Name-GUID" and that the first 4 bytes in the file (little-endian format)
|
||||
represent the attributes of the EFI variable (see EFI_VARIABLE_MASK in
|
||||
include/linux/efi.h). Writing to the file must also be done with one write
|
||||
operation.
|
||||
|
||||
For example, you can use the following bash script to create/update an EFI
|
||||
variable with the content from a given file::
|
||||
|
||||
#!/bin/sh -e
|
||||
|
||||
while ! [ -z "$1" ]; do
|
||||
case "$1" in
|
||||
"-f") filename="$2"; shift;;
|
||||
"-g") guid="$2"; shift;;
|
||||
*) name="$1";;
|
||||
esac
|
||||
shift
|
||||
done
|
||||
|
||||
usage()
|
||||
{
|
||||
echo "Syntax: ${0##*/} -f filename [ -g guid ] name"
|
||||
exit 1
|
||||
}
|
||||
|
||||
[ -n "$name" -a -f "$filename" ] || usage
|
||||
|
||||
EFIVARFS="/sys/firmware/efi/efivars"
|
||||
|
||||
[ -d "$EFIVARFS" ] || exit 2
|
||||
|
||||
if stat -tf $EFIVARFS | grep -q -v de5e81e4; then
|
||||
mount -t efivarfs none $EFIVARFS
|
||||
fi
|
||||
|
||||
# try to pick up an existing GUID
|
||||
[ -n "$guid" ] || guid=$(find "$EFIVARFS" -name "$name-*" | head -n1 | cut -f2- -d-)
|
||||
|
||||
# use a randomly generated GUID
|
||||
[ -n "$guid" ] || guid="$(cat /proc/sys/kernel/random/uuid)"
|
||||
|
||||
# efivarfs expects all of the data in one write
|
||||
tmp=$(mktemp)
|
||||
/bin/echo -ne "\007\000\000\000" | cat - $filename > $tmp
|
||||
dd if=$tmp of="$EFIVARFS/$name-$guid" bs=$(stat -c %s $tmp)
|
||||
rm $tmp
|
||||
|
||||
Loading ACPI SSDTs from 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
|
||||
mounted. In the following examples, we assume that configfs has been mounted in
|
||||
/config.
|
||||
|
||||
New tables can be loading by creating new directories in /config/acpi/table/ and
|
||||
writing the SSDT aml code in the aml attribute::
|
||||
|
||||
cd /config/acpi/table
|
||||
mkdir my_ssdt
|
||||
cat ~/ssdt.aml > my_ssdt/aml
|
||||
@@ -77,6 +77,7 @@ configure specific aspects of kernel behavior to your liking.
|
||||
LSM/index
|
||||
mm/index
|
||||
perf-security
|
||||
acpi/index
|
||||
|
||||
.. only:: subproject and html
|
||||
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
============
|
||||
ACPI Support
|
||||
============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
linuxized-acpica
|
||||
scan_handlers
|
||||
+64
-47
@@ -1,31 +1,37 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
.. include:: <isonum.txt>
|
||||
|
||||
============================================================
|
||||
Linuxized ACPICA - Introduction to ACPICA Release Automation
|
||||
============================================================
|
||||
|
||||
Copyright (C) 2013-2016, Intel Corporation
|
||||
Author: Lv Zheng <lv.zheng@intel.com>
|
||||
:Copyright: |copy| 2013-2016, Intel Corporation
|
||||
|
||||
:Author: Lv Zheng <lv.zheng@intel.com>
|
||||
|
||||
|
||||
Abstract:
|
||||
|
||||
Abstract
|
||||
========
|
||||
This document describes the ACPICA project and the relationship between
|
||||
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
|
||||
upstream.
|
||||
|
||||
ACPICA Project
|
||||
==============
|
||||
|
||||
1. ACPICA Project
|
||||
The ACPI Component Architecture (ACPICA) project provides an operating
|
||||
system (OS)-independent reference implementation of the Advanced
|
||||
Configuration and Power Interface Specification (ACPI). It has been
|
||||
adapted by various host OSes. By directly integrating ACPICA, Linux can
|
||||
also benefit from the application experiences of ACPICA from other host
|
||||
OSes.
|
||||
|
||||
The ACPI Component Architecture (ACPICA) project provides an operating
|
||||
system (OS)-independent reference implementation of the Advanced
|
||||
Configuration and Power Interface Specification (ACPI). It has been
|
||||
adapted by various host OSes. By directly integrating ACPICA, Linux can
|
||||
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
|
||||
supported by Intel Corporation.
|
||||
|
||||
The homepage of ACPICA project is: www.acpica.org, it is maintained and
|
||||
supported by Intel Corporation.
|
||||
|
||||
The following figure depicts the Linux ACPI subsystem where the ACPICA
|
||||
adaptation is included:
|
||||
The following figure depicts the Linux ACPI subsystem where the ACPICA
|
||||
adaptation is included::
|
||||
|
||||
+---------------------------------------------------------+
|
||||
| |
|
||||
@@ -71,21 +77,27 @@ upstream.
|
||||
|
||||
Figure 1. Linux ACPI Software Components
|
||||
|
||||
NOTE:
|
||||
.. note::
|
||||
A. OS Service Layer - Provided by Linux to offer OS dependent
|
||||
implementation of the predefined ACPICA interfaces (acpi_os_*).
|
||||
::
|
||||
|
||||
include/acpi/acpiosxf.h
|
||||
drivers/acpi/osl.c
|
||||
include/acpi/platform
|
||||
include/asm/acenv.h
|
||||
B. ACPICA Functionality - Released from ACPICA code base to offer
|
||||
OS independent implementation of the ACPICA interfaces (acpi_*).
|
||||
::
|
||||
|
||||
drivers/acpi/acpica
|
||||
include/acpi/ac*.h
|
||||
tools/power/acpi
|
||||
C. Linux/ACPI Functionality - Providing Linux specific ACPI
|
||||
functionality to the other Linux kernel subsystems and user space
|
||||
programs.
|
||||
::
|
||||
|
||||
drivers/acpi
|
||||
include/linux/acpi.h
|
||||
include/linux/acpi*.h
|
||||
@@ -95,24 +107,27 @@ upstream.
|
||||
ACPI subsystem to offer architecture specific implementation of the
|
||||
ACPI interfaces. They are Linux specific components and are out of
|
||||
the scope of this document.
|
||||
::
|
||||
|
||||
include/asm/acpi.h
|
||||
include/asm/acpi*.h
|
||||
arch/*/acpi
|
||||
|
||||
2. ACPICA Release
|
||||
ACPICA Release
|
||||
==============
|
||||
|
||||
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
|
||||
month.
|
||||
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
|
||||
month.
|
||||
|
||||
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 patches. The patches generated by this process are referred to as
|
||||
"linuxized ACPICA patches". The release process is carried out on a local
|
||||
copy the ACPICA git repository. Each commit in the monthly release is
|
||||
converted into a linuxized ACPICA patch. Together, they form the monthly
|
||||
ACPICA release patchset for the Linux ACPI community. This process is
|
||||
illustrated in the following figure:
|
||||
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 patches. The patches generated by this process are referred to as
|
||||
"linuxized ACPICA patches". The release process is carried out on a local
|
||||
copy the ACPICA git repository. Each commit in the monthly release is
|
||||
converted into a linuxized ACPICA patch. Together, they form the monthly
|
||||
ACPICA release patchset for the Linux ACPI community. This process is
|
||||
illustrated in the following figure::
|
||||
|
||||
+-----------------------------+
|
||||
| acpica / master (-) commits |
|
||||
@@ -153,7 +168,7 @@ upstream.
|
||||
|
||||
Figure 2. ACPICA -> Linux Upstream Process
|
||||
|
||||
NOTE:
|
||||
.. note::
|
||||
A. Linuxize Utilities - Provided by the ACPICA repository, including a
|
||||
utility located in source/tools/acpisrc folder and a number of
|
||||
scripts located in generate/linux folder.
|
||||
@@ -170,19 +185,20 @@ upstream.
|
||||
following kernel configuration options:
|
||||
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
|
||||
automatically without manual modifications, the "linux / master" tree should
|
||||
contain the ACPICA code that exactly corresponds to the ACPICA code
|
||||
contained in "new linuxized acpica" tree and it should be possible to run
|
||||
the release process fully automatically.
|
||||
Ideally, all of the ACPICA commits should be converted into Linux patches
|
||||
automatically without manual modifications, the "linux / master" tree should
|
||||
contain the ACPICA code that exactly corresponds to the ACPICA code
|
||||
contained in "new linuxized acpica" tree and it should be possible to run
|
||||
the release process fully automatically.
|
||||
|
||||
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
|
||||
"ACPICA Divergences".
|
||||
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
|
||||
"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
|
||||
established, there already had been divergences between Linux and
|
||||
ACPICA. Over the past several years those divergences have been greatly
|
||||
@@ -213,11 +229,12 @@ upstream.
|
||||
rebased on the ACPICA side in order to offer better solutions, new ACPICA
|
||||
divergences are generated.
|
||||
|
||||
4. ACPICA Development
|
||||
ACPICA Development
|
||||
==================
|
||||
|
||||
This paragraph guides Linux developers to use the ACPICA upstream release
|
||||
utilities to obtain Linux patches corresponding to upstream ACPICA commits
|
||||
before they become available from the ACPICA release process.
|
||||
This paragraph guides Linux developers to use the ACPICA upstream release
|
||||
utilities to obtain Linux patches corresponding to upstream ACPICA commits
|
||||
before they become available from the ACPICA release process.
|
||||
|
||||
1. Cherry-pick an ACPICA commit
|
||||
|
||||
@@ -225,7 +242,7 @@ upstream.
|
||||
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
|
||||
from the ACPICA local repository:
|
||||
from the ACPICA local repository::
|
||||
|
||||
$ git clone https://github.com/acpica/acpica
|
||||
$ cd acpica
|
||||
@@ -240,7 +257,7 @@ upstream.
|
||||
changes that haven't been applied to Linux yet.
|
||||
|
||||
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
|
||||
$ cd acpica
|
||||
@@ -254,7 +271,7 @@ upstream.
|
||||
3. Inspect the current divergences
|
||||
|
||||
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 http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
|
||||
+16
-10
@@ -1,7 +1,13 @@
|
||||
ACPI Scan Handlers
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
.. include:: <isonum.txt>
|
||||
|
||||
Copyright (C) 2012, Intel Corporation
|
||||
Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
|
||||
==================
|
||||
ACPI Scan Handlers
|
||||
==================
|
||||
|
||||
:Copyright: |copy| 2012, Intel Corporation
|
||||
|
||||
:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
|
||||
|
||||
During system initialization and ACPI-based device hot-add, the ACPI namespace
|
||||
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.
|
||||
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
|
||||
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 {
|
||||
const struct acpi_device_id *ids;
|
||||
struct list_head list_node;
|
||||
int (*attach)(struct acpi_device *dev, const struct acpi_device_id *id);
|
||||
void (*detach)(struct acpi_device *dev);
|
||||
};
|
||||
struct acpi_scan_handler {
|
||||
const struct acpi_device_id *ids;
|
||||
struct list_head list_node;
|
||||
int (*attach)(struct acpi_device *dev, const struct acpi_device_id *id);
|
||||
void (*detach)(struct acpi_device *dev);
|
||||
};
|
||||
|
||||
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
|
||||
@@ -56,6 +56,7 @@ available subsections can be seen below.
|
||||
slimbus
|
||||
soundwire/index
|
||||
fpga/index
|
||||
acpi/index
|
||||
|
||||
.. only:: subproject and html
|
||||
|
||||
|
||||
+12
-9
@@ -1,8 +1,11 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
==================================
|
||||
_DSD Device Properties Usage Rules
|
||||
----------------------------------
|
||||
==================================
|
||||
|
||||
Properties, Property Sets and Property Subsets
|
||||
----------------------------------------------
|
||||
==============================================
|
||||
|
||||
The _DSD (Device Specific Data) configuration object, introduced in ACPI 5.1,
|
||||
allows any type of device configuration data to be provided via the ACPI
|
||||
@@ -18,7 +21,7 @@ specific type) associated with it.
|
||||
|
||||
In the ACPI _DSD context it is an element of the sub-package following the
|
||||
generic Device Properties UUID in the _DSD return package as specified in the
|
||||
Device Properties UUID definition document [1].
|
||||
Device Properties UUID definition document [1]_.
|
||||
|
||||
It also may be regarded as the definition of a key and the associated data type
|
||||
that can be returned by _DSD in the Device Properties UUID sub-package for a
|
||||
@@ -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
|
||||
to as a whole (and to be treated as a separate entity). The canonical
|
||||
representation of property subsets is via the mechanism specified in the
|
||||
Hierarchical Properties Extension UUID definition document [2].
|
||||
Hierarchical Properties Extension UUID definition document [2]_.
|
||||
|
||||
Property sets may be hierarchical. That is, a property set may contain
|
||||
multiple property subsets that each may contain property subsets of its
|
||||
own and so on.
|
||||
|
||||
General Validity Rule for Property Sets
|
||||
---------------------------------------
|
||||
=======================================
|
||||
|
||||
Valid property sets must follow the guidance given by the Device Properties UUID
|
||||
definition document [1].
|
||||
@@ -73,7 +76,7 @@ suitable for the ACPI environment and consequently they cannot belong to a valid
|
||||
property set.
|
||||
|
||||
Property Sets and Device Tree Bindings
|
||||
--------------------------------------
|
||||
======================================
|
||||
|
||||
It often is useful to make _DSD return property sets that follow Device Tree
|
||||
bindings.
|
||||
@@ -91,7 +94,7 @@ expected to automatically work in the ACPI environment regardless of their
|
||||
contents.
|
||||
|
||||
References
|
||||
----------
|
||||
==========
|
||||
|
||||
[1] http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf
|
||||
[2] http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf
|
||||
.. [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
|
||||
@@ -1,13 +1,18 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
.. include:: <isonum.txt>
|
||||
|
||||
=========================================================
|
||||
Special Usage Model of the ACPI Control Method Lid Device
|
||||
=========================================================
|
||||
|
||||
Copyright (C) 2016, Intel Corporation
|
||||
Author: Lv Zheng <lv.zheng@intel.com>
|
||||
:Copyright: |copy| 2016, Intel Corporation
|
||||
|
||||
:Author: Lv Zheng <lv.zheng@intel.com>
|
||||
|
||||
Abstract:
|
||||
|
||||
Platforms containing lids convey lid state (open/close) to OSPMs using a
|
||||
control method lid device. To implement this, the AML tables issue
|
||||
Abstract
|
||||
========
|
||||
Platforms containing lids convey lid state (open/close) to OSPMs
|
||||
using a control method lid device. To implement this, the AML tables issue
|
||||
Notify(lid_device, 0x80) to notify the OSPMs whenever the lid state has
|
||||
changed. The _LID control method for the lid device must be implemented to
|
||||
report the "current" state of the lid as either "opened" or "closed".
|
||||
@@ -19,7 +24,8 @@ taken into account. This document describes the restrictions and the
|
||||
expections of the Linux ACPI lid device driver.
|
||||
|
||||
|
||||
1. Restrictions of the returning value of the _LID control method
|
||||
Restrictions of the returning value of the _LID control method
|
||||
==============================================================
|
||||
|
||||
The _LID control method is described to return the "current" lid state.
|
||||
However the word of "current" has ambiguity, some buggy AML tables return
|
||||
@@ -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.
|
||||
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
|
||||
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
|
||||
trigger some system power saving operations on Windows. Since it is fully
|
||||
tested, it is reliable from all AML tables.
|
||||
|
||||
3. Expections for the userspace users of the ACPI lid device driver
|
||||
Expections for the userspace users of the ACPI lid device driver
|
||||
================================================================
|
||||
|
||||
The ACPI button driver exports the lid state to the userspace via the
|
||||
following file:
|
||||
following file::
|
||||
|
||||
/proc/acpi/button/lid/LID0/state
|
||||
|
||||
This file actually calls the _LID control method described above. And given
|
||||
the previous explanation, it is not reliable enough on some platforms. So
|
||||
it is advised for the userspace program to not to solely rely on this file
|
||||
to determine the actual lid state.
|
||||
|
||||
The ACPI button driver emits the following input event to the userspace:
|
||||
SW_LID
|
||||
* SW_LID
|
||||
|
||||
The ACPI lid device driver is implemented to try to deliver the platform
|
||||
triggered events to the userspace. However, given the fact that the buggy
|
||||
firmware cannot make sure "opened"/"closed" events are paired, the ACPI
|
||||
@@ -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"
|
||||
events and the unreliable initial state notification, Linux users can use
|
||||
the following kernel parameters to handle the possible issues:
|
||||
|
||||
A. button.lid_init_state=method:
|
||||
When this option is specified, the ACPI button driver reports the
|
||||
initial lid state using the returning value of the _LID control method
|
||||
and whether the "opened"/"closed" events are paired fully relies on the
|
||||
firmware implementation.
|
||||
|
||||
This option can be used to fix some platforms where the returning value
|
||||
of the _LID control method is reliable but the initial lid state
|
||||
notification is missing.
|
||||
|
||||
This option is the default behavior during the period the userspace
|
||||
isn't ready to handle the buggy AML tables.
|
||||
|
||||
B. button.lid_init_state=open:
|
||||
When this option is specified, the ACPI button driver always reports the
|
||||
initial lid state as "opened" and whether the "opened"/"closed" events
|
||||
are paired fully relies on the firmware implementation.
|
||||
|
||||
This may fix some platforms where the returning value of the _LID
|
||||
control method is not reliable and the initial lid state notification is
|
||||
missing.
|
||||
@@ -80,6 +96,7 @@ B. button.lid_init_state=open:
|
||||
If the userspace has been prepared to ignore the unreliable "opened" events
|
||||
and the unreliable initial state notification, Linux users should always
|
||||
use the following kernel parameter:
|
||||
|
||||
C. button.lid_init_state=ignore:
|
||||
When this option is specified, the ACPI button driver never reports the
|
||||
initial lid state and there is a compensation mechanism implemented to
|
||||
@@ -89,6 +106,7 @@ C. button.lid_init_state=ignore:
|
||||
notifications can be delivered to the userspace when the lid is actually
|
||||
opens given that some AML tables do not send "opened" notifications
|
||||
reliably.
|
||||
|
||||
In this mode, if everything is correctly implemented by the platform
|
||||
firmware, the old userspace programs should still work. Otherwise, the
|
||||
new userspace programs are required to work with the ACPI button driver.
|
||||
@@ -0,0 +1,75 @@
|
||||
.. 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"
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user