On Wed, Apr 9, 2025 at 10:47 AM Sakari Ailus
<sakari.ailus@xxxxxxxxxxxxxxx> 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@xxxxxxxxxxxxxxx # for 6.8 and later
> Signed-off-by: Sakari Ailus <sakari.ailus@xxxxxxxxxxxxxxx>
> ---
> .../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
>
