1 .. SPDX-License-Identifier: GPL-2.0
10 _DSD (Device Specific Data) [7] is a predefined ACPI device
11 configuration object that can be used to convey information on
12 hardware features which are not specifically covered by the ACPI
13 specification [1][6]. There are two _DSD extensions that are relevant
14 for graphs: property [4] and hierarchical data extensions [5]. The
15 property extension provides generic key-value pairs whereas the
16 hierarchical data extension supports nodes with references to other
17 nodes, forming a tree. The nodes in the tree may contain properties as
18 defined by the property extension. The two extensions together provide
19 a tree-like structure with zero or more properties (key-value pairs)
20 in each node of the tree.
22 The data structure may be accessed at runtime by using the device_*
23 and fwnode_* functions defined in include/linux/fwnode.h .
25 Fwnode represents a generic firmware node object. It is independent on
26 the firmware type. In ACPI, fwnodes are _DSD hierarchical data
27 extensions objects. A device's _DSD object is represented by an
30 The data structure may be referenced to elsewhere in the ACPI tables
31 by using a hard reference to the device itself and an index to the
32 hierarchical data extension array on each depth.
38 The port and endpoint concepts are very similar to those in Devicetree
39 [3]. A port represents an interface in a device, and an endpoint
40 represents a connection to that interface.
42 All port nodes are located under the device's "_DSD" node in the hierarchical
43 data extension tree. The data extension related to each port node must begin
44 with "port" and must be followed by the "@" character and the number of the
45 port as its key. The target object it refers to should be called "PRTX", where
46 "X" is the number of the port. An example of such a package would be::
48 Package() { "port@4", "PRT4" }
50 Further on, endpoints are located under the port nodes. The hierarchical
51 data extension key of the endpoint nodes must begin with
52 "endpoint" and must be followed by the "@" character and the number of the
53 endpoint. The object it refers to should be called "EPXY", where "X" is the
54 number of the port and "Y" is the number of the endpoint. An example of such a
57 Package() { "endpoint@0", "EP40" }
59 Each port node contains a property extension key "port", the value of which is
60 the number of the port. Each endpoint is similarly numbered with a property
61 extension key "reg", the value of which is the number of the endpoint. Port
62 numbers must be unique within a device and endpoint numbers must be unique
63 within a port. If a device object may only has a single port, then the number
64 of that port shall be zero. Similarly, if a port may only have a single
65 endpoint, the number of that endpoint shall be zero.
67 The endpoint reference uses property extension with "remote-endpoint" property
68 name followed by a reference in the same package. Such references consist of
69 the remote device reference, the first package entry of the port data extension
70 reference under the device and finally the first package entry of the endpoint
71 data extension reference under the port. Individual references thus appear as::
73 Package() { device, "port@X", "endpoint@Y" }
75 In the above example, "X" is the number of the port and "Y" is the number of
78 The references to endpoints must be always done both ways, to the
79 remote endpoint and back from the referred remote endpoint node.
81 A simple example of this is show below::
83 Scope (\_SB.PCI0.I2C2)
87 Name (_DSD, Package () {
88 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
90 Package () { "compatible", Package () { "nokia,smia" } },
92 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
94 Package () { "port@0", "PRT0" },
97 Name (PRT0, Package() {
98 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
100 Package () { "reg", 0 },
102 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
104 Package () { "endpoint@0", "EP00" },
107 Name (EP00, Package() {
108 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
110 Package () { "reg", 0 },
111 Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } },
121 Name (_DSD, Package () {
122 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
124 Package () { "port@4", "PRT4" },
128 Name (PRT4, Package() {
129 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
131 Package () { "reg", 4 }, /* CSI-2 port number */
133 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
135 Package () { "endpoint@0", "EP40" },
139 Name (EP40, Package() {
140 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
142 Package () { "reg", 0 },
143 Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } },
149 Here, the port 0 of the "CAM0" device is connected to the port 4 of
150 the "ISP" device and vice versa.
156 [1] _DSD (Device Specific Data) Implementation Guide.
157 https://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm,
158 referenced 2016-10-03.
160 [2] Devicetree. https://www.devicetree.org, referenced 2016-10-03.
162 [3] Documentation/devicetree/bindings/graph.txt
164 [4] Device Properties UUID For _DSD.
165 https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf,
166 referenced 2016-10-04.
168 [5] Hierarchical Data Extension UUID For _DSD.
169 https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf,
170 referenced 2016-10-04.
172 [6] Advanced Configuration and Power Interface Specification.
173 https://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf,
174 referenced 2016-10-04.
176 [7] _DSD Device Properties Usage Rules.
177 :doc:`../DSD-properties-rules`