lkml.org 
[lkml]   [2019]   [Apr]   [24]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v5 13/23] Documentation: ACPI: move dsd/graph.txt to firmware-guide/acpi and convert to reST
    Date
    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>
    Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
    ---
    .../acpi/dsd/graph.rst} | 157 +++++++++---------
    Documentation/firmware-guide/acpi/index.rst | 1 +
    2 files changed, 81 insertions(+), 77 deletions(-)
    rename Documentation/{acpi/dsd/graph.txt => firmware-guide/acpi/dsd/graph.rst} (56%)

    diff --git a/Documentation/acpi/dsd/graph.txt b/Documentation/firmware-guide/acpi/dsd/graph.rst
    similarity index 56%
    rename from Documentation/acpi/dsd/graph.txt
    rename to Documentation/firmware-guide/acpi/dsd/graph.rst
    index b9ce910781dc..e0baed35b037 100644
    --- a/Documentation/acpi/dsd/graph.txt
    +++ b/Documentation/firmware-guide/acpi/dsd/graph.rst
    @@ -1,8 +1,11 @@
    -Graphs
    +.. SPDX-License-Identifier: GPL-2.0

    +======
    +Graphs
    +======

    _DSD
    -----
    +====

    _DSD (Device Specific Data) [7] is a predefined ACPI device
    configuration object that can be used to convey information on
    @@ -30,7 +33,7 @@ hierarchical data extension array on each depth.


    Ports and endpoints
    --------------------
    +===================

    The port and endpoint concepts are very similar to those in Devicetree
    [3]. A port represents an interface in a device, and an endpoint
    @@ -38,9 +41,9 @@ represents a connection to that interface.

    All port nodes are located under the device's "_DSD" node in the hierarchical
    data extension tree. The data extension related to each port node must begin
    -with "port" and must be followed by the "@" character and the number of the port
    -as its key. The target object it refers to should be called "PRTX", where "X" is
    -the number of the port. An example of such a package would be:
    +with "port" and must be followed by the "@" character and the number of the
    +port as its key. The target object it refers to should be called "PRTX", where
    +"X" is the number of the port. An example of such a package would be::

    Package() { "port@4", PRT4 }

    @@ -49,7 +52,7 @@ data extension key of the endpoint nodes must begin with
    "endpoint" and must be followed by the "@" character and the number of the
    endpoint. The object it refers to should be called "EPXY", where "X" is the
    number of the port and "Y" is the number of the endpoint. An example of such a
    -package would be:
    +package would be::

    Package() { "endpoint@0", EP40 }

    @@ -62,85 +65,85 @@ of that port shall be zero. Similarly, if a port may only have a single
    endpoint, the number of that endpoint shall be zero.

    The endpoint reference uses property extension with "remote-endpoint" property
    -name followed by a reference in the same package. Such references consist of the
    +name followed by a reference in the same package. Such references consist of
    the remote device reference, the first package entry of the port data extension
    reference under the device and finally the first package entry of the endpoint
    -data extension reference under the port. Individual references thus appear as:
    +data extension reference under the port. Individual references thus appear as::

    Package() { device, "port@X", "endpoint@Y" }

    -In the above example, "X" is the number of the port and "Y" is the number of the
    -endpoint.
    +In the above example, "X" is the number of the port and "Y" is the number of
    +the endpoint.

    The references to endpoints must be always done both ways, to the
    remote endpoint and back from the referred remote endpoint node.

    -A simple example of this is show below:
    +A simple example of this is show below::

    Scope (\_SB.PCI0.I2C2)
    {
    - Device (CAM0)
    - {
    - Name (_DSD, Package () {
    - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
    - Package () {
    - Package () { "compatible", Package () { "nokia,smia" } },
    - },
    - ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
    - Package () {
    - Package () { "port@0", PRT0 },
    - }
    - })
    - Name (PRT0, Package() {
    - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
    - Package () {
    - Package () { "reg", 0 },
    - },
    - ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
    - Package () {
    - Package () { "endpoint@0", EP00 },
    - }
    - })
    - Name (EP00, Package() {
    - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
    - Package () {
    - Package () { "reg", 0 },
    - Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } },
    - }
    - })
    - }
    + Device (CAM0)
    + {
    + Name (_DSD, Package () {
    + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
    + Package () {
    + Package () { "compatible", Package () { "nokia,smia" } },
    + },
    + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
    + Package () {
    + Package () { "port@0", PRT0 },
    + }
    + })
    + Name (PRT0, Package() {
    + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
    + Package () {
    + Package () { "reg", 0 },
    + },
    + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
    + Package () {
    + Package () { "endpoint@0", EP00 },
    + }
    + })
    + Name (EP00, Package() {
    + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
    + Package () {
    + Package () { "reg", 0 },
    + Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } },
    + }
    + })
    + }
    }

    Scope (\_SB.PCI0)
    {
    - Device (ISP)
    - {
    - Name (_DSD, Package () {
    - ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
    - Package () {
    - Package () { "port@4", PRT4 },
    - }
    - })
    -
    - Name (PRT4, Package() {
    - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
    - Package () {
    - Package () { "reg", 4 }, /* CSI-2 port number */
    - },
    - ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
    - Package () {
    - Package () { "endpoint@0", EP40 },
    - }
    - })
    -
    - Name (EP40, Package() {
    - ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
    - Package () {
    - Package () { "reg", 0 },
    - Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } },
    - }
    - })
    - }
    + Device (ISP)
    + {
    + Name (_DSD, Package () {
    + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
    + Package () {
    + Package () { "port@4", PRT4 },
    + }
    + })
    +
    + Name (PRT4, Package() {
    + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
    + Package () {
    + Package () { "reg", 4 }, /* CSI-2 port number */
    + },
    + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
    + Package () {
    + Package () { "endpoint@0", EP40 },
    + }
    + })
    +
    + Name (EP40, Package() {
    + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
    + Package () {
    + Package () { "reg", 0 },
    + Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } },
    + }
    + })
    + }
    }

    Here, the port 0 of the "CAM0" device is connected to the port 4 of
    @@ -148,27 +151,27 @@ the "ISP" device and vice versa.


    References
    -----------
    +==========

    [1] _DSD (Device Specific Data) Implementation Guide.
    - <URL:http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm>,
    + http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm,
    referenced 2016-10-03.

    -[2] Devicetree. <URL:http://www.devicetree.org>, referenced 2016-10-03.
    +[2] Devicetree. http://www.devicetree.org, referenced 2016-10-03.

    [3] Documentation/devicetree/bindings/graph.txt

    [4] Device Properties UUID For _DSD.
    - <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
    + http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf,
    referenced 2016-10-04.

    [5] Hierarchical Data Extension UUID For _DSD.
    - <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
    + http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf,
    referenced 2016-10-04.

    [6] Advanced Configuration and Power Interface Specification.
    - <URL:http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf>,
    + http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf,
    referenced 2016-10-04.

    [7] _DSD Device Properties Usage Rules.
    - Documentation/acpi/DSD-properties-rules.txt
    + :doc:`../DSD-properties-rules`
    diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
    index bedcb0b242a2..f81cfbcb6878 100644
    --- a/Documentation/firmware-guide/acpi/index.rst
    +++ b/Documentation/firmware-guide/acpi/index.rst
    @@ -8,6 +8,7 @@ ACPI Support
    :maxdepth: 1

    namespace
    + dsd/graph
    enumeration
    osi
    method-customizing
    --
    2.20.1
    \
     
     \ /
      Last update: 2019-04-24 19:55    [W:4.315 / U:0.984 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site