Referencing hierarchical data nodes

계층적 데이터 노드 참조 규칙

이 문서는 2018년과 2021년 Intel Corporation 저작물이며 저자는 Sakari Ailus다. 일반적인 ACPI 참조는 tree 안의 device object만 가리킬 수 있고 hierarchical data extension node를 직접 가리킬 수 없으므로, 여기서는 그러한 노드를 참조하기 위한 별도 방식을 정의한다.

`_DSD` hierarchical data node에 대한 참조는 device object reference 뒤에 점(`.`)과 data node object까지의 relative path를 붙인 하나의 문자열이다. 반드시 문자열 참조를 사용해야 한다. 비문자열 참조를 사용하면 hierarchical data node에 대한 참조가 아니라 그 노드의 복사본이 만들어진다.

참조되는 hierarchical data extension node는 자신의 parent object 바로 아래에 있어야 한다. parent는 device object일 수도 있고 다른 hierarchical data extension node일 수도 있다. 이 직접 자식 배치 규칙은 DSD Guide [dsd-guide]의 계층 구조 규칙과 함께 적용한다.

hierarchical data node의 key는 node name, `@` 문자, 접두사나 접미사가 없는 16진수 node number를 차례로 이어 붙인다. 같은 ACPI object의 `_DSD` property extension에는 `reg` property가 있어야 하고, 그 숫자 값은 key에 적힌 node number와 같아야 한다.

hierarchical data extension node에 숫자 값이 없다면 ACPI object의 `_DSD` properties에서 `reg`를 생략한다. 동시에 hierarchical data extension key에서도 `@`와 number를 생략한다. 즉 `reg`만 없애거나 key의 숫자 부분만 없애는 식으로 두 표현을 불일치시켜서는 안 된다.

.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>

===================================
Referencing hierarchical data nodes
===================================

:Copyright: |copy| 2018, 2021 Intel Corporation
:Author: Sakari Ailus <[email protected]>

ACPI in general allows referring to device objects in the tree only.
Hierarchical data extension nodes may not be referred to directly, hence this
document defines a scheme to implement such references.

A reference to a _DSD hierarchical data node is a string consisting of a
device object reference followed by a dot (".") and a relative path to a data
node object. Do not use non-string references as this will produce a copy of
the hierarchical data node, not a reference!

The hierarchical data extension node which is referred to shall be located
directly under its parent object i.e. either the device object or another
hierarchical data extension node [dsd-guide].

The keys in the hierarchical data nodes shall consist of the name of the node,
"@" character and the number of the node in hexadecimal notation (without pre-
or postfixes). The same ACPI object shall include the _DSD property extension
with a property "reg" that shall have the same numerical value as the number of
the node.

In case a hierarchical data extensions node has no numerical value, then the
"reg" property shall be omitted from the ACPI object's _DSD properties and the
"@" character and the number shall be omitted from the hierarchical data
extension key.

DEV0의 대상 노드 계층

아래 ASL 예제에서 `reference` `_DSD` property는 `DEV1`의 parent 아래에 있는 `DEV0`의 hierarchical data extension node `ANOD`를 가리키는 문자열 참조를 담는다. `ANOD`는 이 참조의 최종 target node다.

`DEV0._DSD`는 hierarchical data extension UUID `dbb8e3e6-5886-4ba6-8795-1319f52a966b` 아래에 `"node@0" → "NOD0"`, `"node@1" → "NOD1"` 매핑을 둔다. 두 key의 16진수 숫자 0과 1은 각 대상 object의 `reg` 값과 일치한다.

`NOD0`는 Device Properties UUID `daffd814-6eba-4d8c-8a91-bc9bbf4aa301`을 사용한다. 그 property package에는 `reg=0`과 `random-property=3`이 들어 있다.

`NOD1`은 다시 hierarchical data extension UUID를 사용하며 `reg=1`과 `"anothernode" → "ANOD"` 매핑을 제공한다. `ANOD`는 `NOD1` 아래의 추가 data node object지만 숫자 식별자가 없으므로 key는 `anothernode`이며 `@number`가 없다.

최종 `ANOD`는 Device Properties UUID를 사용하고 `random-property=0`만 포함한다. 숫자 값이 없는 노드이므로 `reg` property도 없다. 이 구성이 앞 절의 key와 `reg` 동시 생략 규칙을 보여준다.

Example
=======

In the ASL snippet below, the "reference" _DSD property contains a string
reference to a hierarchical data extension node ANOD under DEV0 under the parent
of DEV1. ANOD is also the final target node of the reference.
::

        Device (DEV0)
        {
            Name (_DSD, Package () {
                ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
                Package () {
                    Package () { "node@0", "NOD0" },
                    Package () { "node@1", "NOD1" },
                }
            })
            Name (NOD0, Package() {
                ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
                Package () {
                    Package () { "reg", 0 },
                    Package () { "random-property", 3 },
                }
            })
            Name (NOD1, Package() {
                ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
                Package () {
                    Package () { "reg", 1 },
                    Package () { "anothernode", "ANOD" },
                }
            })
            Name (ANOD, Package() {
                ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
                Package () {
                    Package () { "random-property", 0 },
                }
            })
        }

DEV1의 문자열 참조와 참고 자료

`DEV1._DSD`는 Device Properties UUID `daffd814-6eba-4d8c-8a91-bc9bbf4aa301`을 사용하고, property package에 `Package () { "reference", "^DEV0.ANOD" }`를 둔다. 값 전체가 문자열이므로 `ANOD`의 package를 복사하는 것이 아니라 노드를 참조한다.

경로 `^DEV0.ANOD`의 `^`는 현재 scope인 `DEV1`에서 parent scope로 올라간다. 이어서 같은 parent 아래의 `DEV0`을 찾고, 점 뒤의 상대 경로를 따라 최종 data node object `ANOD`를 해석한다. 원문의 설명대로 최종 target은 `DEV0` 아래 계층에 있는 `ANOD`다.

관련 graph 예제는 `Documentation/firmware-guide/acpi/dsd/graph.rst`에서 확인할 수 있다. 규칙의 기준 문서 [dsd-guide]는 UEFI DSD Guide이며 원문 URL은 `https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc`이고, 문서에 기록된 참조일은 2021-11-30이다.

        Device (DEV1)
        {
            Name (_DSD, Package () {
                ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
                Package () {
                    Package () { "reference", "^DEV0.ANOD" }
                    },
                }
            })
        }

Please also see a graph example in
Documentation/firmware-guide/acpi/dsd/graph.rst.

References
==========

[dsd-guide] DSD Guide.
    https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
    2021-11-30.