ACPI / Documentation: Update method tracing documentation.
authorLv Zheng <lv.zheng@intel.com>
Wed, 5 Aug 2015 08:24:04 +0000 (16:24 +0800)
committerRafael J. Wysocki <rafael.j.wysocki@intel.com>
Fri, 7 Aug 2015 00:42:22 +0000 (02:42 +0200)
This patch updates method tracing documentation.

Signed-off-by: Lv Zheng <lv.zheng@intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Documentation/acpi/method-tracing.txt

index f6efb1e..c2505ee 100644 (file)
-/sys/module/acpi/parameters/:
+ACPICA Trace Facility
 
-trace_method_name
-       The AML method name that the user wants to trace
+Copyright (C) 2015, Intel Corporation
+Author: Lv Zheng <lv.zheng@intel.com>
 
-trace_debug_layer
-       The temporary debug_layer used when tracing the method.
-       Using 0xffffffff by default if it is 0.
 
-trace_debug_level
-       The temporary debug_level used when tracing the method.
-       Using 0x00ffffff by default if it is 0.
+Abstract:
 
-trace_state
-       The status of the tracing feature.
+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.
 
-       "enabled" means this feature is enabled
-       and the AML method is traced every time it's executed.
+   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.
 
-       "1" means this feature is enabled and the AML method
-       will only be traced during the next execution.
+   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
 
-       "disabled" means this feature is disabled.
-       Users can enable/disable this debug tracing feature by
-       "echo string > /sys/module/acpi/parameters/trace_state".
-       "string" should be one of "enable", "disable" and "1".
+  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 followings:
+       "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.