Documentation/firmware-guide/acpi/dsd/graph.rst

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