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 interpretation, 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.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.