acpi/dsd/graph.rst

1 .. SPDX-License-Identifier: GPL-2.0
10 _DSD (Device Specific Data) [dsd-guide] is a predefined ACPI device
14 for graphs: property [dsd-guide] and hierarchical data extensions. The
15 property extension provides generic key-value pairs whereas the
19 a tree-like structure with zero or more properties (key-value pairs)
38 The port and endpoint concepts are very similar to those in Devicetree
39 [devicetree, graph-bindings]. A port represents an interface in a device, and
40 an endpoint represents a connection to that interface. Also see [data-node-ref]
43 All port nodes are located under the device's "_DSD" node in the hierarchical
44 data extension tree. The data extension related to each port node must begin
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 to should be called "PRTX", where
47 "X" is the number of the port. An example of such a package would be::
49     Package() { "port@4", "PRT4" }
51 Further on, endpoints are located under the port nodes. The hierarchical
52 data extension key of the endpoint nodes must begin with
53 "endpoint" and must be followed by the "@" character and the number of the
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 the endpoint. An example of such a
58     Package() { "endpoint@0", "EP40" }
60 Each port node contains a property extension key "port", the value of which is
61 the number of the port. Each endpoint is similarly numbered with a property
62 extension key "reg", the value of which is the number of the endpoint. Port
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 a single port, then the number
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 zero.
68 The endpoint reference uses property extension with "remote-endpoint" property
70 the remote device reference, the first package entry of the port data extension
71 reference under the device and finally the first package entry of the endpoint
72 data extension reference under the port. Individual references thus appear as::
74     Package() { device, "port@X", "endpoint@Y" }
76 In the above example, "X" is the number of the port and "Y" is the number of
77 the endpoint.
80 remote endpoint and back from the referred remote endpoint node.
89 		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
93 		ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
95 		    Package () { "port@0", "PRT0" },
99 		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
103 		ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
105 		    Package () { "endpoint@0", "EP00" },
109 		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
112 		    Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } },
123 		ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
125 		    Package () { "port@4", "PRT4" },
130 		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
132 		    Package () { "reg", 4 }, /* CSI-2 port number */
134 		ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
136 		    Package () { "endpoint@0", "EP40" },
141 		ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
144 		    Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } },
150 Here, the port 0 of the "CAM0" device is connected to the port 4 of
158     https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30.
160 [data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst
162 [devicetree] Devicetree. https://www.devicetree.org, referenced 2016-10-03.
164 [dsd-guide] DSD Guide.
165     https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
166     2021-11-30.
168 [dsd-rules] _DSD Device Properties Usage Rules.
169     Documentation/firmware-guide/acpi/DSD-properties-rules.rst
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.