Documentation/acpi/method-customizing.txt

Chinese translated version of Documentation\block\switching-sched.txt

If you have any comment or update to the content, please contact the
original document maintainer directly.  However, if you have a problem
communicating in English you can also ask the Chinese maintainer for
help.  Contact the Chinese maintainer if this translation is outdated
or if there is a problem with the translation.

Chinese maintainer: 秦芹 18768122412@163.com
---------------------------------------------------------------------
Documentation/acpi/method-customizing.txt的中文翻译

如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
译存在问题，请联系中文版维护者。

中文版维护者： 秦芹 18768122412@163.com
中文版翻译者：秦芹 18768122412@163.com

以下为正文
---------------------------------------------------------------------

Linux ACPI Custom Control Method How To

Linux ACPI怎样定制控制方法

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

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

原文由张瑞书写，电子邮箱为：<rui.zhang@intel.com>

Linux supports customizing ACPI control methods at runtime.

Linux支持在运行时定制ACPI控制方法

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.

   插入一个全新的方法来创建一类丢失的方法（如：_OFF,_ON,_STA,_INI等）。

    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.

   对于这些情况，动态安装一个简单控制方法比覆盖整个DSDT更加简单，

    因为内核重建/重启是没有必要的，并且在几分钟内就可以得到测试结果。

对于定制的ACPI控制方法的使用，需要注意如下几点：
 Note: Only ACPI METHOD can be overridden, any other object types like
        "Device", "OperationRegion", are not recognized.

注：只有ACPI方法可以被覆盖，而任何其他对象类型（如：“设备”，

       “OperationRegion”）是不被允许的。

 Note: The same ACPI control method can be overridden for many times,
        and it's always the latest one that used by Linux/kernel.

 注：相同的ACPI控制方法可以被覆盖多次，它总是使用Linux/内核最新的一个。
 Note: To get the ACPI debug object output (Store (AAAA, Debug)),
        please run "echo 1 > /sys/module/acpi/parameters/aml_debug_output".

  注：为了得到ACPI调试对象的输出，请运行命令：
     "echi1>/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"

        通过ACPIsysfs中的I/F就可以获得ACPI表。
       如：要得到DSDT，只需运行命令：
      “cat /sys/firmware/acpi/tables/DSDT>/tmp/dsdt.dat”
     b) disassemble the table by running "iasl -d dsdt.dat".

          拆卸表，运行命令：“iasl -d dsdt.dat”。
     c) rewrite the ASL code of the method and save it in a new file,

         重写方法中的ASL代码，并将其保存在一个新文件中。
     d) package the new file (psr.asl) to an ACPI table format.

        将新文件（psr.asl）包装成ACPI表格式。
        Here is an example of a customized \_SB._AC._PSR method,
        下面是一个定制\_SB._AC._PSR方法的例子：
       DefinitionBlock ("", "SSDT", 1, "", "", 0x20080715)
        {
          External (ACON)
 
          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.
        And remember to use "External" to declare external objects.

       注：ACPI命名空间中应该使用方法的完整路径，

       并且声明外部对象要使用关键字“External”进行声明。
    e) assemble the file to generate the AML code of the method.
       e.g. "iasl psr.asl" (psr.aml is generated as a result)

       组装文件生成方法的AML代码。

       如：“iasl psr.asl”(psr.aml是组装文件生成的结果)
    f) mount debugfs by "mount -t debugfs none /sys/kernel/debug"

       安装debugfs（Linux内核），通过运行命令：
       “mount -t debugfs none /sys/kernal/debug”
    g) override the old method via the debugfs by running
       "cat /tmp/psr.aml > /sys/kernel/debug/acpi/custom_method"

        通过运行debugfs覆盖旧方法。运行内核命令：
        “cat /tmp/psr.aml>/sys/kernal/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.
     插入一个新方法
     这比覆盖一个现有方法更容易。我们只需要创建我们想插入

     的ASL代码方法，然后安装1中的c~g步骤进行操作。
  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 overrided 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. 

     撤销更改

     "撤销"操作现在不支持插入一个新方法，也就是我们不能去除当前

      的方法。对于一个覆盖的方法，为了能做撤销更改，需要在1条中

      步骤c时，保存原方法的一个副本，并且重做步骤c~g，用原始的

     ASL代码覆盖现有方法。
 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.
  注：我们可以用一个内核来实现多个自定义运行的ACPI方法，

         但是，每一个人写的debugfs只能实现单一的方法覆盖。

          即：如果我们想插入/覆盖多个ACPI方法，我们需要重做多次步骤c~g。
  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).

 注：请注意，root可以不当使用此驱动来任意修改内存和获得额外

         的权利，但如果root的权限受到了限制就不能进行这些操作。

        （如：如果不允许开机后，root加载额外模块）