diff mbox series

[v4,17/63] Documentation: ACPI: move method-tracing.txt to firmware-guide/acpi and convert to rsST

Message ID 20190423162932.21428-18-changbin.du@gmail.com (mailing list archive)
State New, archived
Delegated to: Bjorn Helgaas
Headers show
Series Include linux ACPI/PCI/X86 docs into Sphinx TOC tree | expand

Commit Message

Changbin Du April 23, 2019, 4:28 p.m. UTC
This converts the plain text documentation to reStructuredText format and
add it to Sphinx TOC tree. No essential content change.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
---
 Documentation/acpi/method-tracing.txt         | 192 ---------------
 Documentation/firmware-guide/acpi/index.rst   |   1 +
 .../firmware-guide/acpi/method-tracing.rst    | 225 ++++++++++++++++++
 3 files changed, 226 insertions(+), 192 deletions(-)
 delete mode 100644 Documentation/acpi/method-tracing.txt
 create mode 100644 Documentation/firmware-guide/acpi/method-tracing.rst

Comments

Mauro Carvalho Chehab April 24, 2019, 2:26 p.m. UTC | #1
Em Wed, 24 Apr 2019 00:28:46 +0800
Changbin Du <changbin.du@gmail.com> escreveu:

> This converts the plain text documentation to reStructuredText format and
> add it to Sphinx TOC tree. No essential content change.
> 
> Signed-off-by: Changbin Du <changbin.du@gmail.com>
> ---
>  Documentation/acpi/method-tracing.txt         | 192 ---------------
>  Documentation/firmware-guide/acpi/index.rst   |   1 +
>  .../firmware-guide/acpi/method-tracing.rst    | 225 ++++++++++++++++++
>  3 files changed, 226 insertions(+), 192 deletions(-)
>  delete mode 100644 Documentation/acpi/method-tracing.txt
>  create mode 100644 Documentation/firmware-guide/acpi/method-tracing.rst
> 
> diff --git a/Documentation/acpi/method-tracing.txt b/Documentation/acpi/method-tracing.txt
> deleted file mode 100644
> index 0aba14c8f459..000000000000
> --- a/Documentation/acpi/method-tracing.txt
> +++ /dev/null
> @@ -1,192 +0,0 @@
> -ACPICA Trace Facility
> -
> -Copyright (C) 2015, Intel Corporation
> -Author: Lv Zheng <lv.zheng@intel.com>
> -
> -
> -Abstract:
> -
> -This document describes the functions and the interfaces of the method
> -tracing facility.
> -
> -1. Functionalities and usage examples:
> -
> -   ACPICA provides method tracing capability. And two functions are
> -   currently implemented using this capability.
> -
> -   A. 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/acpi/debug.txt 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.
> -
> -   B. 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
> -   interpretion, 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
> -
> -2. 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.
> diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> index a45fea11f998..287a7cbd82ac 100644
> --- a/Documentation/firmware-guide/acpi/index.rst
> +++ b/Documentation/firmware-guide/acpi/index.rst
> @@ -13,6 +13,7 @@ ACPI Support
>     enumeration
>     osi
>     method-customizing
> +   method-tracing
>     DSD-properties-rules
>     debug
>     gpio-properties
> diff --git a/Documentation/firmware-guide/acpi/method-tracing.rst b/Documentation/firmware-guide/acpi/method-tracing.rst
> new file mode 100644
> index 000000000000..7a997ba168d7
> --- /dev/null
> +++ b/Documentation/firmware-guide/acpi/method-tracing.rst
> @@ -0,0 +1,225 @@
> +.. 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.

Same comment as on other patches.

> +
> +1. 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/acpi/debug.txt 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
> +-------------

The markup is bigger than the line. You should have seen a Sphinx
warning here.

> +
> +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
> +interpretion, 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
> +
> +2. 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::

For the above, please indent, in order to properly change the
sysfs node font to bold. Also, mark paragraphs with a \n, e. g:

   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::

After doing such changes:

Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>


> +
> +   # 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.



