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
  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