xref: /linux/Documentation/firmware-guide/acpi/dsd/data-node-references.rst (revision 3702a515edec515fcc7e085053da636fefac88d6) 
1.. SPDX-License-Identifier: GPL-2.0
2.. include:: <isonum.txt>
3
4===================================
5Referencing hierarchical data nodes
6===================================
7
8:Copyright: |copy| 2018, 2021 Intel Corporation
9:Author: Sakari Ailus <sakari.ailus@linux.intel.com>
10
11ACPI in general allows referring to device objects in the tree only.
12Hierarchical data extension nodes may not be referred to directly, hence this
13document defines a scheme to implement such references.
14
15A reference to a _DSD hierarchical data node is a string consisting of a
16device object reference followed by a dot (".") and a relative path to a data
17node object. Do not use non-string references as this will produce a copy of
18the hierarchical data node, not a reference!
19
20The hierarchical data extension node which is referred to shall be located
21directly under its parent object i.e. either the device object or another
22hierarchical data extension node [dsd-guide].
23
24The keys in the hierarchical data nodes shall consist of the name of the node,
25"@" character and the number of the node in hexadecimal notation (without pre-
26or postfixes). The same ACPI object shall include the _DSD property extension
27with a property "reg" that shall have the same numerical value as the number of
28the node.
29
30In case a hierarchical data extensions node has no numerical value, then the
31"reg" property shall be omitted from the ACPI object's _DSD properties and the
32"@" character and the number shall be omitted from the hierarchical data
33extension key.
34
35
36Example
37=======
38
39In the ASL snippet below, the "reference" _DSD property contains a string
40reference to a hierarchical data extension node ANOD under DEV0 under the parent
41of DEV1. ANOD is also the final target node of the reference.
42::
43
44	Device (DEV0)
45	{
46	    Name (_DSD, Package () {
47		ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
48		Package () {
49		    Package () { "node@0", "NOD0" },
50		    Package () { "node@1", "NOD1" },
51		}
52	    })
53	    Name (NOD0, Package() {
54		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
55		Package () {
56		    Package () { "reg", 0 },
57		    Package () { "random-property", 3 },
58		}
59	    })
60	    Name (NOD1, Package() {
61		ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
62		Package () {
63		    Package () { "reg", 1 },
64		    Package () { "anothernode", "ANOD" },
65		}
66	    })
67	    Name (ANOD, Package() {
68		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
69		Package () {
70		    Package () { "random-property", 0 },
71		}
72	    })
73	}
74
75	Device (DEV1)
76	{
77	    Name (_DSD, Package () {
78		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
79		Package () {
80		    Package () { "reference", "^DEV0.ANOD" }
81		    },
82		}
83	    })
84	}
85
86Please also see a graph example in
87Documentation/firmware-guide/acpi/dsd/graph.rst.
88
89References
90==========
91
92[dsd-guide] DSD Guide.
93    https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
94    2021-11-30.
95