method-tracing.rst

  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.