GNU Linux-libre 6.9-gnu
[releases.git] / Documentation / firmware-guide / acpi / method-tracing.rst
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.