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

   1 .. SPDX-License-Identifier: GPL-2.0
   2 .. include:: <isonum.txt>
   3
   4 =====================
   5 ACPICA Trace Facility
   6 =====================
   7
   8 :Copyright: |copy| 2015, Intel Corporation
   9 :Author: Lv Zheng <lv.zheng@intel.com>
  10
  11
  12 Abstract
  13 ========
  14 This document describes the functions and the interfaces of the
  15 method tracing facility.
  16
  17 Functionalities and usage examples
  18 ==================================
  19
  20 ACPICA provides method tracing capability. And two functions are
  21 currently implemented using this capability.
  22
  23 Log reducer
  24 -----------
  25
  26 ACPICA subsystem provides debugging outputs when CONFIG_ACPI_DEBUG is
  27 enabled. The debugging messages which are deployed via
  28 ACPI_DEBUG_PRINT() macro can be reduced at 2 levels - per-component
  29 level (known as debug layer, configured via
  30 /sys/module/acpi/parameters/debug_layer) and per-type level (known as
  31 debug level, configured via /sys/module/acpi/parameters/debug_level).
  32
  33 But when the particular layer/level is applied to the control method
  34 evaluations, the quantity of the debugging outputs may still be too
  35 large to be put into the kernel log buffer. The idea thus is worked out
  36 to only enable the particular debug layer/level (normally more detailed)
  37 logs when the control method evaluation is started, and disable the
  38 detailed logging when the control method evaluation is stopped.
  39
  40 The following command examples illustrate the usage of the "log reducer"
  41 functionality:
  42
  43 a. Filter out the debug layer/level matched logs when control methods
  44    are being evaluated::
  45
  46       # cd /sys/module/acpi/parameters
  47       # echo "0xXXXXXXXX" > trace_debug_layer
  48       # echo "0xYYYYYYYY" > trace_debug_level
  49       # echo "enable" > trace_state
  50
  51 b. Filter out the debug layer/level matched logs when the specified
  52    control method is being evaluated::
  53
  54       # cd /sys/module/acpi/parameters
  55       # echo "0xXXXXXXXX" > trace_debug_layer
  56       # echo "0xYYYYYYYY" > trace_debug_level
  57       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
  58       # echo "method" > /sys/module/acpi/parameters/trace_state
  59
  60 c. Filter out the debug layer/level matched logs when the specified
  61    control method is being evaluated for the first time::
  62
  63       # cd /sys/module/acpi/parameters
  64       # echo "0xXXXXXXXX" > trace_debug_layer
  65       # echo "0xYYYYYYYY" > trace_debug_level
  66       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
  67       # echo "method-once" > /sys/module/acpi/parameters/trace_state
  68
  69 Where:
  70    0xXXXXXXXX/0xYYYYYYYY
  71      Refer to Documentation/firmware-guide/acpi/debug.rst for possible debug layer/level
  72      masking values.
  73    \PPPP.AAAA.TTTT.HHHH
  74      Full path of a control method that can be found in the ACPI namespace.
  75      It needn't be an entry of a control method evaluation.
  76
  77 AML tracer
  78 ----------
  79
  80 There are special log entries added by the method tracing facility at
  81 the "trace points" the AML interpreter starts/stops to execute a control
  82 method, or an AML opcode. Note that the format of the log entries are
  83 subject to change::
  84
  85    [    0.186427]   exdebug-0398 ex_trace_point        : Method Begin [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
  86    [    0.186630]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905c88:If] execution.
  87    [    0.186820]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905cc0:LEqual] execution.
  88    [    0.187010]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905a20:-NamePath-] execution.
  89    [    0.187214]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905a20:-NamePath-] execution.
  90    [    0.187407]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905f60:One] execution.
  91    [    0.187594]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905f60:One] execution.
  92    [    0.187789]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905cc0:LEqual] execution.
  93    [    0.187980]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905cc0:Return] execution.
  94    [    0.188146]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905f60:One] execution.
  95    [    0.188334]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905f60:One] execution.
  96    [    0.188524]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905cc0:Return] execution.
  97    [    0.188712]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905c88:If] execution.
  98    [    0.188903]   exdebug-0398 ex_trace_point        : Method End [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
  99
 100 Developers can utilize these special log entries to track the AML
 101 interpretion, thus can aid issue debugging and performance tuning. Note
 102 that, as the "AML tracer" logs are implemented via ACPI_DEBUG_PRINT()
 103 macro, CONFIG_ACPI_DEBUG is also required to be enabled for enabling
 104 "AML tracer" logs.
 105
 106 The following command examples illustrate the usage of the "AML tracer"
 107 functionality:
 108
 109 a. Filter out the method start/stop "AML tracer" logs when control
 110    methods are being evaluated::
 111
 112       # cd /sys/module/acpi/parameters
 113       # echo "0x80" > trace_debug_layer
 114       # echo "0x10" > trace_debug_level
 115       # echo "enable" > trace_state
 116
 117 b. Filter out the method start/stop "AML tracer" when the specified
 118    control method is being evaluated::
 119
 120       # cd /sys/module/acpi/parameters
 121       # echo "0x80" > trace_debug_layer
 122       # echo "0x10" > trace_debug_level
 123       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
 124       # echo "method" > trace_state
 125
 126 c. Filter out the method start/stop "AML tracer" logs when the specified
 127    control method is being evaluated for the first time::
 128
 129       # cd /sys/module/acpi/parameters
 130       # echo "0x80" > trace_debug_layer
 131       # echo "0x10" > trace_debug_level
 132       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
 133       # echo "method-once" > trace_state
 134
 135 d. Filter out the method/opcode start/stop "AML tracer" when the
 136    specified control method is being evaluated::
 137
 138       # cd /sys/module/acpi/parameters
 139       # echo "0x80" > trace_debug_layer
 140       # echo "0x10" > trace_debug_level
 141       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
 142       # echo "opcode" > trace_state
 143
 144 e. Filter out the method/opcode start/stop "AML tracer" when the
 145    specified control method is being evaluated for the first time::
 146
 147       # cd /sys/module/acpi/parameters
 148       # echo "0x80" > trace_debug_layer
 149       # echo "0x10" > trace_debug_level
 150       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
 151       # echo "opcode-opcode" > trace_state
 152
 153 Note that all above method tracing facility related module parameters can
 154 be used as the boot parameters, for example::
 155
 156    acpi.trace_debug_layer=0x80 acpi.trace_debug_level=0x10 \
 157    acpi.trace_method_name=\_SB.LID0._LID acpi.trace_state=opcode-once
 158
 159
 160 Interface descriptions
 161 ======================
 162
 163 All method tracing functions can be configured via ACPI module
 164 parameters that are accessible at /sys/module/acpi/parameters/:
 165
 166 trace_method_name
 167   The full path of the AML method that the user wants to trace.
 168
 169   Note that the full path shouldn't contain the trailing "_"s in its
 170   name segments but may contain "\" to form an absolute path.
 171
 172 trace_debug_layer
 173   The temporary debug_layer used when the tracing feature is enabled.
 174
 175   Using ACPI_EXECUTER (0x80) by default, which is the debug_layer
 176   used to match all "AML tracer" logs.
 177
 178 trace_debug_level
 179   The temporary debug_level used when the tracing feature is enabled.
 180
 181   Using ACPI_LV_TRACE_POINT (0x10) by default, which is the
 182   debug_level used to match all "AML tracer" logs.
 183
 184 trace_state
 185   The status of the tracing feature.
 186
 187   Users can enable/disable this debug tracing feature by executing
 188   the following command::
 189
 190    # echo string > /sys/module/acpi/parameters/trace_state
 191
 192 Where "string" should be one of the following:
 193
 194 "disable"
 195   Disable the method tracing feature.
 196
 197 "enable"
 198   Enable the method tracing feature.
 199
 200   ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
 201   during any method execution will be logged.
 202
 203 "method"
 204   Enable the method tracing feature.
 205
 206   ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
 207   during method execution of "trace_method_name" will be logged.
 208
 209 "method-once"
 210   Enable the method tracing feature.
 211
 212   ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
 213   during method execution of "trace_method_name" will be logged only once.
 214
 215 "opcode"
 216   Enable the method tracing feature.
 217
 218   ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
 219   during method/opcode execution of "trace_method_name" will be logged.
 220
 221 "opcode-once"
 222   Enable the method tracing feature.
 223
 224   ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
 225   during method/opcode execution of "trace_method_name" will be logged only
 226   once.
 227
 228 Note that, the difference between the "enable" and other feature
 229 enabling options are:
 230
 231 1. When "enable" is specified, since
 232    "trace_debug_layer/trace_debug_level" shall apply to all control
 233    method evaluations, after configuring "trace_state" to "enable",
 234    "trace_method_name" will be reset to NULL.
 235 2. When "method/opcode" is specified, if
 236    "trace_method_name" is NULL when "trace_state" is configured to
 237    these options, the "trace_debug_layer/trace_debug_level" will
 238    apply to all control method evaluations.