Documentation/firmware-guide/acpi/method-tracing.rst - third_party/kernel - Git at Google

 .. SPDX-License-Identifier: GPL-2.0
 .. include:: <isonum.txt>

 =====================
 ACPICA Trace Facility
 =====================

 :Copyright: |copy| 2015, Intel Corporation
 :Author: Lv Zheng <lv.zheng@intel.com>


 Abstract
 ========
 This document describes the functions and the interfaces of the
 method tracing facility.

 Functionalities and usage examples
 ==================================

 ACPICA provides method tracing capability. And two functions are
 currently implemented using this capability.

 Log reducer
 -----------

 ACPICA subsystem provides debugging outputs when CONFIG_ACPI_DEBUG is
 enabled. The debugging messages which are deployed via
 ACPI_DEBUG_PRINT() macro can be reduced at 2 levels - per-component
 level (known as debug layer, configured via
 /sys/module/acpi/parameters/debug_layer) and per-type level (known as
 debug level, configured via /sys/module/acpi/parameters/debug_level).

 But when the particular layer/level is applied to the control method
 evaluations, the quantity of the debugging outputs may still be too
 large to be put into the kernel log buffer. The idea thus is worked out
 to only enable the particular debug layer/level (normally more detailed)
 logs when the control method evaluation is started, and disable the
 detailed logging when the control method evaluation is stopped.

 The following command examples illustrate the usage of the "log reducer"
 functionality:

 a. Filter out the debug layer/level matched logs when control methods
    are being evaluated::

       # cd /sys/module/acpi/parameters
       # echo "0xXXXXXXXX" > trace_debug_layer
       # echo "0xYYYYYYYY" > trace_debug_level
       # echo "enable" > trace_state

 b. Filter out the debug layer/level matched logs when the specified
    control method is being evaluated::

       # cd /sys/module/acpi/parameters
       # echo "0xXXXXXXXX" > trace_debug_layer
       # echo "0xYYYYYYYY" > trace_debug_level
       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
       # echo "method" > /sys/module/acpi/parameters/trace_state

 c. Filter out the debug layer/level matched logs when the specified
    control method is being evaluated for the first time::

       # cd /sys/module/acpi/parameters
       # echo "0xXXXXXXXX" > trace_debug_layer
       # echo "0xYYYYYYYY" > trace_debug_level
       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
       # echo "method-once" > /sys/module/acpi/parameters/trace_state

 Where:
    0xXXXXXXXX/0xYYYYYYYY
      Refer to Documentation/firmware-guide/acpi/debug.rst for possible debug layer/level
      masking values.
    \PPPP.AAAA.TTTT.HHHH
      Full path of a control method that can be found in the ACPI namespace.
      It needn't be an entry of a control method evaluation.

 AML tracer
 ----------

 There are special log entries added by the method tracing facility at
 the "trace points" the AML interpreter starts/stops to execute a control
 method, or an AML opcode. Note that the format of the log entries are
 subject to change::

    [    0.186427]   exdebug-0398 ex_trace_point        : Method Begin [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
    [    0.186630]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905c88:If] execution.
    [    0.186820]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905cc0:LEqual] execution.
    [    0.187010]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905a20:-NamePath-] execution.
    [    0.187214]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905a20:-NamePath-] execution.
    [    0.187407]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905f60:One] execution.
    [    0.187594]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905f60:One] execution.
    [    0.187789]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905cc0:LEqual] execution.
    [    0.187980]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905cc0:Return] execution.
    [    0.188146]   exdebug-0398 ex_trace_point        : Opcode Begin [0xf5905f60:One] execution.
    [    0.188334]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905f60:One] execution.
    [    0.188524]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905cc0:Return] execution.
    [    0.188712]   exdebug-0398 ex_trace_point        : Opcode End [0xf5905c88:If] execution.
    [    0.188903]   exdebug-0398 ex_trace_point        : Method End [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.

 Developers can utilize these special log entries to track the AML
 interpretation, thus can aid issue debugging and performance tuning. Note
 that, as the "AML tracer" logs are implemented via ACPI_DEBUG_PRINT()
 macro, CONFIG_ACPI_DEBUG is also required to be enabled for enabling
 "AML tracer" logs.

 The following command examples illustrate the usage of the "AML tracer"
 functionality:

 a. Filter out the method start/stop "AML tracer" logs when control
    methods are being evaluated::

       # cd /sys/module/acpi/parameters
       # echo "0x80" > trace_debug_layer
       # echo "0x10" > trace_debug_level
       # echo "enable" > trace_state

 b. Filter out the method start/stop "AML tracer" when the specified
    control method is being evaluated::

       # cd /sys/module/acpi/parameters
       # echo "0x80" > trace_debug_layer
       # echo "0x10" > trace_debug_level
       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
       # echo "method" > trace_state

 c. Filter out the method start/stop "AML tracer" logs when the specified
    control method is being evaluated for the first time::

       # cd /sys/module/acpi/parameters
       # echo "0x80" > trace_debug_layer
       # echo "0x10" > trace_debug_level
       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
       # echo "method-once" > trace_state

 d. Filter out the method/opcode start/stop "AML tracer" when the
    specified control method is being evaluated::

       # cd /sys/module/acpi/parameters
       # echo "0x80" > trace_debug_layer
       # echo "0x10" > trace_debug_level
       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
       # echo "opcode" > trace_state

 e. Filter out the method/opcode start/stop "AML tracer" when the
    specified control method is being evaluated for the first time::

       # cd /sys/module/acpi/parameters
       # echo "0x80" > trace_debug_layer
       # echo "0x10" > trace_debug_level
       # echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
       # echo "opcode-opcode" > trace_state

 Note that all above method tracing facility related module parameters can
 be used as the boot parameters, for example::

    acpi.trace_debug_layer=0x80 acpi.trace_debug_level=0x10 \
    acpi.trace_method_name=\_SB.LID0._LID acpi.trace_state=opcode-once


 Interface descriptions
 ======================

 All method tracing functions can be configured via ACPI module
 parameters that are accessible at /sys/module/acpi/parameters/:

 trace_method_name
   The full path of the AML method that the user wants to trace.

   Note that the full path shouldn't contain the trailing "_"s in its
   name segments but may contain "\" to form an absolute path.

 trace_debug_layer
   The temporary debug_layer used when the tracing feature is enabled.

   Using ACPI_EXECUTER (0x80) by default, which is the debug_layer
   used to match all "AML tracer" logs.

 trace_debug_level
   The temporary debug_level used when the tracing feature is enabled.

   Using ACPI_LV_TRACE_POINT (0x10) by default, which is the
   debug_level used to match all "AML tracer" logs.

 trace_state
   The status of the tracing feature.

   Users can enable/disable this debug tracing feature by executing
   the following command::

    # echo string > /sys/module/acpi/parameters/trace_state

 Where "string" should be one of the following:

 "disable"
   Disable the method tracing feature.

 "enable"
   Enable the method tracing feature.

   ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
   during any method execution will be logged.

 "method"
   Enable the method tracing feature.

   ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
   during method execution of "trace_method_name" will be logged.

 "method-once"
   Enable the method tracing feature.

   ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
   during method execution of "trace_method_name" will be logged only once.

 "opcode"
   Enable the method tracing feature.

   ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
   during method/opcode execution of "trace_method_name" will be logged.

 "opcode-once"
   Enable the method tracing feature.

   ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
   during method/opcode execution of "trace_method_name" will be logged only
   once.

 Note that, the difference between the "enable" and other feature
 enabling options are:

 1. When "enable" is specified, since
    "trace_debug_layer/trace_debug_level" shall apply to all control
    method evaluations, after configuring "trace_state" to "enable",
    "trace_method_name" will be reset to NULL.
 2. When "method/opcode" is specified, if
    "trace_method_name" is NULL when "trace_state" is configured to
    these options, the "trace_debug_layer/trace_debug_level" will
    apply to all control method evaluations.
	.. SPDX-License-Identifier: GPL-2.0
	.. include:: <isonum.txt>

	=====================
	ACPICA Trace Facility
	=====================

	:Copyright: \|copy\| 2015, Intel Corporation
	:Author: Lv Zheng <lv.zheng@intel.com>


	Abstract
	========
	This document describes the functions and the interfaces of the
	method tracing facility.

	Functionalities and usage examples
	==================================

	ACPICA provides method tracing capability. And two functions are
	currently implemented using this capability.

	Log reducer
	-----------

	ACPICA subsystem provides debugging outputs when CONFIG_ACPI_DEBUG is
	enabled. The debugging messages which are deployed via
	ACPI_DEBUG_PRINT() macro can be reduced at 2 levels - per-component
	level (known as debug layer, configured via
	/sys/module/acpi/parameters/debug_layer) and per-type level (known as
	debug level, configured via /sys/module/acpi/parameters/debug_level).

	But when the particular layer/level is applied to the control method
	evaluations, the quantity of the debugging outputs may still be too
	large to be put into the kernel log buffer. The idea thus is worked out
	to only enable the particular debug layer/level (normally more detailed)
	logs when the control method evaluation is started, and disable the
	detailed logging when the control method evaluation is stopped.

	The following command examples illustrate the usage of the "log reducer"
	functionality:

	a. Filter out the debug layer/level matched logs when control methods
	are being evaluated::

	# cd /sys/module/acpi/parameters
	# echo "0xXXXXXXXX" > trace_debug_layer
	# echo "0xYYYYYYYY" > trace_debug_level
	# echo "enable" > trace_state

	b. Filter out the debug layer/level matched logs when the specified
	control method is being evaluated::

	# cd /sys/module/acpi/parameters
	# echo "0xXXXXXXXX" > trace_debug_layer
	# echo "0xYYYYYYYY" > trace_debug_level
	# echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
	# echo "method" > /sys/module/acpi/parameters/trace_state

	c. Filter out the debug layer/level matched logs when the specified
	control method is being evaluated for the first time::

	# cd /sys/module/acpi/parameters
	# echo "0xXXXXXXXX" > trace_debug_layer
	# echo "0xYYYYYYYY" > trace_debug_level
	# echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
	# echo "method-once" > /sys/module/acpi/parameters/trace_state

	Where:
	0xXXXXXXXX/0xYYYYYYYY
	Refer to Documentation/firmware-guide/acpi/debug.rst for possible debug layer/level
	masking values.
	\PPPP.AAAA.TTTT.HHHH
	Full path of a control method that can be found in the ACPI namespace.
	It needn't be an entry of a control method evaluation.

	AML tracer
	----------

	There are special log entries added by the method tracing facility at
	the "trace points" the AML interpreter starts/stops to execute a control
	method, or an AML opcode. Note that the format of the log entries are
	subject to change::

	[ 0.186427] exdebug-0398 ex_trace_point : Method Begin [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.
	[ 0.186630] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905c88:If] execution.
	[ 0.186820] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905cc0:LEqual] execution.
	[ 0.187010] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905a20:-NamePath-] execution.
	[ 0.187214] exdebug-0398 ex_trace_point : Opcode End [0xf5905a20:-NamePath-] execution.
	[ 0.187407] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905f60:One] execution.
	[ 0.187594] exdebug-0398 ex_trace_point : Opcode End [0xf5905f60:One] execution.
	[ 0.187789] exdebug-0398 ex_trace_point : Opcode End [0xf5905cc0:LEqual] execution.
	[ 0.187980] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905cc0:Return] execution.
	[ 0.188146] exdebug-0398 ex_trace_point : Opcode Begin [0xf5905f60:One] execution.
	[ 0.188334] exdebug-0398 ex_trace_point : Opcode End [0xf5905f60:One] execution.
	[ 0.188524] exdebug-0398 ex_trace_point : Opcode End [0xf5905cc0:Return] execution.
	[ 0.188712] exdebug-0398 ex_trace_point : Opcode End [0xf5905c88:If] execution.
	[ 0.188903] exdebug-0398 ex_trace_point : Method End [0xf58394d8:\_SB.PCI0.LPCB.ECOK] execution.

	Developers can utilize these special log entries to track the AML
	interpretation, thus can aid issue debugging and performance tuning. Note
	that, as the "AML tracer" logs are implemented via ACPI_DEBUG_PRINT()
	macro, CONFIG_ACPI_DEBUG is also required to be enabled for enabling
	"AML tracer" logs.

	The following command examples illustrate the usage of the "AML tracer"
	functionality:

	a. Filter out the method start/stop "AML tracer" logs when control
	methods are being evaluated::

	# cd /sys/module/acpi/parameters
	# echo "0x80" > trace_debug_layer
	# echo "0x10" > trace_debug_level
	# echo "enable" > trace_state

	b. Filter out the method start/stop "AML tracer" when the specified
	control method is being evaluated::

	# cd /sys/module/acpi/parameters
	# echo "0x80" > trace_debug_layer
	# echo "0x10" > trace_debug_level
	# echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
	# echo "method" > trace_state

	c. Filter out the method start/stop "AML tracer" logs when the specified
	control method is being evaluated for the first time::

	# cd /sys/module/acpi/parameters
	# echo "0x80" > trace_debug_layer
	# echo "0x10" > trace_debug_level
	# echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
	# echo "method-once" > trace_state

	d. Filter out the method/opcode start/stop "AML tracer" when the
	specified control method is being evaluated::

	# cd /sys/module/acpi/parameters
	# echo "0x80" > trace_debug_layer
	# echo "0x10" > trace_debug_level
	# echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
	# echo "opcode" > trace_state

	e. Filter out the method/opcode start/stop "AML tracer" when the
	specified control method is being evaluated for the first time::

	# cd /sys/module/acpi/parameters
	# echo "0x80" > trace_debug_layer
	# echo "0x10" > trace_debug_level
	# echo "\PPPP.AAAA.TTTT.HHHH" > trace_method_name
	# echo "opcode-opcode" > trace_state

	Note that all above method tracing facility related module parameters can
	be used as the boot parameters, for example::

	acpi.trace_debug_layer=0x80 acpi.trace_debug_level=0x10 \
	acpi.trace_method_name=\_SB.LID0._LID acpi.trace_state=opcode-once


	Interface descriptions
	======================

	All method tracing functions can be configured via ACPI module
	parameters that are accessible at /sys/module/acpi/parameters/:

	trace_method_name
	The full path of the AML method that the user wants to trace.

	Note that the full path shouldn't contain the trailing "_"s in its
	name segments but may contain "\" to form an absolute path.

	trace_debug_layer
	The temporary debug_layer used when the tracing feature is enabled.

	Using ACPI_EXECUTER (0x80) by default, which is the debug_layer
	used to match all "AML tracer" logs.

	trace_debug_level
	The temporary debug_level used when the tracing feature is enabled.

	Using ACPI_LV_TRACE_POINT (0x10) by default, which is the
	debug_level used to match all "AML tracer" logs.

	trace_state
	The status of the tracing feature.

	Users can enable/disable this debug tracing feature by executing
	the following command::

	# echo string > /sys/module/acpi/parameters/trace_state

	Where "string" should be one of the following:

	"disable"
	Disable the method tracing feature.

	"enable"
	Enable the method tracing feature.

	ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
	during any method execution will be logged.

	"method"
	Enable the method tracing feature.

	ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
	during method execution of "trace_method_name" will be logged.

	"method-once"
	Enable the method tracing feature.

	ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
	during method execution of "trace_method_name" will be logged only once.

	"opcode"
	Enable the method tracing feature.

	ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
	during method/opcode execution of "trace_method_name" will be logged.

	"opcode-once"
	Enable the method tracing feature.

	ACPICA debugging messages matching "trace_debug_layer/trace_debug_level"
	during method/opcode execution of "trace_method_name" will be logged only
	once.

	Note that, the difference between the "enable" and other feature
	enabling options are:

	1. When "enable" is specified, since
	"trace_debug_layer/trace_debug_level" shall apply to all control
	method evaluations, after configuring "trace_state" to "enable",
	"trace_method_name" will be reset to NULL.
	2. When "method/opcode" is specified, if
	"trace_method_name" is NULL when "trace_state" is configured to
	these options, the "trace_debug_layer/trace_debug_level" will
	apply to all control method evaluations.