1Graphs 2 3 4_DSD 5---- 6 7_DSD (Device Specific Data) [7] is a predefined ACPI device 8configuration object that can be used to convey information on 9hardware features which are not specifically covered by the ACPI 10specification [1][6]. There are two _DSD extensions that are relevant 11for graphs: property [4] and hierarchical data extensions [5]. The 12property extension provides generic key-value pairs whereas the 13hierarchical data extension supports nodes with references to other 14nodes, forming a tree. The nodes in the tree may contain properties as 15defined by the property extension. The two extensions together provide 16a tree-like structure with zero or more properties (key-value pairs) 17in each node of the tree. 18 19The data structure may be accessed at runtime by using the device_* 20and fwnode_* functions defined in include/linux/fwnode.h . 21 22Fwnode represents a generic firmware node object. It is independent on 23the firmware type. In ACPI, fwnodes are _DSD hierarchical data 24extensions objects. A device's _DSD object is represented by an 25fwnode. 26 27The data structure may be referenced to elsewhere in the ACPI tables 28by using a hard reference to the device itself and an index to the 29hierarchical data extension array on each depth. 30 31 32Ports and endpoints 33------------------- 34 35The port and endpoint concepts are very similar to those in Devicetree 36[3]. A port represents an interface in a device, and an endpoint 37represents a connection to that interface. 38 39All port nodes are located under the device's "_DSD" node in the 40hierarchical data extension tree. The property extension related to 41each port node must contain the key "port" and an integer value which 42is the number of the port. The object it refers to should be called "PRTX", 43where "X" is the number of the port. 44 45Further on, endpoints are located under the individual port nodes. The 46first hierarchical data extension package list entry of the endpoint 47nodes must begin with "endpoint" and must be followed by the number 48of the endpoint. The object it refers to should be called "EPXY", where 49"X" is the number of the port and "Y" is the number of the endpoint. 50 51Each port node contains a property extension key "port", the value of 52which is the number of the port node. The each endpoint is similarly numbered 53with a property extension key "endpoint". Port numbers must be unique within a 54device and endpoint numbers must be unique within a port. 55 56The endpoint reference uses property extension with "remote-endpoint" property 57name followed by a reference in the same package. Such references consist of the 58the remote device reference, number of the port in the device and finally the 59number of the endpoint in that port. Individual references thus appear as: 60 61 Package() { device, port_number, endpoint_number } 62 63The references to endpoints must be always done both ways, to the 64remote endpoint and back from the referred remote endpoint node. 65 66A simple example of this is show below: 67 68 Scope (\_SB.PCI0.I2C2) 69 { 70 Device (CAM0) 71 { 72 Name (_DSD, Package () { 73 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), 74 Package () { 75 Package () { "compatible", Package () { "nokia,smia" } }, 76 }, 77 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), 78 Package () { 79 Package () { "port0", "PRT0" }, 80 } 81 }) 82 Name (PRT0, Package() { 83 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), 84 Package () { 85 Package () { "port", 0 }, 86 }, 87 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), 88 Package () { 89 Package () { "endpoint0", "EP00" }, 90 } 91 }) 92 Name (EP00, Package() { 93 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), 94 Package () { 95 Package () { "endpoint", 0 }, 96 Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, 4, 0 } }, 97 } 98 }) 99 } 100 } 101 102 Scope (\_SB.PCI0) 103 { 104 Device (ISP) 105 { 106 Name (_DSD, Package () { 107 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), 108 Package () { 109 Package () { "port4", "PRT4" }, 110 } 111 }) 112 113 Name (PRT4, Package() { 114 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), 115 Package () { 116 Package () { "port", 4 }, /* CSI-2 port number */ 117 }, 118 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), 119 Package () { 120 Package () { "endpoint0", "EP40" }, 121 } 122 }) 123 124 Name (EP40, Package() { 125 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), 126 Package () { 127 Package () { "endpoint", 0 }, 128 Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, 0, 0 } }, 129 } 130 }) 131 } 132 } 133 134Here, the port 0 of the "CAM0" device is connected to the port 4 of 135the "ISP" device and vice versa. 136 137 138References 139---------- 140 141[1] _DSD (Device Specific Data) Implementation Guide. 142 <URL:http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm>, 143 referenced 2016-10-03. 144 145[2] Devicetree. <URL:http://www.devicetree.org>, referenced 2016-10-03. 146 147[3] Documentation/devicetree/bindings/graph.txt 148 149[4] Device Properties UUID For _DSD. 150 <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, 151 referenced 2016-10-04. 152 153[5] Hierarchical Data Extension UUID For _DSD. 154 <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.pdf>, 155 referenced 2016-10-04. 156 157[6] Advanced Configuration and Power Interface Specification. 158 <URL:http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf>, 159 referenced 2016-10-04. 160 161[7] _DSD Device Properties Usage Rules. 162 Documentation/acpi/DSD-properties-rules.txt 163