Re: [PATCH v4 14/63] Documentation: ACPI: move dsd/graph.txt to firmware-guide/acpi and convert to reST
From: Mauro Carvalho Chehab
Date: Tue Apr 23 2019 - 17:15:04 EST
Em Wed, 24 Apr 2019 00:28:43 +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>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx>
> ---
> .../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