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