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

Changbin Du
2019-04-24T16:55:13Z

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

--
Cheers,
Changbin Du