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