Documentation/firmware-guide/acpi/dsd/data-node-references.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2 .. include:: <isonum.txt>
   3
   4 ===================================
   5 Referencing hierarchical data nodes
   6 ===================================
   7
   8 :Copyright: |copy| 2018 Intel Corporation
   9 :Author: Sakari Ailus <sakari.ailus@linux.intel.com>
  10
  11 ACPI in general allows referring to device objects in the tree only.
  12 Hierarchical data extension nodes may not be referred to directly, hence this
  13 document defines a scheme to implement such references.
  14
  15 A reference consist of the device object name followed by one or more
  16 hierarchical data extension [1] keys. Specifically, the hierarchical data
  17 extension node which is referred to by the key shall lie directly under the
  18 parent object i.e. either the device object or another hierarchical data
  19 extension node.
  20
  21 The keys in the hierarchical data nodes shall consist of the name of the node,
  22 "@" character and the number of the node in hexadecimal notation (without pre-
  23 or postfixes). The same ACPI object shall include the _DSD property extension
  24 with a property "reg" that shall have the same numerical value as the number of
  25 the node.
  26
  27 In case a hierarchical data extensions node has no numerical value, then the
  28 "reg" property shall be omitted from the ACPI object's _DSD properties and the
  29 "@" character and the number shall be omitted from the hierarchical data
  30 extension key.
  31
  32
  33 Example
  34 =======
  35
  36 In the ASL snippet below, the "reference" _DSD property [2] contains a
  37 device object reference to DEV0 and under that device object, a
  38 hierarchical data extension key "node@1" referring to the NOD1 object
  39 and lastly, a hierarchical data extension key "anothernode" referring to
  40 the ANOD object which is also the final target node of the reference.
  41 ::
  42
  43         Device (DEV0)
  44         {
  45             Name (_DSD, Package () {
  46                 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
  47                 Package () {
  48                     Package () { "node@0", NOD0 },
  49                     Package () { "node@1", NOD1 },
  50                 }
  51             })
  52             Name (NOD0, Package() {
  53                 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
  54                 Package () {
  55                     Package () { "random-property", 3 },
  56                 }
  57             })
  58             Name (NOD1, Package() {
  59                 ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
  60                 Package () {
  61                     Package () { "anothernode", ANOD },
  62                 }
  63             })
  64             Name (ANOD, Package() {
  65                 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
  66                 Package () {
  67                     Package () { "random-property", 0 },
  68                 }
  69             })
  70         }
  71
  72         Device (DEV1)
  73         {
  74             Name (_DSD, Package () {
  75                 ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
  76                 Package () {
  77                     Package () { "reference", ^DEV0, "node@1", "anothernode" },
  78                 }
  79             })
  80         }
  81
  82 Please also see a graph example in :doc:`graph`.
  83
  84 References
  85 ==========
  86
  87 [1] Hierarchical Data Extension UUID For _DSD.
  88 <http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>,
  89 referenced 2018-07-17.
  90
  91 [2] Device Properties UUID For _DSD.
  92 <http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>,
  93 referenced 2016-10-04.