lkml.org 
[lkml]   [2019]   [Apr]   [23]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v4 17/63] Documentation: ACPI: move method-tracing.txt to firmware-guide/acpi and convert to rsST
    Date
    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.
    +
    +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.
    --
    2.20.1
    \
     
     \ /
      Last update: 2019-04-23 18:33    [W:3.773 / U:0.012 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site