239 lines · plain
1.. SPDX-License-Identifier: GPL-2.02.. include:: <isonum.txt>3 4=====================5ACPICA Trace Facility6=====================7 8:Copyright: |copy| 2015, Intel Corporation9:Author: Lv Zheng <lv.zheng@intel.com>10 11 12Abstract13========14This document describes the functions and the interfaces of the15method tracing facility.16 17Functionalities and usage examples18==================================19 20ACPICA provides method tracing capability. And two functions are21currently implemented using this capability.22 23Log reducer24-----------25 26ACPICA subsystem provides debugging outputs when CONFIG_ACPI_DEBUG is27enabled. The debugging messages which are deployed via28ACPI_DEBUG_PRINT() macro can be reduced at 2 levels - per-component29level (known as debug layer, configured via30/sys/module/acpi/parameters/debug_layer) and per-type level (known as31debug level, configured via /sys/module/acpi/parameters/debug_level).32 33But when the particular layer/level is applied to the control method34evaluations, the quantity of the debugging outputs may still be too35large to be put into the kernel log buffer. The idea thus is worked out36to only enable the particular debug layer/level (normally more detailed)37logs when the control method evaluation is started, and disable the38detailed logging when the control method evaluation is stopped.39 40The following command examples illustrate the usage of the "log reducer"41functionality:42 43a. Filter out the debug layer/level matched logs when control methods44 are being evaluated::45 46 # cd /sys/module/acpi/parameters47 # echo "0xXXXXXXXX" > trace_debug_layer48 # echo "0xYYYYYYYY" > trace_debug_level49 # echo "enable" > trace_state50 51b. Filter out the debug layer/level matched logs when the specified52 control method is being evaluated::53 54 # cd /sys/module/acpi/parameters55 # echo "0xXXXXXXXX" > trace_debug_layer56 # echo "0xYYYYYYYY" > trace_debug_level57 # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name58 # echo "method" > /sys/module/acpi/parameters/trace_state59 60c. Filter out the debug layer/level matched logs when the specified61 control method is being evaluated for the first time::62 63 # cd /sys/module/acpi/parameters64 # echo "0xXXXXXXXX" > trace_debug_layer65 # echo "0xYYYYYYYY" > trace_debug_level66 # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name67 # echo "method-once" > /sys/module/acpi/parameters/trace_state68 69Where:70 0xXXXXXXXX/0xYYYYYYYY71 Refer to Documentation/firmware-guide/acpi/debug.rst for possible debug layer/level72 masking values.73 \PPPP.AAAA.TTTT.HHHH74 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 77AML tracer78----------79 80There are special log entries added by the method tracing facility at81the "trace points" the AML interpreter starts/stops to execute a control82method, or an AML opcode. Note that the format of the log entries are83subject 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 100Developers can utilize these special log entries to track the AML101interpretation, thus can aid issue debugging and performance tuning. Note102that, as the "AML tracer" logs are implemented via ACPI_DEBUG_PRINT()103macro, CONFIG_ACPI_DEBUG is also required to be enabled for enabling104"AML tracer" logs.105 106The following command examples illustrate the usage of the "AML tracer"107functionality:108 109a. Filter out the method start/stop "AML tracer" logs when control110 methods are being evaluated::111 112 # cd /sys/module/acpi/parameters113 # echo "0x80" > trace_debug_layer114 # echo "0x10" > trace_debug_level115 # echo "enable" > trace_state116 117b. Filter out the method start/stop "AML tracer" when the specified118 control method is being evaluated::119 120 # cd /sys/module/acpi/parameters121 # echo "0x80" > trace_debug_layer122 # echo "0x10" > trace_debug_level123 # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name124 # echo "method" > trace_state125 126c. Filter out the method start/stop "AML tracer" logs when the specified127 control method is being evaluated for the first time::128 129 # cd /sys/module/acpi/parameters130 # echo "0x80" > trace_debug_layer131 # echo "0x10" > trace_debug_level132 # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name133 # echo "method-once" > trace_state134 135d. Filter out the method/opcode start/stop "AML tracer" when the136 specified control method is being evaluated::137 138 # cd /sys/module/acpi/parameters139 # echo "0x80" > trace_debug_layer140 # echo "0x10" > trace_debug_level141 # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name142 # echo "opcode" > trace_state143 144e. Filter out the method/opcode start/stop "AML tracer" when the145 specified control method is being evaluated for the first time::146 147 # cd /sys/module/acpi/parameters148 # echo "0x80" > trace_debug_layer149 # echo "0x10" > trace_debug_level150 # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name151 # echo "opcode-opcode" > trace_state152 153Note that all above method tracing facility related module parameters can154be 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-once158 159 160Interface descriptions161======================162 163All method tracing functions can be configured via ACPI module164parameters that are accessible at /sys/module/acpi/parameters/:165 166trace_method_name167 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 its170 name segments but may contain "\" to form an absolute path.171 172trace_debug_layer173 The temporary debug_layer used when the tracing feature is enabled.174 175 Using ACPI_EXECUTER (0x80) by default, which is the debug_layer176 used to match all "AML tracer" logs.177 178trace_debug_level179 The temporary debug_level used when the tracing feature is enabled.180 181 Using ACPI_LV_TRACE_POINT (0x10) by default, which is the182 debug_level used to match all "AML tracer" logs.183 184trace_state185 The status of the tracing feature.186 187 Users can enable/disable this debug tracing feature by executing188 the following command::189 190 # echo string > /sys/module/acpi/parameters/trace_state191 192Where "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 only226 once.227 228Note that, the difference between the "enable" and other feature229enabling options are:230 2311. When "enable" is specified, since232 "trace_debug_layer/trace_debug_level" shall apply to all control233 method evaluations, after configuring "trace_state" to "enable",234 "trace_method_name" will be reset to NULL.2352. When "method/opcode" is specified, if236 "trace_method_name" is NULL when "trace_state" is configured to237 these options, the "trace_debug_layer/trace_debug_level" will238 apply to all control method evaluations.239