1.. SPDX-License-Identifier: GPL-2.0 2.. include:: <isonum.txt> 3 4===================== 5ACPICA Trace Facility 6===================== 7 8:Copyright: |copy| 2015, Intel Corporation 9:Author: Lv Zheng <lv.zheng@intel.com> 10 11 12Abstract 13======== 14This document describes the functions and the interfaces of the 15method tracing facility. 16 17Functionalities and usage examples 18================================== 19 20ACPICA provides method tracing capability. And two functions are 21currently implemented using this capability. 22 23Log reducer 24----------- 25 26ACPICA subsystem provides debugging outputs when CONFIG_ACPI_DEBUG is 27enabled. The debugging messages which are deployed via 28ACPI_DEBUG_PRINT() macro can be reduced at 2 levels - per-component 29level (known as debug layer, configured via 30/sys/module/acpi/parameters/debug_layer) and per-type level (known as 31debug level, configured via /sys/module/acpi/parameters/debug_level). 32 33But when the particular layer/level is applied to the control method 34evaluations, the quantity of the debugging outputs may still be too 35large to be put into the kernel log buffer. The idea thus is worked out 36to only enable the particular debug layer/level (normally more detailed) 37logs when the control method evaluation is started, and disable the 38detailed 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 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 51b. 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 60c. 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 69Where: 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 77AML tracer 78---------- 79 80There are special log entries added by the method tracing facility at 81the "trace points" the AML interpreter starts/stops to execute a control 82method, or an AML opcode. Note that the format of the log entries are 83subject 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 AML 101interpretation, thus can aid issue debugging and performance tuning. Note 102that, as the "AML tracer" logs are implemented via ACPI_DEBUG_PRINT() 103macro, CONFIG_ACPI_DEBUG is also required to be enabled for enabling 104"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 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 117b. 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 126c. 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 135d. 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 144e. 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 153Note that all above method tracing facility related module parameters can 154be 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 160Interface descriptions 161====================== 162 163All method tracing functions can be configured via ACPI module 164parameters that are accessible at /sys/module/acpi/parameters/: 165 166trace_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 172trace_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 178trace_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 184trace_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 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 only 226 once. 227 228Note that, the difference between the "enable" and other feature 229enabling options are: 230 2311. 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. 2352. 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. 239