Documentation/acpi/dsd/graph.txt

   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 hierarchical
  40 data extension tree. The data extension related to each port node must begin
  41 with "port" and must be followed by the "@" character and the number of the port
  42 as its key. The target object it refers to should be called "PRTX", where "X" is
  43 the number of the port. An example of such a package would be:
  44
  45     Package() { "port@4", PRT4 }
  46
  47 Further on, endpoints are located under the port nodes. The hierarchical
  48 data extension key of the endpoint nodes must begin with
  49 "endpoint" and must be followed by the "@" character and the number of the
  50 endpoint. The object it refers to should be called "EPXY", where "X" is the
  51 number of the port and "Y" is the number of the endpoint. An example of such a
  52 package would be:
  53
  54     Package() { "endpoint@0", EP40 }
  55
  56 Each port node contains a property extension key "port", the value of which is
  57 the number of the port. Each endpoint is similarly numbered with a property
  58 extension key "reg", the value of which is the number of the endpoint. Port
  59 numbers must be unique within a device and endpoint numbers must be unique
  60 within a port. If a device object may only has a single port, then the number
  61 of that port shall be zero. Similarly, if a port may only have a single
  62 endpoint, the number of that endpoint shall be zero.
  63
  64 The endpoint reference uses property extension with "remote-endpoint" property
  65 name followed by a reference in the same package. Such references consist of the
  66 the remote device reference, the first package entry of the port data extension
  67 reference under the device and finally the first package entry of the endpoint
  68 data extension reference under the port. Individual references thus appear as:
  69
  70     Package() { device, "port@X", "endpoint@Y" }
  71
  72 In the above example, "X" is the number of the port and "Y" is the number of the
  73 endpoint.
  74
  75 The references to endpoints must be always done both ways, to the
  76 remote endpoint and back from the referred remote endpoint node.
  77
  78 A simple example of this is show below:
  79
  80     Scope (\_SB.PCI0.I2C2)
  81     {
  82         Device (CAM0)
  83         {
  84             Name (_DSD, Package () {
  85                 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
  86                 Package () {
  87                     Package () { "compatible", Package () { "nokia,smia" } },
  88                 },
  89                 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
  90                 Package () {
  91                     Package () { "port@0", PRT0 },
  92                 }
  93             })
  94             Name (PRT0, Package() {
  95                 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
  96                 Package () {
  97                     Package () { "reg", 0 },
  98                 },
  99                 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
 100                 Package () {
 101                     Package () { "endpoint@0", EP00 },
 102                 }
 103             })
 104             Name (EP00, Package() {
 105                 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
 106                 Package () {
 107                     Package () { "reg", 0 },
 108                     Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } },
 109                 }
 110             })
 111         }
 112     }
 113
 114     Scope (\_SB.PCI0)
 115     {
 116         Device (ISP)
 117         {
 118             Name (_DSD, Package () {
 119                 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
 120                 Package () {
 121                     Package () { "port@4", PRT4 },
 122                 }
 123             })
 124
 125             Name (PRT4, Package() {
 126                 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
 127                 Package () {
 128                     Package () { "reg", 4 }, /* CSI-2 port number */
 129                 },
 130                 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
 131                 Package () {
 132                     Package () { "endpoint@0", EP40 },
 133                 }
 134             })
 135
 136             Name (EP40, Package() {
 137                 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
 138                 Package () {
 139                     Package () { "reg", 0 },
 140                     Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } },
 141                 }
 142             })
 143         }
 144     }
 145
 146 Here, the port 0 of the "CAM0" device is connected to the port 4 of
 147 the "ISP" device and vice versa.
 148
 149
 150 References
 151 ----------
 152
 153 [1] _DSD (Device Specific Data) Implementation Guide.
 154     <URL:http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm>,
 155     referenced 2016-10-03.
 156
 157 [2] Devicetree. <URL:http://www.devicetree.org>, referenced 2016-10-03.
 158
 159 [3] Documentation/devicetree/bindings/graph.txt
 160
 161 [4] Device Properties UUID For _DSD.
 162     <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
 163     referenced 2016-10-04.
 164
 165 [5] Hierarchical Data Extension UUID For _DSD.
 166     <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
 167     referenced 2016-10-04.
 168
 169 [6] Advanced Configuration and Power Interface Specification.
 170     <URL:http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf>,
 171     referenced 2016-10-04.
 172
 173 [7] _DSD Device Properties Usage Rules.
 174     Documentation/acpi/DSD-properties-rules.txt