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