0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =======================================
0004 Linux ACPI Custom Control Method How To
0005 =======================================
0006
0007 :Author: Zhang Rui <rui.zhang@intel.com>
0008
0009
0010 Linux supports customizing ACPI control methods at runtime.
0011
0012 Users can use this to:
0013
0014 1. override an existing method which may not work correctly,
0015 or just for debugging purposes.
0016 2. insert a completely new method in order to create a missing
0017 method such as _OFF, _ON, _STA, _INI, etc.
0018
0019 For these cases, it is far simpler to dynamically install a single
0020 control method rather than override the entire DSDT, because kernel
0021 rebuild/reboot is not needed and test result can be got in minutes.
0022
0023 .. note::
0024
0025 - Only ACPI METHOD can be overridden, any other object types like
0026 "Device", "OperationRegion", are not recognized. Methods
0027 declared inside scope operators are also not supported.
0028
0029 - The same ACPI control method can be overridden for many times,
0030 and it's always the latest one that used by Linux/kernel.
0031
0032 - To get the ACPI debug object output (Store (AAAA, Debug)),
0033 please run::
0034
0035 echo 1 > /sys/module/acpi/parameters/aml_debug_output
0036
0037
0038 1. override an existing method
0039 ==============================
0040 a) get the ACPI table via ACPI sysfs I/F. e.g. to get the DSDT,
0041 just run "cat /sys/firmware/acpi/tables/DSDT > /tmp/dsdt.dat"
0042 b) disassemble the table by running "iasl -d dsdt.dat".
0043 c) rewrite the ASL code of the method and save it in a new file,
0044 d) package the new file (psr.asl) to an ACPI table format.
0045 Here is an example of a customized \_SB._AC._PSR method::
0046
0047 DefinitionBlock ("", "SSDT", 1, "", "", 0x20080715)
0048 {
0049 Method (\_SB_.AC._PSR, 0, NotSerialized)
0050 {
0051 Store ("In AC _PSR", Debug)
0052 Return (ACON)
0053 }
0054 }
0055
0056 Note that the full pathname of the method in ACPI namespace
0057 should be used.
0058 e) assemble the file to generate the AML code of the method.
0059 e.g. "iasl -vw 6084 psr.asl" (psr.aml is generated as a result)
0060 If parameter "-vw 6084" is not supported by your iASL compiler,
0061 please try a newer version.
0062 f) mount debugfs by "mount -t debugfs none /sys/kernel/debug"
0063 g) override the old method via the debugfs by running
0064 "cat /tmp/psr.aml > /sys/kernel/debug/acpi/custom_method"
0065
0066 2. insert a new method
0067 ======================
0068 This is easier than overriding an existing method.
0069 We just need to create the ASL code of the method we want to
0070 insert and then follow the step c) ~ g) in section 1.
0071
0072 3. undo your changes
0073 ====================
0074 The "undo" operation is not supported for a new inserted method
0075 right now, i.e. we can not remove a method currently.
0076 For an overridden method, in order to undo your changes, please
0077 save a copy of the method original ASL code in step c) section 1,
0078 and redo step c) ~ g) to override the method with the original one.
0079
0080
0081 .. note:: We can use a kernel with multiple custom ACPI method running,
0082 But each individual write to debugfs can implement a SINGLE
0083 method override. i.e. if we want to insert/override multiple
0084 ACPI methods, we need to redo step c) ~ g) for multiple times.
0085
0086 .. note:: Be aware that root can mis-use this driver to modify arbitrary
0087 memory and gain additional rights, if root's privileges got
0088 restricted (for example if root is not allowed to load additional
0089 modules after boot).
