Changbin Du | f2dde1e | 2019-04-25 01:52:56 +0800 | [diff] [blame] | 1 | .. SPDX-License-Identifier: GPL-2.0 |
| 2 | |
| 3 | ====== |
| 4 | Graphs |
| 5 | ====== |
| 6 | |
| 7 | _DSD |
| 8 | ==== |
| 9 | |
| 10 | _DSD (Device Specific Data) [7] 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 [1][6]. There are two _DSD extensions that are relevant |
| 14 | for graphs: property [4] and hierarchical data extensions [5]. 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 | [3]. A port represents an interface in a device, and an endpoint |
| 40 | represents a connection to that interface. |
| 41 | |
| 42 | All port nodes are located under the device's "_DSD" node in the hierarchical |
| 43 | data extension tree. The data extension related to each port node must begin |
| 44 | with "port" and must be followed by the "@" character and the number of the |
| 45 | port as its key. The target object it refers to should be called "PRTX", where |
| 46 | "X" is the number of the port. An example of such a package would be:: |
| 47 | |
Sakari Ailus | a423bd8 | 2019-05-10 12:46:03 +0300 | [diff] [blame] | 48 | Package() { "port@4", "PRT4" } |
Changbin Du | f2dde1e | 2019-04-25 01:52:56 +0800 | [diff] [blame] | 49 | |
| 50 | Further on, endpoints are located under the port nodes. The hierarchical |
| 51 | data extension key of the endpoint nodes must begin with |
| 52 | "endpoint" and must be followed by the "@" character and the number of the |
| 53 | endpoint. The object it refers to should be called "EPXY", where "X" is the |
| 54 | number of the port and "Y" is the number of the endpoint. An example of such a |
| 55 | package would be:: |
| 56 | |
Sakari Ailus | a423bd8 | 2019-05-10 12:46:03 +0300 | [diff] [blame] | 57 | Package() { "endpoint@0", "EP40" } |
Changbin Du | f2dde1e | 2019-04-25 01:52:56 +0800 | [diff] [blame] | 58 | |
| 59 | Each port node contains a property extension key "port", the value of which is |
| 60 | the number of the port. Each endpoint is similarly numbered with a property |
| 61 | extension key "reg", the value of which is the number of the endpoint. Port |
| 62 | numbers must be unique within a device and endpoint numbers must be unique |
| 63 | within a port. If a device object may only has a single port, then the number |
| 64 | of that port shall be zero. Similarly, if a port may only have a single |
| 65 | endpoint, the number of that endpoint shall be zero. |
| 66 | |
| 67 | The endpoint reference uses property extension with "remote-endpoint" property |
| 68 | name followed by a reference in the same package. Such references consist of |
| 69 | the remote device reference, the first package entry of the port data extension |
| 70 | reference under the device and finally the first package entry of the endpoint |
| 71 | data extension reference under the port. Individual references thus appear as:: |
| 72 | |
| 73 | Package() { device, "port@X", "endpoint@Y" } |
| 74 | |
| 75 | In the above example, "X" is the number of the port and "Y" is the number of |
| 76 | the endpoint. |
| 77 | |
| 78 | The references to endpoints must be always done both ways, to the |
| 79 | remote endpoint and back from the referred remote endpoint node. |
| 80 | |
| 81 | A simple example of this is show below:: |
| 82 | |
| 83 | Scope (\_SB.PCI0.I2C2) |
| 84 | { |
Sakari Ailus | 5695f51 | 2019-05-10 12:46:02 +0300 | [diff] [blame] | 85 | Device (CAM0) |
| 86 | { |
| 87 | Name (_DSD, Package () { |
| 88 | ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), |
| 89 | Package () { |
| 90 | Package () { "compatible", Package () { "nokia,smia" } }, |
| 91 | }, |
| 92 | ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), |
| 93 | Package () { |
Sakari Ailus | a423bd8 | 2019-05-10 12:46:03 +0300 | [diff] [blame] | 94 | Package () { "port@0", "PRT0" }, |
Sakari Ailus | 5695f51 | 2019-05-10 12:46:02 +0300 | [diff] [blame] | 95 | } |
| 96 | }) |
| 97 | Name (PRT0, Package() { |
| 98 | ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), |
| 99 | Package () { |
| 100 | Package () { "reg", 0 }, |
| 101 | }, |
| 102 | ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), |
| 103 | Package () { |
Sakari Ailus | a423bd8 | 2019-05-10 12:46:03 +0300 | [diff] [blame] | 104 | Package () { "endpoint@0", "EP00" }, |
Sakari Ailus | 5695f51 | 2019-05-10 12:46:02 +0300 | [diff] [blame] | 105 | } |
| 106 | }) |
| 107 | Name (EP00, Package() { |
| 108 | ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), |
| 109 | Package () { |
| 110 | Package () { "reg", 0 }, |
| 111 | Package () { "remote-endpoint", Package() { \_SB.PCI0.ISP, "port@4", "endpoint@0" } }, |
| 112 | } |
| 113 | }) |
| 114 | } |
Changbin Du | f2dde1e | 2019-04-25 01:52:56 +0800 | [diff] [blame] | 115 | } |
| 116 | |
| 117 | Scope (\_SB.PCI0) |
| 118 | { |
Sakari Ailus | 5695f51 | 2019-05-10 12:46:02 +0300 | [diff] [blame] | 119 | Device (ISP) |
| 120 | { |
| 121 | Name (_DSD, Package () { |
| 122 | ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), |
| 123 | Package () { |
Sakari Ailus | a423bd8 | 2019-05-10 12:46:03 +0300 | [diff] [blame] | 124 | Package () { "port@4", "PRT4" }, |
Sakari Ailus | 5695f51 | 2019-05-10 12:46:02 +0300 | [diff] [blame] | 125 | } |
| 126 | }) |
Changbin Du | f2dde1e | 2019-04-25 01:52:56 +0800 | [diff] [blame] | 127 | |
Sakari Ailus | 5695f51 | 2019-05-10 12:46:02 +0300 | [diff] [blame] | 128 | Name (PRT4, Package() { |
| 129 | ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), |
| 130 | Package () { |
| 131 | Package () { "reg", 4 }, /* CSI-2 port number */ |
| 132 | }, |
| 133 | ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), |
| 134 | Package () { |
Sakari Ailus | a423bd8 | 2019-05-10 12:46:03 +0300 | [diff] [blame] | 135 | Package () { "endpoint@0", "EP40" }, |
Sakari Ailus | 5695f51 | 2019-05-10 12:46:02 +0300 | [diff] [blame] | 136 | } |
| 137 | }) |
Changbin Du | f2dde1e | 2019-04-25 01:52:56 +0800 | [diff] [blame] | 138 | |
Sakari Ailus | 5695f51 | 2019-05-10 12:46:02 +0300 | [diff] [blame] | 139 | Name (EP40, Package() { |
| 140 | ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), |
| 141 | Package () { |
| 142 | Package () { "reg", 0 }, |
| 143 | Package () { "remote-endpoint", Package () { \_SB.PCI0.I2C2.CAM0, "port@0", "endpoint@0" } }, |
| 144 | } |
| 145 | }) |
| 146 | } |
Changbin Du | f2dde1e | 2019-04-25 01:52:56 +0800 | [diff] [blame] | 147 | } |
| 148 | |
| 149 | Here, the port 0 of the "CAM0" device is connected to the port 4 of |
| 150 | the "ISP" device and vice versa. |
| 151 | |
| 152 | |
| 153 | References |
| 154 | ========== |
| 155 | |
| 156 | [1] _DSD (Device Specific Data) Implementation Guide. |
| 157 | http://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm, |
| 158 | referenced 2016-10-03. |
| 159 | |
| 160 | [2] Devicetree. http://www.devicetree.org, referenced 2016-10-03. |
| 161 | |
| 162 | [3] Documentation/devicetree/bindings/graph.txt |
| 163 | |
| 164 | [4] Device Properties UUID For _DSD. |
| 165 | http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf, |
| 166 | referenced 2016-10-04. |
| 167 | |
| 168 | [5] Hierarchical Data Extension UUID For _DSD. |
| 169 | http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf, |
| 170 | referenced 2016-10-04. |
| 171 | |
| 172 | [6] Advanced Configuration and Power Interface Specification. |
| 173 | http://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf, |
| 174 | referenced 2016-10-04. |
| 175 | |
| 176 | [7] _DSD Device Properties Usage Rules. |
| 177 | :doc:`../DSD-properties-rules` |