[PATCH 1/1] Documentation: ACPI: Use all-string data node references

[PATCH 1/1] Documentation: ACPI: Use all-string data node references

[Sakari Ailus]

Document that references to data nodes shall use string-only references
instead of a device reference and a succession of the first package
entries of hierarchical data node references.

Fixes: 9880702d123f ("ACPI: property: Support using strings in reference properties")
Cc: stable@vger.kernel.org # for 6.8 and later
Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
---
 .../acpi/dsd/data-node-references.rst         | 26 +++++++++----------
 .../firmware-guide/acpi/dsd/graph.rst         | 11 +++-----
 .../firmware-guide/acpi/dsd/leds.rst          |  7 +----
 3 files changed, 17 insertions(+), 27 deletions(-)

diff --git a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst
index 8d8b53e96bcf..8d91fab37d89 100644
--- a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst
+++ b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst
@@ -12,11 +12,14 @@ 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 [dsd-guide] 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.
+A reference to a _DSD hierarchical data node consist of the device object
+reference followed by a dot (".") and the data node object name as a string. Do
+not use non-string references as this will result in a copy of the hierarchical
+data node itself, not a reference!
+
+The hierarchical data extension node which is referred to shall have a
+followable path of hierarchical data node reference under a device it resides
+[dsd-guide].
 
 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-
@@ -33,11 +36,9 @@ extension key.
 Example
 =======
 
-In the ASL snippet below, the "reference" _DSD property 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.
+In the ASL snippet below, the "reference" _DSD property contains a string
+reference to a hierarchical data extension node ANOD under DEV0 under the parent
+of DEV1 device object. ANOD is also the final target node of the reference.
 ::
 
 	Device (DEV0)
@@ -76,10 +77,7 @@ the ANOD object which is also the final target node of the reference.
 	    Name (_DSD, Package () {
 		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
 		Package () {
-		    Package () {
-			"reference", Package () {
-			    ^DEV0, "node@1", "anothernode"
-			}
+		    Package () { "reference", "^DEV0.ANOD" }
 		    },
 		}
 	    })
diff --git a/Documentation/firmware-guide/acpi/dsd/graph.rst b/Documentation/firmware-guide/acpi/dsd/graph.rst
index b9dbfc73ed25..d6ae5ffa748c 100644
--- a/Documentation/firmware-guide/acpi/dsd/graph.rst
+++ b/Documentation/firmware-guide/acpi/dsd/graph.rst
@@ -66,12 +66,9 @@ 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 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::
+name followed by a string reference in the same package. [data-node-ref]::
 
-    Package() { device, "port@X", "endpoint@Y" }
+    "device.datanode"
 
 In the above example, "X" is the number of the port and "Y" is the number of
 the endpoint.
@@ -109,7 +106,7 @@ A simple example of this is show below::
 		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
 		Package () {
 		    Package () { "reg", 0 },
-		    Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } },
+		    Package () { "remote-endpoint", "\\_SB.PCI0.ISP.EP40" },
 		}
 	    })
 	}
@@ -141,7 +138,7 @@ A simple example of this is show below::
 		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
 		Package () {
 		    Package () { "reg", 0 },
-		    Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } },
+		    Package () { "remote-endpoint", "\\_SB.PCI0.I2C2.CAM0.EP00" },
 		}
 	    })
 	}
diff --git a/Documentation/firmware-guide/acpi/dsd/leds.rst b/Documentation/firmware-guide/acpi/dsd/leds.rst
index 93db592c93c7..a97cd07d49be 100644
--- a/Documentation/firmware-guide/acpi/dsd/leds.rst
+++ b/Documentation/firmware-guide/acpi/dsd/leds.rst
@@ -15,11 +15,6 @@ Referring to LEDs in Device tree is documented in [video-interfaces], in
 "flash-leds" property documentation. In short, LEDs are directly referred to by
 using phandles.
 
-While Device tree allows referring to any node in the tree [devicetree], in
-ACPI references are limited to device nodes only [acpi]. For this reason using
-the same mechanism on ACPI is not possible. A mechanism to refer to non-device
-ACPI nodes is documented in [data-node-ref].
-
 ACPI allows (as does DT) using integer arguments after the reference. A
 combination of the LED driver device reference and an integer argument,
 referring to the "reg" property of the relevant LED, is used to identify
@@ -74,7 +69,7 @@ omitted. ::
 			Package () {
 				Package () {
 					"flash-leds",
-					Package () { ^LED, "led@0", ^LED, "led@1" },
+					Package () { "^LED.LED0", "^LED.LED1" },
 				}
 			}
 		})
-- 
2.39.5

Re: [PATCH 1/1] Documentation: ACPI: Use all-string data node references

[Rafael J. Wysocki]

