| Message ID | 20190423162932.21428-15-changbin.du@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Delegated to: | Bjorn Helgaas |
| Headers | show |
| Series | Include linux ACPI/PCI/X86 docs into Sphinx TOC tree | expand |
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
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
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> --- .../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%)