About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / acpi / method-tracing.txt




Custom Search

Based on kernel version 4.3. Page generated on 2015-11-02 12:43 EST.

1	ACPICA Trace Facility
2	
3	Copyright (C) 2015, Intel Corporation
4	Author: Lv Zheng <lv.zheng@intel.com>
5	
6	
7	Abstract:
8	
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
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.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.