mirrors/linux
1
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2025-12-27 11:06:41 -05:00
Code Issues Packages Projects Releases Wiki Activity

Documentation: ACPI: Use all-string data node references

Browse Source 
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: 9880702d12 ("ACPI: property: Support using strings in reference properties")
Cc: 6.8+ <stable@vger.kernel.org> # 6.8+
Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
Link: https://patch.msgid.link/20250409084738.3657079-1-sakari.ailus@linux.intel.com
[ rjw: Clarifying edits ]
Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
This commit is contained in:
Sakari Ailus
2025-04-09 11:47:38 +03:00
committed by Rafael J. Wysocki
parent 0af2f6be1b
commit 6db0261f37
3 changed files with 17 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
Documentation/firmware-guide/acpi/dsd/data-node-references.rst
View File

@@ -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 is a string consisting of a
device object reference followed by a dot (".") and a relative path to a data
node object. Do not use non-string references as this will produce a copy of
the hierarchical data node, not a reference!
The hierarchical data extension node which is referred to shall be located
directly under its parent object i.e. either the device object or another
hierarchical data extension node [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. 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" }
},
}
})

11
Documentation/firmware-guide/acpi/dsd/graph.rst
View File

@@ -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" },
}
})
}

7
Documentation/firmware-guide/acpi/dsd/leds.rst
View File

@@ -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" },
}
}
})