tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
ACPI / Documentation: Update method tracing documentation.
This patch updates method tracing documentation.
Signed-off-by: Lv Zheng <lv.zheng@intel.com>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
authored by
Lv Zheng
and committed by
Rafael J. Wysocki
cb4ff766
a0186bcf
+187
-21
+187
-21
Documentation/acpi/method-tracing.txt
+187
-21
Documentation/acpi/method-tracing.txt
···
1
-
/sys/module/acpi/parameters/:
1
+
ACPICA Trace Facility
2
2
3
-
trace_method_name
4
-
The AML method name that the user wants to trace
3
+
Copyright (C) 2015, Intel Corporation
4
+
Author: Lv Zheng <lv.zheng@intel.com>
5
5
6
-
trace_debug_layer
7
-
The temporary debug_layer used when tracing the method.
8
-
Using 0xffffffff by default if it is 0.
9
6
10
-
trace_debug_level
11
-
The temporary debug_level used when tracing the method.
12
-
Using 0x00ffffff by default if it is 0.
7
+
Abstract:
13
8
14
-
trace_state
9
+
This document describes the functions and the interfaces of the method
10
+
tracing facility.
11
+
12
+
1. 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
+
130
+
2. 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
15
151
The status of the tracing feature.
16
-
17
-
"enabled" means this feature is enabled
18
-
and the AML method is traced every time it's executed.
19
-
20
-
"1" means this feature is enabled and the AML method
21
-
will only be traced during the next execution.
22
-
23
-
"disabled" means this feature is disabled.
24
-
Users can enable/disable this debug tracing feature by
25
-
"echo string > /sys/module/acpi/parameters/trace_state".
26
-
"string" should be one of "enable", "disable" and "1".
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.