Commit eea78032 authored by Changbin Du's avatar Changbin Du Committed by Rafael J. Wysocki
Browse files

Documentation: ACPI: move method-customizing.txt to firmware-guide/acpi and convert to reST 



This converts the plain text documentation to reStructuredText format
and adds it to Sphinx TOC tree.

No essential content change.

Signed-off-by: default avatarChangbin Du <changbin.du@gmail.com>
Reviewed-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: default avatarRafael J. Wysocki <rafael.j.wysocki@intel.com>
parent b6dff0e1

Documentation/acpi/method-customizing.txt

deleted100644 → 0
+0 −73
Original line number Diff line number Diff line 
Linux ACPI Custom Control Method How To

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



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





Linux supports customizing ACPI control methods at runtime.



Users can use this to

1. override an existing method which may not work correctly,

   or just for debugging purposes.

2. insert a completely new method in order to create a missing

   method such as _OFF, _ON, _STA, _INI, etc.

For these cases, it is far simpler to dynamically install a single

control method rather than override the entire DSDT, because kernel

rebuild/reboot is not needed and test result can be got in minutes.



Note: Only ACPI METHOD can be overridden, any other object types like

      "Device", "OperationRegion", are not recognized. Methods

      declared inside scope operators are also not supported.

Note: The same ACPI control method can be overridden for many times,

      and it's always the latest one that used by Linux/kernel.

Note: To get the ACPI debug object output (Store (AAAA, Debug)),

      please run "echo 1 > /sys/module/acpi/parameters/aml_debug_output".



1. override an existing method

   a) get the ACPI table via ACPI sysfs I/F. e.g. to get the DSDT,

      just run "cat /sys/firmware/acpi/tables/DSDT > /tmp/dsdt.dat"

   b) disassemble the table by running "iasl -d dsdt.dat".

   c) rewrite the ASL code of the method and save it in a new file,

   d) package the new file (psr.asl) to an ACPI table format.

      Here is an example of a customized \_SB._AC._PSR method,



      DefinitionBlock ("", "SSDT", 1, "", "", 0x20080715)

      {

	Method (\_SB_.AC._PSR, 0, NotSerialized)

	{

		Store ("In AC _PSR", Debug)

		Return (ACON)

	}

      }

      Note that the full pathname of the method in ACPI namespace

      should be used.

   e) assemble the file to generate the AML code of the method.

      e.g. "iasl -vw 6084 psr.asl" (psr.aml is generated as a result)

      If parameter "-vw 6084" is not supported by your iASL compiler,

      please try a newer version.

   f) mount debugfs by "mount -t debugfs none /sys/kernel/debug"

   g) override the old method via the debugfs by running

      "cat /tmp/psr.aml > /sys/kernel/debug/acpi/custom_method"



2. insert a new method

   This is easier than overriding an existing method.

   We just need to create the ASL code of the method we want to

   insert and then follow the step c) ~ g) in section 1.



3. undo your changes

   The "undo" operation is not supported for a new inserted method

   right now, i.e. we can not remove a method currently.

   For an overridden method, in order to undo your changes, please

   save a copy of the method original ASL code in step c) section 1,

   and redo step c) ~ g) to override the method with the original one.





Note: We can use a kernel with multiple custom ACPI method running,

      But each individual write to debugfs can implement a SINGLE

      method override. i.e. if we want to insert/override multiple

      ACPI methods, we need to redo step c) ~ g) for multiple times.



Note: Be aware that root can mis-use this driver to modify arbitrary

      memory and gain additional rights, if root's privileges got

      restricted (for example if root is not allowed to load additional

      modules after boot).

Documentation/firmware-guide/acpi/index.rst

+2 −1
Original line number Diff line number Diff line
@@ -10,5 +10,6 @@ ACPI Support 
   namespace

   enumeration

   osi

   method-customizing

   DSD-properties-rules

   gpio-properties
 
 No newline at end of file

Documentation/firmware-guide/acpi/method-customizing.rst

0 → 100644
+89 −0
Original line number Diff line number Diff line 
.. 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).