Re: [PATCH v4 16/63] Documentation: ACPI: move debug.txt to firmware-guide/acpi and convert to reST

[Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx>]

Em Wed, 24 Apr 2019 00:28:45 +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>
> ---
>  .../acpi/debug.rst}                           | 31 ++++++++++---------
>  Documentation/firmware-guide/acpi/index.rst   |  3 +-
>  2 files changed, 19 insertions(+), 15 deletions(-)
>  rename Documentation/{acpi/debug.txt => firmware-guide/acpi/debug.rst} (91%)
> 
> diff --git a/Documentation/acpi/debug.txt b/Documentation/firmware-guide/acpi/debug.rst
> similarity index 91%
> rename from Documentation/acpi/debug.txt
> rename to Documentation/firmware-guide/acpi/debug.rst
> index 65bf47c46b6d..1a152dd1d765 100644
> --- a/Documentation/acpi/debug.txt
> +++ b/Documentation/firmware-guide/acpi/debug.rst
> @@ -1,18 +1,21 @@
> -			ACPI Debug Output
> +.. SPDX-License-Identifier: GPL-2.0
>  
> +=================
> +ACPI Debug Output
> +=================
>  
>  The ACPI CA, the Linux ACPI core, and some ACPI drivers can generate debug
>  output.  This document describes how to use this facility.
>  
>  Compile-time configuration
> ---------------------------
> +==========================
>  
>  ACPI debug output is globally enabled by CONFIG_ACPI_DEBUG.  If this config
>  option is turned off, the debug messages are not even built into the
>  kernel.
>  
>  Boot- and run-time configuration
> ---------------------------------
> +================================
>  
>  When CONFIG_ACPI_DEBUG=y, you can select the component and level of messages
>  you're interested in.  At boot-time, use the acpi.debug_layer and
> @@ -21,7 +24,7 @@ debug_layer and debug_level files in /sys/module/acpi/parameters/ to control
>  the debug messages.
>  
>  debug_layer (component)
> ------------------------
> +=======================
>  
>  The "debug_layer" is a mask that selects components of interest, e.g., a
>  specific driver or part of the ACPI interpreter.  To build the debug_layer
> @@ -33,7 +36,7 @@ to /sys/module/acpi/parameters/debug_layer.
>  
>  The possible components are defined in include/acpi/acoutput.h and
>  include/acpi/acpi_drivers.h.  Reading /sys/module/acpi/parameters/debug_layer
> -shows the supported mask values, currently these:
> +shows the supported mask values, currently these::
>  
>      ACPI_UTILITIES                  0x00000001
>      ACPI_HARDWARE                   0x00000002
> @@ -65,7 +68,7 @@ shows the supported mask values, currently these:
>      ACPI_PROCESSOR_COMPONENT        0x20000000

This is one way of doing. The other one, with would likely produce a
better visual, would be to use tables, e. g.:

     ==============                  ==========
     ACPI_UTILITIES                  0x00000001
     ACPI_HARDWARE                   0x00000002
     ==============                  ==========

Of course, if you use tables here, you need to be consistent along
similar cases inside the document.

while both works, I prefer using tables on such cases.

Either way:

Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx>

>  
>  debug_level
> ------------
> +===========
>  
>  The "debug_level" is a mask that selects different types of messages, e.g.,
>  those related to initialization, method execution, informational messages, etc.
> @@ -81,7 +84,7 @@ to /sys/module/acpi/parameters/debug_level.
>  
>  The possible levels are defined in include/acpi/acoutput.h.  Reading
>  /sys/module/acpi/parameters/debug_level shows the supported mask values,
> -currently these:
> +currently these::
>  
>      ACPI_LV_INIT                    0x00000001
>      ACPI_LV_DEBUG_OBJECT            0x00000002
> @@ -113,9 +116,9 @@ currently these:
>      ACPI_LV_EVENTS                  0x80000000
>  
>  Examples
> ---------
> +========
>  
> -For example, drivers/acpi/bus.c contains this:
> +For example, drivers/acpi/bus.c contains this::
>  
>      #define _COMPONENT              ACPI_BUS_COMPONENT
>      ...
> @@ -127,22 +130,22 @@ statement uses ACPI_DB_INFO, which is macro based on the ACPI_LV_INFO
>  definition.)
>  
>  Enable all AML "Debug" output (stores to the Debug object while interpreting
> -AML) during boot:
> +AML) during boot::
>  
>      acpi.debug_layer=0xffffffff acpi.debug_level=0x2
>  
> -Enable PCI and PCI interrupt routing debug messages:
> +Enable PCI and PCI interrupt routing debug messages::
>  
>      acpi.debug_layer=0x400000 acpi.debug_level=0x4
>  
> -Enable all ACPI hardware-related messages:
> +Enable all ACPI hardware-related messages::
>  
>      acpi.debug_layer=0x2 acpi.debug_level=0xffffffff
>  
> -Enable all ACPI_DB_INFO messages after boot:
> +Enable all ACPI_DB_INFO messages after boot::
>  
>      # echo 0x4 > /sys/module/acpi/parameters/debug_level
>  
> -Show all valid component values:
> +Show all valid component values::
>   
>      # cat /sys/module/acpi/parameters/debug_layer
> diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> index 6d4e0df4f063..a45fea11f998 100644
> --- a/Documentation/firmware-guide/acpi/index.rst
> +++ b/Documentation/firmware-guide/acpi/index.rst
> @@ -14,6 +14,7 @@ ACPI Support
>     osi
>     method-customizing
>     DSD-properties-rules
> +   debug
>     gpio-properties
>     i2c-muxes
> -   acpi-lid
> \ No newline at end of file
> +   acpi-lid



Thanks,
Mauro