Based on kernel version 4.16.1. Page generated on 2018-04-09 11:52 EST.
1 Graphs 2 3 4 _DSD 5 ---- 6 7 _DSD (Device Specific Data) [7] is a predefined ACPI device 8 configuration object that can be used to convey information on 9 hardware features which are not specifically covered by the ACPI 10 specification [1][6]. There are two _DSD extensions that are relevant 11 for graphs: property [4] and hierarchical data extensions [5]. The 12 property extension provides generic key-value pairs whereas the 13 hierarchical data extension supports nodes with references to other 14 nodes, forming a tree. The nodes in the tree may contain properties as 15 defined by the property extension. The two extensions together provide 16 a tree-like structure with zero or more properties (key-value pairs) 17 in each node of the tree. 18 19 The data structure may be accessed at runtime by using the device_* 20 and fwnode_* functions defined in include/linux/fwnode.h . 21 22 Fwnode represents a generic firmware node object. It is independent on 23 the firmware type. In ACPI, fwnodes are _DSD hierarchical data 24 extensions objects. A device's _DSD object is represented by an 25 fwnode. 26 27 The data structure may be referenced to elsewhere in the ACPI tables 28 by using a hard reference to the device itself and an index to the 29 hierarchical data extension array on each depth. 30 31 32 Ports and endpoints 33 ------------------- 34 35 The port and endpoint concepts are very similar to those in Devicetree 36 [3]. A port represents an interface in a device, and an endpoint 37 represents a connection to that interface. 38 39 All port nodes are located under the device's "_DSD" node in the 40 hierarchical data extension tree. The property extension related to 41 each port node must contain the key "port" and an integer value which 42 is the number of the port. The object it refers to should be called "PRTX", 43 where "X" is the number of the port. 44 45 Further on, endpoints are located under the individual port nodes. The 46 first hierarchical data extension package list entry of the endpoint 47 nodes must begin with "endpoint" and must be followed by the number 48 of 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 51 Each port node contains a property extension key "port", the value of 52 which is the number of the port node. The each endpoint is similarly numbered 53 with a property extension key "endpoint". Port numbers must be unique within a 54 device and endpoint numbers must be unique within a port. 55 56 The endpoint reference uses property extension with "remote-endpoint" property 57 name followed by a reference in the same package. Such references consist of the 58 the remote device reference, number of the port in the device and finally the 59 number of the endpoint in that port. Individual references thus appear as: 60 61 Package() { device, port_number, endpoint_number } 62 63 The references to endpoints must be always done both ways, to the 64 remote endpoint and back from the referred remote endpoint node. 65 66 A 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 134 Here, the port 0 of the "CAM0" device is connected to the port 4 of 135 the "ISP" device and vice versa. 136 137 138 References 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