0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ======
0004 Graphs
0005 ======
0006
0007 _DSD
0008 ====
0009
0010 _DSD (Device Specific Data) [dsd-guide] is a predefined ACPI device
0011 configuration object that can be used to convey information on
0012 hardware features which are not specifically covered by the ACPI
0013 specification [acpi]. There are two _DSD extensions that are relevant
0014 for graphs: property [dsd-guide] and hierarchical data extensions. The
0015 property extension provides generic key-value pairs whereas the
0016 hierarchical data extension supports nodes with references to other
0017 nodes, forming a tree. The nodes in the tree may contain properties as
0018 defined by the property extension. The two extensions together provide
0019 a tree-like structure with zero or more properties (key-value pairs)
0020 in each node of the tree.
0021
0022 The data structure may be accessed at runtime by using the device_*
0023 and fwnode_* functions defined in include/linux/fwnode.h .
0024
0025 Fwnode represents a generic firmware node object. It is independent on
0026 the firmware type. In ACPI, fwnodes are _DSD hierarchical data
0027 extensions objects. A device's _DSD object is represented by an
0028 fwnode.
0029
0030 The data structure may be referenced to elsewhere in the ACPI tables
0031 by using a hard reference to the device itself and an index to the
0032 hierarchical data extension array on each depth.
0033
0034
0035 Ports and endpoints
0036 ===================
0037
0038 The port and endpoint concepts are very similar to those in Devicetree
0039 [devicetree, graph-bindings]. A port represents an interface in a device, and
0040 an endpoint represents a connection to that interface. Also see [data-node-ref]
0041 for generic data node references.
0042
0043 All port nodes are located under the device's "_DSD" node in the hierarchical
0044 data extension tree. The data extension related to each port node must begin
0045 with "port" and must be followed by the "@" character and the number of the
0046 port as its key. The target object it refers to should be called "PRTX", where
0047 "X" is the number of the port. An example of such a package would be::
0048
0049 Package() { "port@4", "PRT4" }
0050
0051 Further on, endpoints are located under the port nodes. The hierarchical
0052 data extension key of the endpoint nodes must begin with
0053 "endpoint" and must be followed by the "@" character and the number of the
0054 endpoint. The object it refers to should be called "EPXY", where "X" is the
0055 number of the port and "Y" is the number of the endpoint. An example of such a
0056 package would be::
0057
0058 Package() { "endpoint@0", "EP40" }
0059
0060 Each port node contains a property extension key "port", the value of which is
0061 the number of the port. Each endpoint is similarly numbered with a property
0062 extension key "reg", the value of which is the number of the endpoint. Port
0063 numbers must be unique within a device and endpoint numbers must be unique
0064 within a port. If a device object may only has a single port, then the number
0065 of that port shall be zero. Similarly, if a port may only have a single
0066 endpoint, the number of that endpoint shall be zero.
0067
0068 The endpoint reference uses property extension with "remote-endpoint" property
0069 name followed by a reference in the same package. Such references consist of
0070 the remote device reference, the first package entry of the port data extension
0071 reference under the device and finally the first package entry of the endpoint
0072 data extension reference under the port. Individual references thus appear as::
0073
0074 Package() { device, "port@X", "endpoint@Y" }
0075
0076 In the above example, "X" is the number of the port and "Y" is the number of
0077 the endpoint.
0078
0079 The references to endpoints must be always done both ways, to the
0080 remote endpoint and back from the referred remote endpoint node.
0081
0082 A simple example of this is show below::
0083
0084 Scope (\_SB.PCI0.I2C2)
0085 {
0086 Device (CAM0)
0087 {
0088 Name (_DSD, Package () {
0089 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
0090 Package () {
0091 Package () { "compatible", Package () { "nokia,smia" } },
0092 },
0093 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
0094 Package () {
0095 Package () { "port@0", "PRT0" },
0096 }
0097 })
0098 Name (PRT0, Package() {
0099 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
0100 Package () {
0101 Package () { "reg", 0 },
0102 },
0103 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
0104 Package () {
0105 Package () { "endpoint@0", "EP00" },
0106 }
0107 })
0108 Name (EP00, Package() {
0109 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
0110 Package () {
0111 Package () { "reg", 0 },
0112 Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } },
0113 }
0114 })
0115 }
0116 }
0117
0118 Scope (\_SB.PCI0)
0119 {
0120 Device (ISP)
0121 {
0122 Name (_DSD, Package () {
0123 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
0124 Package () {
0125 Package () { "port@4", "PRT4" },
0126 }
0127 })
0128
0129 Name (PRT4, Package() {
0130 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
0131 Package () {
0132 Package () { "reg", 4 }, /* CSI-2 port number */
0133 },
0134 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
0135 Package () {
0136 Package () { "endpoint@0", "EP40" },
0137 }
0138 })
0139
0140 Name (EP40, Package() {
0141 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
0142 Package () {
0143 Package () { "reg", 0 },
0144 Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } },
0145 }
0146 })
0147 }
0148 }
0149
0150 Here, the port 0 of the "CAM0" device is connected to the port 4 of
0151 the "ISP" device and vice versa.
0152
0153
0154 References
0155 ==========
0156
0157 [acpi] Advanced Configuration and Power Interface Specification.
0158 https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30.
0159
0160 [data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst
0161
0162 [devicetree] Devicetree. https://www.devicetree.org, referenced 2016-10-03.
0163
0164 [dsd-guide] DSD Guide.
0165 https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
0166 2021-11-30.
0167
0168 [dsd-rules] _DSD Device Properties Usage Rules.
0169 Documentation/firmware-guide/acpi/DSD-properties-rules.rst
0170
0171 [graph-bindings] Common bindings for device graphs (Devicetree).
0172 https://github.com/devicetree-org/dt-schema/blob/main/schemas/graph.yaml,
0173 referenced 2021-11-30.
