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

[Changbin Du <changbin.du@gmail.com>]

On Tue, Apr 23, 2019 at 05:38:40PM -0300, Mauro Carvalho Chehab wrote:
> Em Wed, 24 Apr 2019 00:28:31 +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/firmware-guide/acpi/index.rst   |   1 +
> >  .../acpi/namespace.rst}                       | 310 +++++++++---------
> >  2 files changed, 161 insertions(+), 150 deletions(-)
> >  rename Documentation/{acpi/namespace.txt => firmware-guide/acpi/namespace.rst} (54%)
> > 
> > diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
> > index 0ec7d072ba22..210ad8acd6df 100644
> > --- a/Documentation/firmware-guide/acpi/index.rst
> > +++ b/Documentation/firmware-guide/acpi/index.rst
> > @@ -7,3 +7,4 @@ ACPI Support
> >  .. toctree::
> >     :maxdepth: 1
> >  
> > +   namespace
> > diff --git a/Documentation/acpi/namespace.txt b/Documentation/firmware-guide/acpi/namespace.rst
> > similarity index 54%
> > rename from Documentation/acpi/namespace.txt
> > rename to Documentation/firmware-guide/acpi/namespace.rst
> > index 1860cb3865c6..443f0e5d0617 100644
> > --- a/Documentation/acpi/namespace.txt
> > +++ b/Documentation/firmware-guide/acpi/namespace.rst
> > @@ -1,85 +1,88 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +.. include:: <isonum.txt>
> > +
> > +===================================================
> >  ACPI Device Tree - Representation of ACPI Namespace
> > +===================================================
> > +
> > +:Copyright: |copy| 2013, Intel Corporation
> > +
> > +:Author: Lv Zheng <lv.zheng@intel.com>
> > +
> > +:Abstract: The Linux ACPI subsystem converts ACPI namespace objects into a Linux
> > +           device tree under the /sys/devices/LNXSYSTEM:00 and updates it upon
> > +           receiving ACPI hotplug notification events.  For each device object
> > +           in this hierarchy there is a corresponding symbolic link in the
> > +           /sys/bus/acpi/devices.
> > +           This document illustrates the structure of the ACPI device tree.
> 
> Well, this is a matter of preference. I would add Abstract as a chapter,
> as this would make it part of the top index, with can be useful. 
>
Now it becomes a chapter. Thanks.

