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