0001 .. SPDX-License-Identifier: GPL-2.0
0002 .. include:: <isonum.txt>
0003
0004 ===================================
0005 Referencing hierarchical data nodes
0006 ===================================
0007
0008 :Copyright: |copy| 2018, 2021 Intel Corporation
0009 :Author: Sakari Ailus <sakari.ailus@linux.intel.com>
0010
0011 ACPI in general allows referring to device objects in the tree only.
0012 Hierarchical data extension nodes may not be referred to directly, hence this
0013 document defines a scheme to implement such references.
0014
0015 A reference consist of the device object name followed by one or more
0016 hierarchical data extension [dsd-guide] keys. Specifically, the hierarchical
0017 data extension node which is referred to by the key shall lie directly under
0018 the parent object i.e. either the device object or another hierarchical data
0019 extension node.
0020
0021 The keys in the hierarchical data nodes shall consist of the name of the node,
0022 "@" character and the number of the node in hexadecimal notation (without pre-
0023 or postfixes). The same ACPI object shall include the _DSD property extension
0024 with a property "reg" that shall have the same numerical value as the number of
0025 the node.
0026
0027 In case a hierarchical data extensions node has no numerical value, then the
0028 "reg" property shall be omitted from the ACPI object's _DSD properties and the
0029 "@" character and the number shall be omitted from the hierarchical data
0030 extension key.
0031
0032
0033 Example
0034 =======
0035
0036 In the ASL snippet below, the "reference" _DSD property contains a
0037 device object reference to DEV0 and under that device object, a
0038 hierarchical data extension key "node@1" referring to the NOD1 object
0039 and lastly, a hierarchical data extension key "anothernode" referring to
0040 the ANOD object which is also the final target node of the reference.
0041 ::
0042
0043 Device (DEV0)
0044 {
0045 Name (_DSD, Package () {
0046 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
0047 Package () {
0048 Package () { "node@0", "NOD0" },
0049 Package () { "node@1", "NOD1" },
0050 }
0051 })
0052 Name (NOD0, Package() {
0053 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
0054 Package () {
0055 Package () { "reg", 0 },
0056 Package () { "random-property", 3 },
0057 }
0058 })
0059 Name (NOD1, Package() {
0060 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
0061 Package () {
0062 Package () { "reg", 1 },
0063 Package () { "anothernode", "ANOD" },
0064 }
0065 })
0066 Name (ANOD, Package() {
0067 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
0068 Package () {
0069 Package () { "random-property", 0 },
0070 }
0071 })
0072 }
0073
0074 Device (DEV1)
0075 {
0076 Name (_DSD, Package () {
0077 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
0078 Package () {
0079 Package () {
0080 "reference", Package () {
0081 ^DEV0, "node@1", "anothernode"
0082 }
0083 },
0084 }
0085 })
0086 }
0087
0088 Please also see a graph example in
0089 Documentation/firmware-guide/acpi/dsd/graph.rst.
0090
0091 References
0092 ==========
0093
0094 [dsd-guide] DSD Guide.
0095 https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
0096 2021-11-30.
