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

Mauro Carvalho Chehab
2019-04-23T21:21:08Z

Em Wed, 24 Apr 2019 00:28:45 +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>
> ---
> .../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@kernel.org>

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