174 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3======4Graphs5======6 7_DSD8====9 10_DSD (Device Specific Data) [dsd-guide] is a predefined ACPI device11configuration object that can be used to convey information on12hardware features which are not specifically covered by the ACPI13specification [acpi]. There are two _DSD extensions that are relevant14for graphs: property [dsd-guide] and hierarchical data extensions. The15property extension provides generic key-value pairs whereas the16hierarchical data extension supports nodes with references to other17nodes, forming a tree. The nodes in the tree may contain properties as18defined by the property extension. The two extensions together provide19a 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 on26the firmware type. In ACPI, fwnodes are _DSD hierarchical data27extensions objects. A device's _DSD object is represented by an28fwnode.29 30The data structure may be referenced to elsewhere in the ACPI tables31by using a hard reference to the device itself and an index to the32hierarchical data extension array on each depth.33 34 35Ports and endpoints36===================37 38The port and endpoint concepts are very similar to those in Devicetree39[devicetree, graph-bindings]. A port represents an interface in a device, and40an 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 hierarchical44data extension tree. The data extension related to each port node must begin45with "port" and must be followed by the "@" character and the number of the46port as its key. The target object it refers to should be called "PRTX", where47"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 hierarchical52data extension key of the endpoint nodes must begin with53"endpoint" and must be followed by the "@" character and the number of the54endpoint. The object it refers to should be called "EPXY", where "X" is the55number of the port and "Y" is the number of the endpoint. An example of such a56package would be::57 58 Package() { "endpoint@0", "EP40" }59 60Each port node contains a property extension key "port", the value of which is61the number of the port. Each endpoint is similarly numbered with a property62extension key "reg", the value of which is the number of the endpoint. Port63numbers must be unique within a device and endpoint numbers must be unique64within a port. If a device object may only has a single port, then the number65of that port shall be zero. Similarly, if a port may only have a single66endpoint, the number of that endpoint shall be zero.67 68The endpoint reference uses property extension with "remote-endpoint" property69name followed by a reference in the same package. Such references consist of70the remote device reference, the first package entry of the port data extension71reference under the device and finally the first package entry of the endpoint72data extension reference under the port. Individual references thus appear as::73 74 Package() { device, "port@X", "endpoint@Y" }75 76In the above example, "X" is the number of the port and "Y" is the number of77the endpoint.78 79The references to endpoints must be always done both ways, to the80remote endpoint and back from the referred remote endpoint node.81 82A 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 150Here, the port 0 of the "CAM0" device is connected to the port 4 of151the "ISP" device and vice versa.152 153 154References155==========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.rst161 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, referenced166 2021-11-30.167 168[dsd-rules] _DSD Device Properties Usage Rules.169 Documentation/firmware-guide/acpi/DSD-properties-rules.rst170 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.174