Documentation: ACPI: move dsd/data-node-references.txt to firmware-guide/acpi and...

This converts the plain text documentation to reStructuredText format
and adds 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>
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

diff --git a/Documentation/acpi/dsd/data-node-references.txt b/Documentation/acpi/dsd/data-node-references.txt
deleted file mode 100644 (file)
index c387156..0000000
--- a/Documentation/acpi/dsd/data-node-references.txt
+++ /dev/null
@@ -1,89 +0,0 @@
-Copyright (C) 2018 Intel Corporation
-Author: Sakari Ailus <sakari.ailus@linux.intel.com>
-
-
-Referencing hierarchical data nodes
------------------------------------
-
-ACPI in general allows referring to device objects in the tree only.
-Hierarchical data extension nodes may not be referred to directly, hence this
-document defines a scheme to implement such references.
-
-A reference consist of the device object name followed by one or more
-hierarchical data extension [1] keys. Specifically, the hierarchical data
-extension node which is referred to by the key shall lie directly under the
-parent object i.e. either the device object or another hierarchical data
-extension node.
-
-The keys in the hierarchical data nodes shall consist of the name of the node,
-"@" character and the number of the node in hexadecimal notation (without pre-
-or postfixes). The same ACPI object shall include the _DSD property extension
-with a property "reg" that shall have the same numerical value as the number of
-the node.
-
-In case a hierarchical data extensions node has no numerical value, then the
-"reg" property shall be omitted from the ACPI object's _DSD properties and the
-"@" character and the number shall be omitted from the hierarchical data
-extension key.
-
-
-Example
--------
-
-       In the ASL snippet below, the "reference" _DSD property [2] contains a
-       device object reference to DEV0 and under that device object, a
-       hierarchical data extension key "node@1" referring to the NOD1 object
-       and lastly, a hierarchical data extension key "anothernode" referring to
-       the ANOD object which is also the final target node of the reference.
-
-       Device (DEV0)
-       {
-           Name (_DSD, Package () {
-               ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
-               Package () {
-                   Package () { "node@0", NOD0 },
-                   Package () { "node@1", NOD1 },
-               }
-           })
-           Name (NOD0, Package() {
-               ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
-               Package () {
-                   Package () { "random-property", 3 },
-               }
-           })
-           Name (NOD1, Package() {
-               ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
-               Package () {
-                   Package () { "anothernode", ANOD },
-               }
-           })
-           Name (ANOD, Package() {
-               ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
-               Package () {
-                   Package () { "random-property", 0 },
-               }
-           })
-       }
-
-       Device (DEV1)
-       {
-           Name (_DSD, Package () {
-               ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
-               Package () {
-                   Package () { "reference", ^DEV0, "node@1", "anothernode" },
-               }
-           })
-       }
-
-Please also see a graph example in graph.txt .
-
-References
-----------
-
-[1] Hierarchical Data Extension UUID For _DSD.
-    <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
-    referenced 2018-07-17.
-
-[2] Device Properties UUID For _DSD.
-    <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
-    referenced 2016-10-04.

diff --git a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst
new file mode 100644 (file)
index 0000000..1351984
--- /dev/null
+++ b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst
@@ -0,0 +1,93 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+===================================
+Referencing hierarchical data nodes
+===================================
+
+:Copyright: |copy| 2018 Intel Corporation
+:Author: Sakari Ailus <sakari.ailus@linux.intel.com>
+
+ACPI in general allows referring to device objects in the tree only.
+Hierarchical data extension nodes may not be referred to directly, hence this
+document defines a scheme to implement such references.
+
+A reference consist of the device object name followed by one or more
+hierarchical data extension [1] keys. Specifically, the hierarchical data
+extension node which is referred to by the key shall lie directly under the
+parent object i.e. either the device object or another hierarchical data
+extension node.
+
+The keys in the hierarchical data nodes shall consist of the name of the node,
+"@" character and the number of the node in hexadecimal notation (without pre-
+or postfixes). The same ACPI object shall include the _DSD property extension
+with a property "reg" that shall have the same numerical value as the number of
+the node.
+
+In case a hierarchical data extensions node has no numerical value, then the
+"reg" property shall be omitted from the ACPI object's _DSD properties and the
+"@" character and the number shall be omitted from the hierarchical data
+extension key.
+
+
+Example
+=======
+
+In the ASL snippet below, the "reference" _DSD property [2] contains a
+device object reference to DEV0 and under that device object, a
+hierarchical data extension key "node@1" referring to the NOD1 object
+and lastly, a hierarchical data extension key "anothernode" referring to
+the ANOD object which is also the final target node of the reference.
+::
+
+       Device (DEV0)
+       {
+           Name (_DSD, Package () {
+               ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+               Package () {
+                   Package () { "node@0", NOD0 },
+                   Package () { "node@1", NOD1 },
+               }
+           })
+           Name (NOD0, Package() {
+               ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+               Package () {
+                   Package () { "random-property", 3 },
+               }
+           })
+           Name (NOD1, Package() {
+               ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
+               Package () {
+                   Package () { "anothernode", ANOD },
+               }
+           })
+           Name (ANOD, Package() {
+               ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+               Package () {
+                   Package () { "random-property", 0 },
+               }
+           })
+       }
+
+       Device (DEV1)
+       {
+           Name (_DSD, Package () {
+               ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
+               Package () {
+                   Package () { "reference", ^DEV0, "node@1", "anothernode" },
+               }
+           })
+       }
+
+Please also see a graph example in :doc:`graph`.
+
+References
+==========
+
+[1] Hierarchical Data Extension UUID For _DSD.
+<http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
+referenced 2018-07-17.
+
+[2] Device Properties UUID For _DSD.
+<http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
+referenced 2016-10-04.

diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst
index f81cfbcb6878c1a3b7bbfcfa63a3f19f4ecee7c6..6d4e0df4f06382b96b0966b8ebd033495d483746 100644 (file)
--- a/Documentation/firmware-guide/acpi/index.rst
+++ b/Documentation/firmware-guide/acpi/index.rst
@@ -9,6 +9,7 @@ ACPI Support
 
    namespace
    dsd/graph
+   dsd/data-node-references
    enumeration
    osi
    method-customizing