Back to home page

OSCL-LXR

 
 

    


0001 .. SPDX-License-Identifier: GPL-2.0
0002 .. include:: <isonum.txt>
0003 
0004 =====================
0005 ACPICA Trace Facility
0006 =====================
0007 
0008 :Copyright: |copy| 2015, Intel Corporation
0009 :Author: Lv Zheng <lv.zheng@intel.com>
0010 
0011 
0012 Abstract
0013 ========
0014 This document describes the functions and the interfaces of the
0015 method tracing facility.
0016 
0017 Functionalities and usage examples
0018 ==================================
0019 
0020 ACPICA provides method tracing capability. And two functions are
0021 currently implemented using this capability.
0022 
0023 Log reducer
0024 -----------
0025 
0026 ACPICA subsystem provides debugging outputs when CONFIG_ACPI_DEBUG is
0027 enabled. The debugging messages which are deployed via
0028 ACPI_DEBUG_PRINT() macro can be reduced at 2 levels - per-component
0029 level (known as debug layer, configured via
0030 /sys/module/acpi/parameters/debug_layer) and per-type level (known as
0031 debug level, configured via /sys/module/acpi/parameters/debug_level).
0032 
0033 But when the particular layer/level is applied to the control method
0034 evaluations, the quantity of the debugging outputs may still be too
0035 large to be put into the kernel log buffer. The idea thus is worked out
0036 to only enable the particular debug layer/level (normally more detailed)
0037 logs when the control method evaluation is started, and disable the
0038 detailed logging when the control method evaluation is stopped.
0039 
0040 The following command examples illustrate the usage of the "log reducer"
0041 functionality:
0042 
0043 a. Filter out the debug layer/level matched logs when control methods
0044    are being evaluated::
0045 
0046       # cd /sys/module/acpi/parameters
0047       # echo "0xXXXXXXXX" > trace_debug_layer
0048       # echo "0xYYYYYYYY" > trace_debug_level
0049       # echo "enable" > trace_state
0050 
0051 b. Filter out the debug layer/level matched logs when the specified
0052    control method is being evaluated::
0053 
0054       # cd /sys/module/acpi/parameters
0055       # echo "0xXXXXXXXX" > trace_debug_layer
0056       # echo "0xYYYYYYYY" > trace_debug_level
0057       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
0058       # echo "method" > /sys/module/acpi/parameters/trace_state
0059 
0060 c. Filter out the debug layer/level matched logs when the specified
0061    control method is being evaluated for the first time::
0062 
0063       # cd /sys/module/acpi/parameters
0064       # echo "0xXXXXXXXX" > trace_debug_layer
0065       # echo "0xYYYYYYYY" > trace_debug_level
0066       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
0067       # echo "method-once" > /sys/module/acpi/parameters/trace_state
0068 
0069 Where:
0070    0xXXXXXXXX/0xYYYYYYYY
0071      Refer to Documentation/firmware-guide/acpi/debug.rst for possible debug layer/level
0072      masking values.
0073    \PPPP.AAAA.TTTT.HHHH
0074      Full path of a control method that can be found in the ACPI namespace.
0075      It needn't be an entry of a control method evaluation.
0076 
0077 AML tracer
0078 ----------
0079 
0080 There are special log entries added by the method tracing facility at
0081 the "trace points" the AML interpreter starts/stops to execute a control
0082 method, or an AML opcode. Note that the format of the log entries are
0083 subject to change::
0084 
0085    [    0.186427]   exdebug-0398 ex_trace_point        : Method Begin [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
0086    [    0.186630]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905c88:If] execution.
0087    [    0.186820]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905cc0:LEqual] execution.
0088    [    0.187010]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905a20:-NamePath-] execution.
0089    [    0.187214]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905a20:-NamePath-] execution.
0090    [    0.187407]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905f60:One] execution.
0091    [    0.187594]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905f60:One] execution.
0092    [    0.187789]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905cc0:LEqual] execution.
0093    [    0.187980]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905cc0:Return] execution.
0094    [    0.188146]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905f60:One] execution.
0095    [    0.188334]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905f60:One] execution.
0096    [    0.188524]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905cc0:Return] execution.
0097    [    0.188712]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905c88:If] execution.
0098    [    0.188903]   exdebug-0398 ex_trace_point        : Method End [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
0099 
0100 Developers can utilize these special log entries to track the AML
0101 interpretation, thus can aid issue debugging and performance tuning. Note
0102 that, as the "AML tracer" logs are implemented via ACPI_DEBUG_PRINT()
0103 macro, CONFIG_ACPI_DEBUG is also required to be enabled for enabling
0104 "AML tracer" logs.
0105 
0106 The following command examples illustrate the usage of the "AML tracer"
0107 functionality:
0108 
0109 a. Filter out the method start/stop "AML tracer" logs when control
0110    methods are being evaluated::
0111 
0112       # cd /sys/module/acpi/parameters
0113       # echo "0x80" > trace_debug_layer
0114       # echo "0x10" > trace_debug_level
0115       # echo "enable" > trace_state
0116 
0117 b. Filter out the method start/stop "AML tracer" when the specified
0118    control method is being evaluated::
0119 
0120       # cd /sys/module/acpi/parameters
0121       # echo "0x80" > trace_debug_layer
0122       # echo "0x10" > trace_debug_level
0123       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
0124       # echo "method" > trace_state
0125 
0126 c. Filter out the method start/stop "AML tracer" logs when the specified
0127    control method is being evaluated for the first time::
0128 
0129       # cd /sys/module/acpi/parameters
0130       # echo "0x80" > trace_debug_layer
0131       # echo "0x10" > trace_debug_level
0132       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
0133       # echo "method-once" > trace_state
0134 
0135 d. Filter out the method/opcode start/stop "AML tracer" when the
0136    specified control method is being evaluated::
0137 
0138       # cd /sys/module/acpi/parameters
0139       # echo "0x80" > trace_debug_layer
0140       # echo "0x10" > trace_debug_level
0141       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
0142       # echo "opcode" > trace_state
0143 
0144 e. Filter out the method/opcode start/stop "AML tracer" when the
0145    specified control method is being evaluated for the first time::
0146 
0147       # cd /sys/module/acpi/parameters
0148       # echo "0x80" > trace_debug_layer
0149       # echo "0x10" > trace_debug_level
0150       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
0151       # echo "opcode-opcode" > trace_state
0152 
0153 Note that all above method tracing facility related module parameters can
0154 be used as the boot parameters, for example::
0155 
0156    acpi.trace_debug_layer=0x80 acpi.trace_debug_level=0x10 \
0157    acpi.trace_method_name=\_SB.LID0._LID acpi.trace_state=opcode-once
0158 
0159 
0160 Interface descriptions
0161 ======================
0162 
0163 All method tracing functions can be configured via ACPI module
0164 parameters that are accessible at /sys/module/acpi/parameters/:
0165 
0166 trace_method_name
0167   The full path of the AML method that the user wants to trace.
0168 
0169   Note that the full path shouldn't contain the trailing "_"s in its
0170   name segments but may contain "\" to form an absolute path.
0171 
0172 trace_debug_layer
0173   The temporary debug_layer used when the tracing feature is enabled.
0174 
0175   Using ACPI_EXECUTER (0x80) by default, which is the debug_layer
0176   used to match all "AML tracer" logs.
0177 
0178 trace_debug_level
0179   The temporary debug_level used when the tracing feature is enabled.
0180 
0181   Using ACPI_LV_TRACE_POINT (0x10) by default, which is the
0182   debug_level used to match all "AML tracer" logs.
0183 
0184 trace_state
0185   The status of the tracing feature.
0186 
0187   Users can enable/disable this debug tracing feature by executing
0188   the following command::
0189 
0190    # echo string > /sys/module/acpi/parameters/trace_state
0191 
0192 Where "string" should be one of the following:
0193 
0194 "disable"
0195   Disable the method tracing feature.
0196 
0197 "enable"
0198   Enable the method tracing feature.
0199   
0200   ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
0201   during any method execution will be logged.
0202 
0203 "method"
0204   Enable the method tracing feature.
0205 
0206   ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
0207   during method execution of "trace_method_name" will be logged.
0208 
0209 "method-once"
0210   Enable the method tracing feature.
0211 
0212   ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
0213   during method execution of "trace_method_name" will be logged only once.
0214 
0215 "opcode"
0216   Enable the method tracing feature.
0217 
0218   ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
0219   during method/opcode execution of "trace_method_name" will be logged.
0220 
0221 "opcode-once"
0222   Enable the method tracing feature.
0223 
0224   ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
0225   during method/opcode execution of "trace_method_name" will be logged only
0226   once.
0227 
0228 Note that, the difference between the "enable" and other feature
0229 enabling options are:
0230 
0231 1. When "enable" is specified, since
0232    "trace_debug_layer/trace_debug_level" shall apply to all control
0233    method evaluations, after configuring "trace_state" to "enable",
0234    "trace_method_name" will be reset to NULL.
0235 2. When "method/opcode" is specified, if
0236    "trace_method_name" is NULL when "trace_state" is configured to
0237    these options, the "trace_debug_layer/trace_debug_level" will
0238    apply to all control method evaluations.