graph.rst

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