Thanks,
Mauro
Changbin Du April 24, 2019, 4:55 p.m. UTC | #2
On Wed, Apr 24, 2019 at 11:26:38AM -0300, Mauro Carvalho Chehab wrote:
> Em Wed, 24 Apr 2019 00:28:46 +0800
> Changbin Du <changbin.du@gmail.com> escreveu:
> 
> > This converts the plain text documentation to reStructuredText format and
> > add it to Sphinx TOC tree. No essential content change.
> > 
> > Signed-off-by: Changbin Du <changbin.du@gmail.com>
> > ---
> >  Documentation/acpi/method-tracing.txt         | 192 ---------------
> >  Documentation/firmware-guide/acpi/index.rst   |   1 +
> >  .../firmware-guide/acpi/method-tracing.rst    | 225 ++++++++++++++++++
> >  3 files changed, 226 insertions(+), 192 deletions(-)
> >  delete mode 100644 Documentation/acpi/method-tracing.txt
> >  create mode 100644 Documentation/firmware-guide/acpi/method-tracing.rst
> > 
> > diff --git a/Documentation/acpi/method-tracing.txt b/Documentation/acpi/method-tracing.txt
> > deleted file mode 100644
> > index 0aba14c8f459..000000000000
> > --- a/Documentation/acpi/method-tracing.txt
> > +++ /dev/null
> > @@ -1,192 +0,0 @@
> > -ACPICA Trace Facility
> > -
> > -Copyright (C) 2015, Intel Corporation
> > -Author: Lv Zheng <lv.zheng@intel.com>
> > -
> > -
> > -Abstract:
> > -
> > -This document describes the functions and the interfaces of the method
> > -tracing facility.
> > -
> > -1. Functionalities and usage examples:
> > -
> > -   ACPICA provides method tracing capability. And two functions are
> > -   currently implemented using this capability.
> > -
> > -   A. 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/acpi/debug.txt 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.
> > -
> > -   B. 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
> > -   interpretion, 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
> > -
> > -2. 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.
> > diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> > index a45fea11f998..287a7cbd82ac 100644
> > --- a/Documentation/firmware-guide/acpi/index.rst
> > +++ b/Documentation/firmware-guide/acpi/index.rst
> > @@ -13,6 +13,7 @@ ACPI Support
> >     enumeration
> >     osi
> >     method-customizing
> > +   method-tracing
> >     DSD-properties-rules
> >     debug
> >     gpio-properties
> > diff --git a/Documentation/firmware-guide/acpi/method-tracing.rst b/Documentation/firmware-guide/acpi/method-tracing.rst
> > new file mode 100644
> > index 000000000000..7a997ba168d7
> > --- /dev/null
> > +++ b/Documentation/firmware-guide/acpi/method-tracing.rst
> > @@ -0,0 +1,225 @@
> > +.. 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.
> 
> Same comment as on other patches.
>
Fixed, thanks.

> > +
> > +1. 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/acpi/debug.txt 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
> > +-------------
> 
> The markup is bigger than the line. You should have seen a Sphinx
> warning here.
> 
> > +
> > +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
> > +interpretion, 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
> > +
> > +2. 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::
> 
> For the above, please indent, in order to properly change the
> sysfs node font to bold. Also, mark paragraphs with a \n, e. g:
> 
>    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::
> 
Done, thanks.

> After doing such changes:
> 
> Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> 
> 
> > +
> > +   # 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.
> 
> 
> 
> Thanks,
> Mauro
diff mbox series

Patch

diff --git a/Documentation/acpi/method-tracing.txt b/Documentation/acpi/method-tracing.txt
deleted file mode 100644
index 0aba14c8f459..000000000000
--- a/Documentation/acpi/method-tracing.txt
+++ /dev/null
@@ -1,192 +0,0 @@ 
-ACPICA Trace Facility
-
-Copyright (C) 2015, Intel Corporation
-Author: Lv Zheng <lv.zheng@intel.com>
-
-
-Abstract:
-
-This document describes the functions and the interfaces of the method
-tracing facility.
-
-1. Functionalities and usage examples:
-
-   ACPICA provides method tracing capability. And two functions are
-   currently implemented using this capability.
-
-   A. 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/acpi/debug.txt 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.
-
-   B. 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
-   interpretion, 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
-
-2. 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.
diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
index a45fea11f998..287a7cbd82ac 100644
--- a/Documentation/firmware-guide/acpi/index.rst
+++ b/Documentation/firmware-guide/acpi/index.rst
@@ -13,6 +13,7 @@  ACPI Support
    enumeration
    osi
    method-customizing
+   method-tracing
    DSD-properties-rules
    debug
    gpio-properties
diff --git a/Documentation/firmware-guide/acpi/method-tracing.rst b/Documentation/firmware-guide/acpi/method-tracing.rst
new file mode 100644
index 000000000000..7a997ba168d7
--- /dev/null
+++ b/Documentation/firmware-guide/acpi/method-tracing.rst
@@ -0,0 +1,225 @@ 
+.. 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.
+
+1. 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/acpi/debug.txt 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
+interpretion, 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
+
+2. 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.