1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ====== 3 ======
4 Graphs 4 Graphs
5 ====== 5 ======
6 6
7 _DSD 7 _DSD
8 ==== 8 ====
9 9
10 _DSD (Device Specific Data) [dsd-guide] is a p 10 _DSD (Device Specific Data) [dsd-guide] is a predefined ACPI device
11 configuration object that can be used to conve 11 configuration object that can be used to convey information on
12 hardware features which are not specifically c 12 hardware features which are not specifically covered by the ACPI
13 specification [acpi]. There are two _DSD exten 13 specification [acpi]. There are two _DSD extensions that are relevant
14 for graphs: property [dsd-guide] and hierarchi 14 for graphs: property [dsd-guide] and hierarchical data extensions. The
15 property extension provides generic key-value 15 property extension provides generic key-value pairs whereas the
16 hierarchical data extension supports nodes wit 16 hierarchical data extension supports nodes with references to other
17 nodes, forming a tree. The nodes in the tree m 17 nodes, forming a tree. The nodes in the tree may contain properties as
18 defined by the property extension. The two ext 18 defined by the property extension. The two extensions together provide
19 a tree-like structure with zero or more proper 19 a tree-like structure with zero or more properties (key-value pairs)
20 in each node of the tree. 20 in each node of the tree.
21 21
22 The data structure may be accessed at runtime 22 The data structure may be accessed at runtime by using the device_*
23 and fwnode_* functions defined in include/linu 23 and fwnode_* functions defined in include/linux/fwnode.h .
24 24
25 Fwnode represents a generic firmware node obje 25 Fwnode represents a generic firmware node object. It is independent on
26 the firmware type. In ACPI, fwnodes are _DSD h 26 the firmware type. In ACPI, fwnodes are _DSD hierarchical data
27 extensions objects. A device's _DSD object is 27 extensions objects. A device's _DSD object is represented by an
28 fwnode. 28 fwnode.
29 29
30 The data structure may be referenced to elsewh 30 The data structure may be referenced to elsewhere in the ACPI tables
31 by using a hard reference to the device itself 31 by using a hard reference to the device itself and an index to the
32 hierarchical data extension array on each dept 32 hierarchical data extension array on each depth.
33 33
34 34
35 Ports and endpoints 35 Ports and endpoints
36 =================== 36 ===================
37 37
38 The port and endpoint concepts are very simila 38 The port and endpoint concepts are very similar to those in Devicetree
39 [devicetree, graph-bindings]. A port represent 39 [devicetree, graph-bindings]. A port represents an interface in a device, and
40 an endpoint represents a connection to that in 40 an endpoint represents a connection to that interface. Also see [data-node-ref]
41 for generic data node references. 41 for generic data node references.
42 42
43 All port nodes are located under the device's 43 All port nodes are located under the device's "_DSD" node in the hierarchical
44 data extension tree. The data extension relate 44 data extension tree. The data extension related to each port node must begin
45 with "port" and must be followed by the "@" ch 45 with "port" and must be followed by the "@" character and the number of the
46 port as its key. The target object it refers t 46 port as its key. The target object it refers to should be called "PRTX", where
47 "X" is the number of the port. An example of s 47 "X" is the number of the port. An example of such a package would be::
48 48
49 Package() { "port@4", "PRT4" } 49 Package() { "port@4", "PRT4" }
50 50
51 Further on, endpoints are located under the po 51 Further on, endpoints are located under the port nodes. The hierarchical
52 data extension key of the endpoint nodes must 52 data extension key of the endpoint nodes must begin with
53 "endpoint" and must be followed by the "@" cha 53 "endpoint" and must be followed by the "@" character and the number of the
54 endpoint. The object it refers to should be ca 54 endpoint. The object it refers to should be called "EPXY", where "X" is the
55 number of the port and "Y" is the number of th 55 number of the port and "Y" is the number of the endpoint. An example of such a
56 package would be:: 56 package would be::
57 57
58 Package() { "endpoint@0", "EP40" } 58 Package() { "endpoint@0", "EP40" }
59 59
60 Each port node contains a property extension k 60 Each port node contains a property extension key "port", the value of which is
61 the number of the port. Each endpoint is simil 61 the number of the port. Each endpoint is similarly numbered with a property
62 extension key "reg", the value of which is the 62 extension key "reg", the value of which is the number of the endpoint. Port
63 numbers must be unique within a device and end 63 numbers must be unique within a device and endpoint numbers must be unique
64 within a port. If a device object may only has 64 within a port. If a device object may only has a single port, then the number
65 of that port shall be zero. Similarly, if a po 65 of that port shall be zero. Similarly, if a port may only have a single
66 endpoint, the number of that endpoint shall be 66 endpoint, the number of that endpoint shall be zero.
67 67
68 The endpoint reference uses property extension 68 The endpoint reference uses property extension with "remote-endpoint" property
69 name followed by a reference in the same packa 69 name followed by a reference in the same package. Such references consist of
70 the remote device reference, the first package 70 the remote device reference, the first package entry of the port data extension
71 reference under the device and finally the fir 71 reference under the device and finally the first package entry of the endpoint
72 data extension reference under the port. Indiv 72 data extension reference under the port. Individual references thus appear as::
73 73
74 Package() { device, "port@X", "endpoint@Y" 74 Package() { device, "port@X", "endpoint@Y" }
75 75
76 In the above example, "X" is the number of the 76 In the above example, "X" is the number of the port and "Y" is the number of
77 the endpoint. 77 the endpoint.
78 78
79 The references to endpoints must be always don 79 The references to endpoints must be always done both ways, to the
80 remote endpoint and back from the referred rem 80 remote endpoint and back from the referred remote endpoint node.
81 81
82 A simple example of this is show below:: 82 A simple example of this is show below::
83 83
84 Scope (\_SB.PCI0.I2C2) 84 Scope (\_SB.PCI0.I2C2)
85 { 85 {
86 Device (CAM0) 86 Device (CAM0)
87 { 87 {
88 Name (_DSD, Package () { 88 Name (_DSD, Package () {
89 ToUUID("daffd814-6eba-4d8c-8a9 89 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
90 Package () { 90 Package () {
91 Package () { "compatible", 91 Package () { "compatible", Package () { "nokia,smia" } },
92 }, 92 },
93 ToUUID("dbb8e3e6-5886-4ba6-879 93 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
94 Package () { 94 Package () {
95 Package () { "port@0", "PR 95 Package () { "port@0", "PRT0" },
96 } 96 }
97 }) 97 })
98 Name (PRT0, Package() { 98 Name (PRT0, Package() {
99 ToUUID("daffd814-6eba-4d8c-8a9 99 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
100 Package () { 100 Package () {
101 Package () { "reg", 0 }, 101 Package () { "reg", 0 },
102 }, 102 },
103 ToUUID("dbb8e3e6-5886-4ba6-879 103 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
104 Package () { 104 Package () {
105 Package () { "endpoint@0", 105 Package () { "endpoint@0", "EP00" },
106 } 106 }
107 }) 107 })
108 Name (EP00, Package() { 108 Name (EP00, Package() {
109 ToUUID("daffd814-6eba-4d8c-8a9 109 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
110 Package () { 110 Package () {
111 Package () { "reg", 0 }, 111 Package () { "reg", 0 },
112 Package () { "remote-endpo 112 Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } },
113 } 113 }
114 }) 114 })
115 } 115 }
116 } 116 }
117 117
118 Scope (\_SB.PCI0) 118 Scope (\_SB.PCI0)
119 { 119 {
120 Device (ISP) 120 Device (ISP)
121 { 121 {
122 Name (_DSD, Package () { 122 Name (_DSD, Package () {
123 ToUUID("dbb8e3e6-5886-4ba6-879 123 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
124 Package () { 124 Package () {
125 Package () { "port@4", "PR 125 Package () { "port@4", "PRT4" },
126 } 126 }
127 }) 127 })
128 128
129 Name (PRT4, Package() { 129 Name (PRT4, Package() {
130 ToUUID("daffd814-6eba-4d8c-8a9 130 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
131 Package () { 131 Package () {
132 Package () { "reg", 4 }, / 132 Package () { "reg", 4 }, /* CSI-2 port number */
133 }, 133 },
134 ToUUID("dbb8e3e6-5886-4ba6-879 134 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
135 Package () { 135 Package () {
136 Package () { "endpoint@0", 136 Package () { "endpoint@0", "EP40" },
137 } 137 }
138 }) 138 })
139 139
140 Name (EP40, Package() { 140 Name (EP40, Package() {
141 ToUUID("daffd814-6eba-4d8c-8a9 141 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
142 Package () { 142 Package () {
143 Package () { "reg", 0 }, 143 Package () { "reg", 0 },
144 Package () { "remote-endpo 144 Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } },
145 } 145 }
146 }) 146 })
147 } 147 }
148 } 148 }
149 149
150 Here, the port 0 of the "CAM0" device is conne 150 Here, the port 0 of the "CAM0" device is connected to the port 4 of
151 the "ISP" device and vice versa. 151 the "ISP" device and vice versa.
152 152
153 153
154 References 154 References
155 ========== 155 ==========
156 156
157 [acpi] Advanced Configuration and Power Interf 157 [acpi] Advanced Configuration and Power Interface Specification.
158 https://uefi.org/specifications/ACPI/6.4/, 158 https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30.
159 159
160 [data-node-ref] Documentation/firmware-guide/a 160 [data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst
161 161
162 [devicetree] Devicetree. https://www.devicetre 162 [devicetree] Devicetree. https://www.devicetree.org, referenced 2016-10-03.
163 163
164 [dsd-guide] DSD Guide. 164 [dsd-guide] DSD Guide.
165 https://github.com/UEFI/DSD-Guide/blob/mai 165 https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
166 2021-11-30. 166 2021-11-30.
167 167
168 [dsd-rules] _DSD Device Properties Usage Rules 168 [dsd-rules] _DSD Device Properties Usage Rules.
169 Documentation/firmware-guide/acpi/DSD-prop 169 Documentation/firmware-guide/acpi/DSD-properties-rules.rst
170 170
171 [graph-bindings] Common bindings for device gr 171 [graph-bindings] Common bindings for device graphs (Devicetree).
172 https://github.com/devicetree-org/dt-schem 172 https://github.com/devicetree-org/dt-schema/blob/main/schemas/graph.yaml,
173 referenced 2021-11-30. 173 referenced 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.