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