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