Commit | Line | Data |
---|---|---|
cb4ff766 | 1 | ACPICA Trace Facility |
b4d2730a | 2 | |
cb4ff766 LZ |
3 | Copyright (C) 2015, Intel Corporation |
4 | Author: Lv Zheng <lv.zheng@intel.com> | |
b4d2730a | 5 | |
b4d2730a | 6 | |
cb4ff766 | 7 | Abstract: |
b4d2730a | 8 | |
cb4ff766 LZ |
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. | |
b4d2730a | 81 | |
cb4ff766 LZ |
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. | |
b4d2730a | 87 | |
cb4ff766 LZ |
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 | |
b4d2730a | 124 | |
cb4ff766 LZ |
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 | |
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. |