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    http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm,
158    referenced 2016-10-03.
159
160[2] Devicetree. http://www.devicetree.org, referenced 2016-10-03.
161
162[3] Documentation/devicetree/bindings/graph.txt
163
164[4] Device Properties UUID For _DSD.
165    http://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    http://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    http://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