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@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. > 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@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 -- Cheers, Changbin Du
