Re: [PATCH v4 02/63] Documentation: ACPI: move namespace.txt to firmware-guide/acpi and convert to reST
From: Changbin Du
Date: Wed Apr 24 2019 - 12:09:59 EST
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@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/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@xxxxxxxxx>
> > +
> > +: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@xxxxxxxxxx>
>
> > +
> > +:Credit: Thanks for the help from Zhang Rui <rui.zhang@xxxxxxxxx> and
> > + Rafael J.Wysocki <rafael.j.wysocki@xxxxxxxxx>.
> > +
> > +
> > +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@xxxxxxxxx>
> > -
> > -
> > -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@xxxxxxxxx> and Rafael J.
> > -Wysocki <rafael.j.wysocki@xxxxxxxxx>.
> > -
> > -
> > -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@xxxxxxxxx>.
> > (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@xxxxxxxxx>.
> > 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@xxxxxxxxx>.
> >
> > 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@xxxxxxxxx>.
> > 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@xxxxxxxxx>.
> > 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@xxxxxxxxx>.
> >
> > 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