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

[Mauro Carvalho Chehab <mchehab+samsung@kernel.org>]

Em Wed, 24 Apr 2019 00:28:43 +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>

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



Thanks,
Mauro