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 string reference in the same package. [data-node-ref]:: 70 71 "device.datanode" 72 73In the above example, "X" is the number of the port and "Y" is the number of 74the endpoint. 75 76The references to endpoints must be always done both ways, to the 77remote endpoint and back from the referred remote endpoint node. 78 79A simple example of this is show below:: 80 81 Scope (\_SB.PCI0.I2C2) 82 { 83 Device (CAM0) 84 { 85 Name (_DSD, Package () { 86 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), 87 Package () { 88 Package () { "compatible", Package () { "nokia,smia" } }, 89 }, 90 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), 91 Package () { 92 Package () { "port@0", "PRT0" }, 93 } 94 }) 95 Name (PRT0, Package() { 96 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), 97 Package () { 98 Package () { "reg", 0 }, 99 }, 100 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), 101 Package () { 102 Package () { "endpoint@0", "EP00" }, 103 } 104 }) 105 Name (EP00, Package() { 106 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), 107 Package () { 108 Package () { "reg", 0 }, 109 Package () { "remote-endpoint", "\\_SB.PCI0.ISP.EP40" }, 110 } 111 }) 112 } 113 } 114 115 Scope (\_SB.PCI0) 116 { 117 Device (ISP) 118 { 119 Name (_DSD, Package () { 120 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), 121 Package () { 122 Package () { "port@4", "PRT4" }, 123 } 124 }) 125 126 Name (PRT4, Package() { 127 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), 128 Package () { 129 Package () { "reg", 4 }, /* CSI-2 port number */ 130 }, 131 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), 132 Package () { 133 Package () { "endpoint@0", "EP40" }, 134 } 135 }) 136 137 Name (EP40, Package() { 138 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), 139 Package () { 140 Package () { "reg", 0 }, 141 Package () { "remote-endpoint", "\\_SB.PCI0.I2C2.CAM0.EP00" }, 142 } 143 }) 144 } 145 } 146 147Here, the port 0 of the "CAM0" device is connected to the port 4 of 148the "ISP" device and vice versa. 149 150 151References 152========== 153 154[acpi] Advanced Configuration and Power Interface Specification. 155 https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30. 156 157[data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst 158 159[devicetree] Devicetree. https://www.devicetree.org, referenced 2016-10-03. 160 161[dsd-guide] DSD Guide. 162 https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced 163 2021-11-30. 164 165[dsd-rules] _DSD Device Properties Usage Rules. 166 Documentation/firmware-guide/acpi/DSD-properties-rules.rst 167 168[graph-bindings] Common bindings for device graphs (Devicetree). 169 https://github.com/devicetree-org/dt-schema/blob/main/schemas/graph.yaml, 170 referenced 2021-11-30. 171