lkml.org 
[lkml]   [2019]   [Apr]   [25]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v6 09/24] Documentation: ACPI: move method-customizing.txt to firmware-guide/acpi and convert to reST
    Date
    This converts the plain text documentation to reStructuredText format and
    add it to Sphinx TOC tree. No essential content change.

    Signed-off-by: Changbin Du <changbin.du@gmail.com>
    Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
    ---
    Documentation/acpi/method-customizing.txt | 73 ---------------
    Documentation/firmware-guide/acpi/index.rst | 3 +-
    .../acpi/method-customizing.rst | 89 +++++++++++++++++++
    3 files changed, 91 insertions(+), 74 deletions(-)
    delete mode 100644 Documentation/acpi/method-customizing.txt
    create mode 100644 Documentation/firmware-guide/acpi/method-customizing.rst

    diff --git a/Documentation/acpi/method-customizing.txt b/Documentation/acpi/method-customizing.txt
    deleted file mode 100644
    index 7235da975f23..000000000000
    --- a/Documentation/acpi/method-customizing.txt
    +++ /dev/null
    @@ -1,73 +0,0 @@
    -Linux ACPI Custom Control Method How To
    -=======================================
    -
    -Written by Zhang Rui <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).
    diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
    index 61d67763851b..d1d069b26bbc 100644
    --- a/Documentation/firmware-guide/acpi/index.rst
    +++ b/Documentation/firmware-guide/acpi/index.rst
    @@ -10,5 +10,6 @@ ACPI Support
    namespace
    enumeration
    osi
    + method-customizing
    DSD-properties-rules
    - gpio-properties
    + gpio-properties
    \ No newline at end of file
    diff --git a/Documentation/firmware-guide/acpi/method-customizing.rst b/Documentation/firmware-guide/acpi/method-customizing.rst
    new file mode 100644
    index 000000000000..de3ebcaed4cf
    --- /dev/null
    +++ b/Documentation/firmware-guide/acpi/method-customizing.rst
    @@ -0,0 +1,89 @@
    +.. SPDX-License-Identifier: GPL-2.0
    +
    +=======================================
    +Linux ACPI Custom Control Method How To
    +=======================================
    +
    +:Author: Zhang Rui <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).
    --
    2.20.1
    \
     
     \ /
      Last update: 2019-04-25 17:35    [W:2.326 / U:0.108 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site