graph.rst (8632987380765dee716d460640aa58d58d52998e) graph.rst (59f3f98284baa29da60410d04e498467c044aac2)
1.. SPDX-License-Identifier: GPL-2.0
2
3======
4Graphs
5======
6
7_DSD
8====
9
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
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
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
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_*

--- 8 unchanged lines hidden (view full) ---

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
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_*

--- 8 unchanged lines hidden (view full) ---

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.
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.
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" }

--- 99 unchanged lines hidden (view full) ---

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
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" }

--- 99 unchanged lines hidden (view full) ---

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
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.
157[acpi] Advanced Configuration and Power Interface Specification.
158 https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30.
159
159
160[2] Devicetree. https://www.devicetree.org, referenced 2016-10-03.
160[data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst
161
161
162[3] Documentation/devicetree/bindings/graph.txt
162[devicetree] Devicetree. https://www.devicetree.org, referenced 2016-10-03.
163
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.
164[dsd-guide] DSD Guide.
165 https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
166 2021-11-30.
167
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.
168[dsd-rules] _DSD Device Properties Usage Rules.
177 Documentation/firmware-guide/acpi/DSD-properties-rules.rst
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.