blob: 1a6ce7afba5ead79edb91c0c8a179cb20f058104 [file] [log] [blame]
Changbin Duf2dde1e2019-04-25 01:52:56 +08001.. 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
Sakari Ailusa423bd82019-05-10 12:46:03 +030048 Package() { "port@4", "PRT4" }
Changbin Duf2dde1e2019-04-25 01:52:56 +080049
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
Sakari Ailusa423bd82019-05-10 12:46:03 +030057 Package() { "endpoint@0", "EP40" }
Changbin Duf2dde1e2019-04-25 01:52:56 +080058
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 {
Sakari Ailus5695f512019-05-10 12:46:02 +030085 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 () {
Sakari Ailusa423bd82019-05-10 12:46:03 +030094 Package () { "port@0", "PRT0" },
Sakari Ailus5695f512019-05-10 12:46:02 +030095 }
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 () {
Sakari Ailusa423bd82019-05-10 12:46:03 +0300104 Package () { "endpoint@0", "EP00" },
Sakari Ailus5695f512019-05-10 12:46:02 +0300105 }
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 }
Changbin Duf2dde1e2019-04-25 01:52:56 +0800115 }
116
117 Scope (\_SB.PCI0)
118 {
Sakari Ailus5695f512019-05-10 12:46:02 +0300119 Device (ISP)
120 {
121 Name (_DSD, Package () {
122 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
123 Package () {
Sakari Ailusa423bd82019-05-10 12:46:03 +0300124 Package () { "port@4", "PRT4" },
Sakari Ailus5695f512019-05-10 12:46:02 +0300125 }
126 })
Changbin Duf2dde1e2019-04-25 01:52:56 +0800127
Sakari Ailus5695f512019-05-10 12:46:02 +0300128 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 () {
Sakari Ailusa423bd82019-05-10 12:46:03 +0300135 Package () { "endpoint@0", "EP40" },
Sakari Ailus5695f512019-05-10 12:46:02 +0300136 }
137 })
Changbin Duf2dde1e2019-04-25 01:52:56 +0800138
Sakari Ailus5695f512019-05-10 12:46:02 +0300139 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 }
Changbin Duf2dde1e2019-04-25 01:52:56 +0800147 }
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[3Documentation/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`