Re: [PATCH v4 02/63] Documentation: ACPI: move namespace.txt to firmware-guide/acpi and convert to reST
From: Mauro Carvalho Chehab
Date: Tue Apr 23 2019 - 16:38:54 EST
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.
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