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

From: Mauro Carvalho Chehab
Date: Wed Apr 24 2019 - 10:26:54 EST

Next message: Laurent Dufour: "Re: [PATCH v12 20/31] mm: introduce vma reference counter"
Previous message: Dan Carpenter: "[PATCH] dma-mapping: remove an unnecessary NULL check"
Next in thread: Changbin Du: "Re: [PATCH v4 17/63] Documentation: ACPI: move method-tracing.txt to firmware-guide/acpi and convert to rsST"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

Em Wed, 24 Apr 2019 00:28:46 +0800
Changbin Du <changbin.du@xxxxxxxxx> 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@xxxxxxxxx>
> ---
> 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@xxxxxxxxx>
> -
> -
> -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@xxxxxxxxx>
> +
> +
> +: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@xxxxxxxxxx>

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

Next message: Laurent Dufour: "Re: [PATCH v12 20/31] mm: introduce vma reference counter"
Previous message: Dan Carpenter: "[PATCH] dma-mapping: remove an unnecessary NULL check"
Next in thread: Changbin Du: "Re: [PATCH v4 17/63] Documentation: ACPI: move method-tracing.txt to firmware-guide/acpi and convert to rsST"
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]