1.. SPDX-License-Identifier: GPL-2.0
2
3======
4Graphs
5======
6
7_DSD
8====
9
10_DSD (Device Specific Data) [dsd-guide] 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 [acpi]. There are two _DSD extensions that are relevant
14for graphs: property [dsd-guide] and hierarchical data extensions. 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[devicetree, graph-bindings]. A port represents an interface in a device, and
40an endpoint represents a connection to that interface. Also see [data-node-ref]
41for generic data node references.
42
43All port nodes are located under the device's "_DSD" node in the hierarchical
44data extension tree. The data extension related to each port node must begin
45with "port" and must be followed by the "@" character and the number of the
46port 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 such a package would be::
48
49    Package() { "port@4", "PRT4" }
50
51Further on, endpoints are located under the port nodes. The hierarchical
52data extension key of the endpoint nodes must begin with
53"endpoint" and must be followed by the "@" character and the number of the
54endpoint. The object it refers to should be called "EPXY", where "X" is the
55number of the port and "Y" is the number of the endpoint. An example of such a
56package would be::
57
58    Package() { "endpoint@0", "EP40" }
59
60Each port node contains a property extension key "port", the value of which is
61the number of the port. Each endpoint is similarly numbered with a property
62extension key "reg", the value of which is the number of the endpoint. Port
63numbers must be unique within a device and endpoint numbers must be unique
64within a port. If a device object may only has a single port, then the number
65of that port shall be zero. Similarly, if a port may only have a single
66endpoint, the number of that endpoint shall be zero.
67
68The endpoint reference uses property extension with "remote-endpoint" property
69name followed by a reference in the same package. Such references consist of
70the remote device reference, the first package entry of the port data extension
71reference under the device and finally the first package entry of the endpoint
72data extension reference under the port. Individual references thus appear as::
73
74    Package() { device, "port@X", "endpoint@Y" }
75
76In the above example, "X" is the number of the port and "Y" is the number of
77the endpoint.
78
79The references to endpoints must be always done both ways, to the
80remote endpoint and back from the referred remote endpoint node.
81
82A simple example of this is show below::
83
84    Scope (\_SB.PCI0.I2C2)
85    {
86	Device (CAM0)
87	{
88	    Name (_DSD, Package () {
89		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
90		Package () {
91		    Package () { "compatible", Package () { "nokia,smia" } },
92		},
93		ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
94		Package () {
95		    Package () { "port@0", "PRT0" },
96		}
97	    })
98	    Name (PRT0, Package() {
99		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
100		Package () {
101		    Package () { "reg", 0 },
102		},
103		ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
104		Package () {
105		    Package () { "endpoint@0", "EP00" },
106		}
107	    })
108	    Name (EP00, Package() {
109		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
110		Package () {
111		    Package () { "reg", 0 },
112		    Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } },
113		}
114	    })
115	}
116    }
117
118    Scope (\_SB.PCI0)
119    {
120	Device (ISP)
121	{
122	    Name (_DSD, Package () {
123		ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
124		Package () {
125		    Package () { "port@4", "PRT4" },
126		}
127	    })
128
129	    Name (PRT4, Package() {
130		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
131		Package () {
132		    Package () { "reg", 4 }, /* CSI-2 port number */
133		},
134		ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
135		Package () {
136		    Package () { "endpoint@0", "EP40" },
137		}
138	    })
139
140	    Name (EP40, Package() {
141		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
142		Package () {
143		    Package () { "reg", 0 },
144		    Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } },
145		}
146	    })
147	}
148    }
149
150Here, the port 0 of the "CAM0" device is connected to the port 4 of
151the "ISP" device and vice versa.
152
153
154References
155==========
156
157[acpi] Advanced Configuration and Power Interface Specification.
158    https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30.
159
160[data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst
161
162[devicetree] Devicetree. https://www.devicetree.org, referenced 2016-10-03.
163
164[dsd-guide] DSD Guide.
165    https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
166    2021-11-30.
167
168[dsd-rules] _DSD Device Properties Usage Rules.
169    Documentation/firmware-guide/acpi/DSD-properties-rules.rst
170
171[graph-bindings] Common bindings for device graphs (Devicetree).
172    https://github.com/devicetree-org/dt-schema/blob/main/schemas/graph.yaml,
173    referenced 2021-11-30.
174