On Wed, Apr 9, 2025 at 10:47 AM Sakari Ailus
<sakari.ailus@linux.intel.com> wrote:
>
> Document that references to data nodes shall use string-only references
> instead of a device reference and a succession of the first package
> entries of hierarchical data node references.
>
> Fixes: 9880702d123f ("ACPI: property: Support using strings in reference properties")
> Cc: stable@vger.kernel.org # for 6.8 and later
> Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> ---
>  .../acpi/dsd/data-node-references.rst         | 26 +++++++++----------
>  .../firmware-guide/acpi/dsd/graph.rst         | 11 +++-----
>  .../firmware-guide/acpi/dsd/leds.rst          |  7 +----
>  3 files changed, 17 insertions(+), 27 deletions(-)
>
> diff --git a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst
> index 8d8b53e96bcf..8d91fab37d89 100644
> --- a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst
> +++ b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst
> @@ -12,11 +12,14 @@ 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 [dsd-guide] 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.
> +A reference to a _DSD hierarchical data node consist of the device object
> +reference followed by a dot (".") and the data node object name as a string. Do
> +not use non-string references as this will result in a copy of the hierarchical
> +data node itself, not a reference!
> +
> +The hierarchical data extension node which is referred to shall have a
> +followable path of hierarchical data node reference under a device it resides
> +[dsd-guide].

I've edited the above so it is a bit easier to follow and applied the
patch for 6.16.

>  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-
> @@ -33,11 +36,9 @@ extension key.
>  Example
>  =======
>
> -In the ASL snippet below, the "reference" _DSD property 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.
> +In the ASL snippet below, the "reference" _DSD property contains a string
> +reference to a hierarchical data extension node ANOD under DEV0 under the parent
> +of DEV1 device object. ANOD is also the final target node of the reference.
>  ::
>
>         Device (DEV0)
> @@ -76,10 +77,7 @@ the ANOD object which is also the final target node of the reference.
>             Name (_DSD, Package () {
>                 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
>                 Package () {
> -                   Package () {
> -                       "reference", Package () {
> -                           ^DEV0, "node@1", "anothernode"
> -                       }
> +                   Package () { "reference", "^DEV0.ANOD" }
>                     },
>                 }
>             })
> diff --git a/Documentation/firmware-guide/acpi/dsd/graph.rst b/Documentation/firmware-guide/acpi/dsd/graph.rst
> index b9dbfc73ed25..d6ae5ffa748c 100644
> --- a/Documentation/firmware-guide/acpi/dsd/graph.rst
> +++ b/Documentation/firmware-guide/acpi/dsd/graph.rst
> @@ -66,12 +66,9 @@ 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 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::
> +name followed by a string reference in the same package. [data-node-ref]::
>
> -    Package() { device, "port@X", "endpoint@Y" }
> +    "device.datanode"
>
>  In the above example, "X" is the number of the port and "Y" is the number of
>  the endpoint.
> @@ -109,7 +106,7 @@ A simple example of this is show below::
>                 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
>                 Package () {
>                     Package () { "reg", 0 },
> -                   Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } },
> +                   Package () { "remote-endpoint", "\\_SB.PCI0.ISP.EP40" },
>                 }
>             })
>         }
> @@ -141,7 +138,7 @@ A simple example of this is show below::
>                 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
>                 Package () {
>                     Package () { "reg", 0 },
> -                   Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } },
> +                   Package () { "remote-endpoint", "\\_SB.PCI0.I2C2.CAM0.EP00" },
>                 }
>             })
>         }
> diff --git a/Documentation/firmware-guide/acpi/dsd/leds.rst b/Documentation/firmware-guide/acpi/dsd/leds.rst
> index 93db592c93c7..a97cd07d49be 100644
> --- a/Documentation/firmware-guide/acpi/dsd/leds.rst
> +++ b/Documentation/firmware-guide/acpi/dsd/leds.rst
> @@ -15,11 +15,6 @@ Referring to LEDs in Device tree is documented in [video-interfaces], in
>  "flash-leds" property documentation. In short, LEDs are directly referred to by
>  using phandles.
>
> -While Device tree allows referring to any node in the tree [devicetree], in
> -ACPI references are limited to device nodes only [acpi]. For this reason using
> -the same mechanism on ACPI is not possible. A mechanism to refer to non-device
> -ACPI nodes is documented in [data-node-ref].
> -
>  ACPI allows (as does DT) using integer arguments after the reference. A
>  combination of the LED driver device reference and an integer argument,
>  referring to the "reg" property of the relevant LED, is used to identify
> @@ -74,7 +69,7 @@ omitted. ::
>                         Package () {
>                                 Package () {
>                                         "flash-leds",
> -                                       Package () { ^LED, "led@0", ^LED, "led@1" },
> +                                       Package () { "^LED.LED0", "^LED.LED1" },
>                                 }
>                         }
>                 })
> --
> 2.39.5
>