> In any case:
> 
> Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> 
> > +
> > +:Credit:   Thanks for the help from Zhang Rui <rui.zhang@intel.com> and
> > +           Rafael J.Wysocki <rafael.j.wysocki@intel.com>.
> > +
> > +
> > +ACPI Definition Blocks
> > +======================
> > +
> > +The ACPI firmware sets up RSDP (Root System Description Pointer) in the
> > +system memory address space pointing to the XSDT (Extended System
> > +Description Table).  The XSDT always points to the FADT (Fixed ACPI
> > +Description Table) using its first entry, the data within the FADT
> > +includes various fixed-length entries that describe fixed ACPI features
> > +of the hardware.  The FADT contains a pointer to the DSDT
> > +(Differentiated System Descripition Table).  The XSDT also contains
> > +entries pointing to possibly multiple SSDTs (Secondary System
> > +Description Table).
> > +
> > +The DSDT and SSDT data is organized in data structures called definition
> > +blocks that contain definitions of various objects, including ACPI
> > +control methods, encoded in AML (ACPI Machine Language).  The data block
> > +of the DSDT along with the contents of SSDTs represents a hierarchical
> > +data structure called the ACPI namespace whose topology reflects the
> > +structure of the underlying hardware platform.
> > +
> > +The relationships between ACPI System Definition Tables described above
> > +are illustrated in the following diagram::
> > +
> > +   +---------+    +-------+    +--------+    +------------------------+
> > +   |  RSDP   | +->| XSDT  | +->|  FADT  |    |  +-------------------+ |
> > +   +---------+ |  +-------+ |  +--------+  +-|->|       DSDT        | |
> > +   | Pointer | |  | Entry |-+  | ...... |  | |  +-------------------+ |
> > +   +---------+ |  +-------+    | X_DSDT |--+ |  | Definition Blocks | |
> > +   | Pointer |-+  | ..... |    | ...... |    |  +-------------------+ |
> > +   +---------+    +-------+    +--------+    |  +-------------------+ |
> > +                  | Entry |------------------|->|       SSDT        | |
> > +                  +- - - -+                  |  +-------------------| |
> > +                  | Entry | - - - - - - - -+ |  | Definition Blocks | |
> > +                  +- - - -+                | |  +-------------------+ |
> > +                                          | |  +- - - - - - - - - -+ |
> > +                                          +-|->|       SSDT        | |
> > +                                             |  +-------------------+ |
> > +                                             |  | Definition Blocks | |
> > +                                             |  +- - - - - - - - - -+ |
> > +                                             +------------------------+
> > +                                                         |
> > +                                             OSPM Loading |
> > +                                                         \|/
> > +                                                   +----------------+
> > +                                                   | ACPI Namespace |
> > +                                                   +----------------+
> > +
> > +                  Figure 1. ACPI Definition Blocks
> > +
> > +.. note:: RSDP can also contain a pointer to the RSDT (Root System
> > +   Description Table).  Platforms provide RSDT to enable
> > +   compatibility with ACPI 1.0 operating systems.  The OS is expected
> > +   to use XSDT, if present.
> > +
> > +
> > +Example ACPI Namespace
> > +======================
> > +
> > +All definition blocks are loaded into a single namespace.  The namespace
> > +is a hierarchy of objects identified by names and paths.
> > +The following naming conventions apply to object names in the ACPI
> > +namespace:
> >  
> > -Copyright (C) 2013, Intel Corporation
> > -Author: Lv Zheng <lv.zheng@intel.com>
> > -
> > -
> > -Abstract:
> > -
> > -The Linux ACPI subsystem converts ACPI namespace objects into a Linux
> > -device tree under the /sys/devices/LNXSYSTEM:00 and updates it upon
> > -receiving ACPI hotplug notification events.  For each device object in this
> > -hierarchy there is a corresponding symbolic link in the
> > -/sys/bus/acpi/devices.
> > -This document illustrates the structure of the ACPI device tree.
> > -
> > -
> > -Credit:
> > -
> > -Thanks for the help from Zhang Rui <rui.zhang@intel.com> and Rafael J.
> > -Wysocki <rafael.j.wysocki@intel.com>.
> > -
> > -
> > -1. ACPI Definition Blocks
> > -
> > -   The ACPI firmware sets up RSDP (Root System Description Pointer) in the
> > -   system memory address space pointing to the XSDT (Extended System
> > -   Description Table).  The XSDT always points to the FADT (Fixed ACPI
> > -   Description Table) using its first entry, the data within the FADT
> > -   includes various fixed-length entries that describe fixed ACPI features
> > -   of the hardware.  The FADT contains a pointer to the DSDT
> > -   (Differentiated System Descripition Table).  The XSDT also contains
> > -   entries pointing to possibly multiple SSDTs (Secondary System
> > -   Description Table).
> > -
> > -   The DSDT and SSDT data is organized in data structures called definition
> > -   blocks that contain definitions of various objects, including ACPI
> > -   control methods, encoded in AML (ACPI Machine Language).  The data block
> > -   of the DSDT along with the contents of SSDTs represents a hierarchical
> > -   data structure called the ACPI namespace whose topology reflects the
> > -   structure of the underlying hardware platform.
> > -
> > -   The relationships between ACPI System Definition Tables described above
> > -   are illustrated in the following diagram.
> > -
> > -     +---------+    +-------+    +--------+    +------------------------+
> > -     |  RSDP   | +->| XSDT  | +->|  FADT  |    |  +-------------------+ |
> > -     +---------+ |  +-------+ |  +--------+  +-|->|       DSDT        | |
> > -     | Pointer | |  | Entry |-+  | ...... |  | |  +-------------------+ |
> > -     +---------+ |  +-------+    | X_DSDT |--+ |  | Definition Blocks | |
> > -     | Pointer |-+  | ..... |    | ...... |    |  +-------------------+ |
> > -     +---------+    +-------+    +--------+    |  +-------------------+ |
> > -                    | Entry |------------------|->|       SSDT        | |
> > -                    +- - - -+                  |  +-------------------| |
> > -                    | Entry | - - - - - - - -+ |  | Definition Blocks | |
> > -                    +- - - -+                | |  +-------------------+ |
> > -                                             | |  +- - - - - - - - - -+ |
> > -                                             +-|->|       SSDT        | |
> > -                                               |  +-------------------+ |
> > -                                               |  | Definition Blocks | |
> > -                                               |  +- - - - - - - - - -+ |
> > -                                               +------------------------+
> > -                                                           |
> > -                                              OSPM Loading |
> > -                                                          \|/
> > -                                                    +----------------+
> > -                                                    | ACPI Namespace |
> > -                                                    +----------------+
> > -
> > -                     Figure 1. ACPI Definition Blocks
> > -
> > -   NOTE: RSDP can also contain a pointer to the RSDT (Root System
> > -         Description Table).  Platforms provide RSDT to enable
> > -         compatibility with ACPI 1.0 operating systems.  The OS is expected
> > -         to use XSDT, if present.
> > -
> > -
> > -2. Example ACPI Namespace
> > -
> > -   All definition blocks are loaded into a single namespace.  The namespace
> > -   is a hierarchy of objects identified by names and paths.
> > -   The following naming conventions apply to object names in the ACPI
> > -   namespace:
> >     1. All names are 32 bits long.
> >     2. The first byte of a name must be one of 'A' - 'Z', '_'.
> >     3. Each of the remaining bytes of a name must be one of 'A' - 'Z', '0'
> > @@ -91,7 +94,7 @@ Wysocki <rafael.j.wysocki@intel.com>.
> >        (i.e. names prepended with '^' are relative to the parent of the
> >        current namespace node).
> >  
> > -   The figure below shows an example ACPI namespace.
> > +The figure below shows an example ACPI namespace::
> >  
> >     +------+
> >     | \    |                     Root
> > @@ -184,19 +187,20 @@ Wysocki <rafael.j.wysocki@intel.com>.
> >                       Figure 2. Example ACPI Namespace
> >  
> >  
> > -3. Linux ACPI Device Objects
> > +Linux ACPI Device Objects
> > +=========================
> >  
> > -   The Linux kernel's core ACPI subsystem creates struct acpi_device
> > -   objects for ACPI namespace objects representing devices, power resources
> > -   processors, thermal zones.  Those objects are exported to user space via
> > -   sysfs as directories in the subtree under /sys/devices/LNXSYSTM:00.  The
> > -   format of their names is <bus_id:instance>, where 'bus_id' refers to the
> > -   ACPI namespace representation of the given object and 'instance' is used
> > -   for distinguishing different object of the same 'bus_id' (it is
> > -   two-digit decimal representation of an unsigned integer).
> > +The Linux kernel's core ACPI subsystem creates struct acpi_device
> > +objects for ACPI namespace objects representing devices, power resources
> > +processors, thermal zones.  Those objects are exported to user space via
> > +sysfs as directories in the subtree under /sys/devices/LNXSYSTM:00.  The
> > +format of their names is <bus_id:instance>, where 'bus_id' refers to the
> > +ACPI namespace representation of the given object and 'instance' is used
> > +for distinguishing different object of the same 'bus_id' (it is
> > +two-digit decimal representation of an unsigned integer).
> >  
> > -   The value of 'bus_id' depends on the type of the object whose name it is
> > -   part of as listed in the table below.
> > +The value of 'bus_id' depends on the type of the object whose name it is
> > +part of as listed in the table below::
> >  
> >                  +---+-----------------+-------+----------+
> >                  |   | Object/Feature  | Table | bus_id   |
> > @@ -226,10 +230,11 @@ Wysocki <rafael.j.wysocki@intel.com>.
> >  
> >                   Table 1. ACPI Namespace Objects Mapping
> >  
> > -   The following rules apply when creating struct acpi_device objects on
> > -   the basis of the contents of ACPI System Description Tables (as
> > -   indicated by the letter in the first column and the notation in the
> > -   second column of the table above):
> > +The following rules apply when creating struct acpi_device objects on
> > +the basis of the contents of ACPI System Description Tables (as
> > +indicated by the letter in the first column and the notation in the
> > +second column of the table above):
> > +
> >     N:
> >        The object's source is an ACPI namespace node (as indicated by the
> >        named object's type in the second column).  In that case the object's
> > @@ -249,13 +254,14 @@ Wysocki <rafael.j.wysocki@intel.com>.
> >        struct acpi_device object with LNXVIDEO 'bus_id' will be created for
> >        it.
> >  
> > -   The third column of the above table indicates which ACPI System
> > -   Description Tables contain information used for the creation of the
> > -   struct acpi_device objects represented by the given row (xSDT means DSDT
> > -   or SSDT).
> > +The third column of the above table indicates which ACPI System
> > +Description Tables contain information used for the creation of the
> > +struct acpi_device objects represented by the given row (xSDT means DSDT
> > +or SSDT).
> > +
> > +The forth column of the above table indicates the 'bus_id' generation
> > +rule of the struct acpi_device object:
> >  
> > -   The forth column of the above table indicates the 'bus_id' generation
> > -   rule of the struct acpi_device object:
> >     _HID:
> >        _HID in the last column of the table means that the object's bus_id
> >        is derived from the _HID/_CID identification objects present under
> > @@ -275,45 +281,47 @@ Wysocki <rafael.j.wysocki@intel.com>.
> >        object's bus_id.
> >  
> >  
> > -4. Linux ACPI Physical Device Glue
> > -
> > -   ACPI device (i.e. struct acpi_device) objects may be linked to other
> > -   objects in the Linux' device hierarchy that represent "physical" devices
> > -   (for example, devices on the PCI bus).  If that happens, it means that
> > -   the ACPI device object is a "companion" of a device otherwise
> > -   represented in a different way and is used (1) to provide configuration
> > -   information on that device which cannot be obtained by other means and
> > -   (2) to do specific things to the device with the help of its ACPI
> > -   control methods.  One ACPI device object may be linked this way to
> > -   multiple "physical" devices.
> > -
> > -   If an ACPI device object is linked to a "physical" device, its sysfs
> > -   directory contains the "physical_node" symbolic link to the sysfs
> > -   directory of the target device object.  In turn, the target device's
> > -   sysfs directory will then contain the "firmware_node" symbolic link to
> > -   the sysfs directory of the companion ACPI device object.
> > -   The linking mechanism relies on device identification provided by the
> > -   ACPI namespace.  For example, if there's an ACPI namespace object
> > -   representing a PCI device (i.e. a device object under an ACPI namespace
> > -   object representing a PCI bridge) whose _ADR returns 0x00020000 and the
> > -   bus number of the parent PCI bridge is 0, the sysfs directory
> > -   representing the struct acpi_device object created for that ACPI
> > -   namespace object will contain the 'physical_node' symbolic link to the
> > -   /sys/devices/pci0000:00/0000:00:02:0/ sysfs directory of the
> > -   corresponding PCI device.
> > -
> > -   The linking mechanism is generally bus-specific.  The core of its
> > -   implementation is located in the drivers/acpi/glue.c file, but there are
> > -   complementary parts depending on the bus types in question located
> > -   elsewhere.  For example, the PCI-specific part of it is located in
> > -   drivers/pci/pci-acpi.c.
> > -
> > -
> > -5. Example Linux ACPI Device Tree
> > -
> > -   The sysfs hierarchy of struct acpi_device objects corresponding to the
> > -   example ACPI namespace illustrated in Figure 2 with the addition of
> > -   fixed PWR_BUTTON/SLP_BUTTON devices is shown below.
> > +Linux ACPI Physical Device Glue
> > +===============================
> > +
> > +ACPI device (i.e. struct acpi_device) objects may be linked to other
> > +objects in the Linux' device hierarchy that represent "physical" devices
> > +(for example, devices on the PCI bus).  If that happens, it means that
> > +the ACPI device object is a "companion" of a device otherwise
> > +represented in a different way and is used (1) to provide configuration
> > +information on that device which cannot be obtained by other means and
> > +(2) to do specific things to the device with the help of its ACPI
> > +control methods.  One ACPI device object may be linked this way to
> > +multiple "physical" devices.
> > +
> > +If an ACPI device object is linked to a "physical" device, its sysfs
> > +directory contains the "physical_node" symbolic link to the sysfs
> > +directory of the target device object.  In turn, the target device's
> > +sysfs directory will then contain the "firmware_node" symbolic link to
> > +the sysfs directory of the companion ACPI device object.
> > +The linking mechanism relies on device identification provided by the
> > +ACPI namespace.  For example, if there's an ACPI namespace object
> > +representing a PCI device (i.e. a device object under an ACPI namespace
> > +object representing a PCI bridge) whose _ADR returns 0x00020000 and the
> > +bus number of the parent PCI bridge is 0, the sysfs directory
> > +representing the struct acpi_device object created for that ACPI
> > +namespace object will contain the 'physical_node' symbolic link to the
> > +/sys/devices/pci0000:00/0000:00:02:0/ sysfs directory of the
> > +corresponding PCI device.
> > +
> > +The linking mechanism is generally bus-specific.  The core of its
> > +implementation is located in the drivers/acpi/glue.c file, but there are
> > +complementary parts depending on the bus types in question located
> > +elsewhere.  For example, the PCI-specific part of it is located in
> > +drivers/pci/pci-acpi.c.
> > +
> > +
> > +Example Linux ACPI Device Tree
> > +=================================
> > +
> > +The sysfs hierarchy of struct acpi_device objects corresponding to the
> > +example ACPI namespace illustrated in Figure 2 with the addition of
> > +fixed PWR_BUTTON/SLP_BUTTON devices is shown below::
> >  
> >     +--------------+---+-----------------+
> >     | LNXSYSTEM:00 | \ | acpi:LNXSYSTEM: |
> > @@ -377,12 +385,14 @@ Wysocki <rafael.j.wysocki@intel.com>.
> >  
> >                    Figure 3. Example Linux ACPI Device Tree
> >  
> > -   NOTE: Each node is represented as "object/path/modalias", where:
> > -         1. 'object' is the name of the object's directory in sysfs.
> > -         2. 'path' is the ACPI namespace path of the corresponding
> > -            ACPI namespace object, as returned by the object's 'path'
> > -            sysfs attribute.
> > -         3. 'modalias' is the value of the object's 'modalias' sysfs
> > -            attribute (as described earlier in this document).
> > -   NOTE: N/A indicates the device object does not have the 'path' or the
> > -         'modalias' attribute.
> > +.. note:: Each node is represented as "object/path/modalias", where:
> > +
> > +   1. 'object' is the name of the object's directory in sysfs.
> > +   2. 'path' is the ACPI namespace path of the corresponding
> > +      ACPI namespace object, as returned by the object's 'path'
> > +      sysfs attribute.
> > +   3. 'modalias' is the value of the object's 'modalias' sysfs
> > +      attribute (as described earlier in this document).
> > +
> > +.. note:: N/A indicates the device object does not have the 'path' or the
> > +   'modalias' attribute.
> 
> 
> 
> Thanks,
> Mauro

-- 
Cheers,
Changbin Du