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.