_DSD Device Properties Usage Rules

속성·속성 집합·속성 하위 집합

ACPI 5.1에서 도입된 `_DSD`(Device Specific Data) 구성 객체를 사용하면 ACPI namespace를 통해 어떤 유형의 장치 구성 데이터든 제공할 수 있다. 데이터 형식은 원칙적으로 임의적일 수 있지만 UUID로 식별되어야 하며, `_DSD` 출력을 처리하는 드라이버가 그 UUID를 인식해야 한다.

Linux 커널의 ACPI subsystem이 인식하는 범용 `_DSD` UUID도 있다. ACPI subsystem은 이 UUID와 연결된 데이터 package를 자동으로 처리하고, 그 데이터를 장치 드라이버가 사용할 수 있는 device properties 형태로 제공한다.

하나의 device property는 문자열 key와 특정 type의 value로 구성된 data item이다. ACPI `_DSD` 문맥에서는 `_DSD` 반환 package 안에서 범용 Device Properties UUID 다음에 오는 sub-package의 원소다. 정확한 구조는 `_DSD (Device Specific Data) Implementation Guide` [1]의 `Well-Known _DSD UUIDs and Data Structure Formats` 절 아래 `Device Properties UUID` 하위 절에 정의되어 있다.

device property는 특정 장치의 Device Properties UUID sub-package에서 `_DSD`가 반환할 수 있는 key와 그에 연결된 data type의 정의라고 볼 수도 있다. property set은 장치 같은 하나의 hardware entity에 적용되는 property들의 모음이며, ACPI `_DSD`에서는 해당 장치의 Device Properties UUID sub-package가 반환할 수 있는 모든 property의 집합이다.

property subset은 중첩된 property 모음이다. 각 subset에는 전체를 가리키고 별도 entity처럼 다룰 수 있게 하는 추가 key, 즉 name이 연결된다. 표준 표현은 구현 안내서 [1]의 같은 절 아래 `Hierarchical Data Extension UUID` 하위 절에 정의된 메커니즘을 사용한다.

property set은 계층적일 수 있다. 하나의 property set이 여러 property subset을 포함하고, 각 subset이 다시 자체 property subset을 포함하는 구조를 필요한 깊이만큼 반복할 수 있다.

.. SPDX-License-Identifier: GPL-2.0

==================================
_DSD Device Properties Usage Rules
==================================

Properties, Property Sets and Property Subsets
==============================================

The _DSD (Device Specific Data) configuration object, introduced in ACPI 5.1,
allows any type of device configuration data to be provided via the ACPI
namespace.  In principle, the format of the data may be arbitrary, but it has to
be identified by a UUID which must be recognized by the driver processing the
_DSD output.  However, there are generic UUIDs defined for _DSD recognized by
the ACPI subsystem in the Linux kernel which automatically processes the data
packages associated with them and makes those data available to device drivers
as "device properties".

A device property is a data item consisting of a string key and a value (of a
specific type) associated with it.

In the ACPI _DSD context it is an element of the sub-package following the
generic Device Properties UUID in the _DSD return package as specified in the
section titled "Well-Known _DSD UUIDs and Data Structure Formats" sub-section
"Device Properties UUID" in _DSD (Device Specific Data) Implementation Guide
document [1]_.

It also may be regarded as the definition of a key and the associated data type
that can be returned by _DSD in the Device Properties UUID sub-package for a
given device.

A property set is a collection of properties applicable to a hardware entity
like a device.  In the ACPI _DSD context it is the set of all properties that
can be returned in the Device Properties UUID sub-package for the device in
question.

Property subsets are nested collections of properties.  Each of them is
associated with an additional key (name) allowing the subset to be referred
to as a whole (and to be treated as a separate entity).  The canonical
representation of property subsets is via the mechanism specified in the
section titled "Well-Known _DSD UUIDs and Data Structure Formats" sub-section
"Hierarchical Data Extension UUID" in _DSD (Device Specific Data)
Implementation Guide document [1]_.

Property sets may be hierarchical.  That is, a property set may contain
multiple property subsets that each may contain property subsets of its
own and so on.

속성 집합의 일반 유효성 규칙

유효한 property set은 Device Properties UUID 정의 문서 [1]의 지침을 따라야 한다. 데이터 구조가 구문상 올바른 것만으로는 충분하지 않고, 해당 데이터를 `_DSD`로 제공하는 용도 자체도 ACPI의 설계 원칙에 맞아야 한다.

`_DSD` property는 ACPI specification에 이미 정의된 메커니즘을 대체하기 위한 것이 아니라, 그 메커니즘에 추가해서 사용하기 위한 것이다. 따라서 일반적으로 기반 use case를 직접 처리하는 규정이 ACPI specification에 없을 때만 `_DSD` property를 사용해야 한다.

ACPI specification에 직접적인 처리 방법이 있는데도 같은 목적의 property set을 Device Properties UUID와 연결된 `_DSD` data package로 반환하면 일반적으로 유효하지 않다. 이 규칙은 기존 ACPI object와 `_DSD` 사이의 중복된 제어 경로를 막는다.

General Validity Rule for Property Sets
=======================================

Valid property sets must follow the guidance given by the Device Properties UUID
definition document [1].

_DSD properties are intended to be used in addition to, and not instead of, the
existing mechanisms defined by the ACPI specification.  Therefore, as a rule,
they should only be used if the ACPI specification does not make direct
provisions for handling the underlying use case.  It generally is invalid to
return property sets which do not follow that rule from _DSD in data packages
associated with the Device Properties UUID.

AML과의 충돌에 관한 추가 고려 사항

앞의 일반 규칙을 원칙적으로 따랐더라도 property set이 여전히 유효하지 않을 수 있다. 특히 device property로 인해 kernel code, 즉 device driver 또는 library·subsystem이 ACPI namespace의 AML method와 충돌할 수 있는 방식으로 hardware에 접근한다면 문제가 된다.

대표적인 경우는 kernel code가 device property를 사용해 원래 ACPI method가 제어하는 hardware를 직접 조작하는 것이다. device object의 power management에는 `_PSx`와 `_DSW`, power resource object에는 `_ON`과 `_OFF`가 관련되며, ACPI device 비활성화·활성화에는 `_DIS`와 `_SRS` 같은 method가 사용된다.

device property 사용 결과로 kernel code가 AML의 상태 가정을 혼란스럽게 만들 수 있는 모든 경우에 그 property는 ACPI 환경에 적합하지 않다. 따라서 해당 property는 유효한 property set에 포함될 수 없다. 실제 충돌이 이미 관찰되어야만 무효가 되는 것이 아니라, AML을 혼란시킬 가능성이 판단 기준이다.

Additional Considerations
-------------------------

There are cases in which, even if the general rule given above is followed in
principle, the property set may still not be regarded as a valid one.

For example, that applies to device properties which may cause kernel code
(either a device driver or a library/subsystem) to access hardware in a way
possibly leading to a conflict with AML methods in the ACPI namespace.  In
particular, that may happen if the kernel code uses device properties to
manipulate hardware normally controlled by ACPI methods related to power
management, like _PSx and _DSW (for device objects) or _ON and _OFF (for power
resource objects), or by ACPI device disabling/enabling methods, like _DIS and
_SRS.

In all cases in which kernel code may do something that will confuse AML as a
result of using device properties, the device properties in question are not
suitable for the ACPI environment and consequently they cannot belong to a valid
property set.

Device Tree binding과 속성 집합

`_DSD`가 Device Tree binding을 따르는 property set을 반환하도록 만드는 것은 코드 재사용 측면에서 유용한 경우가 많다. 동일한 property API를 사용하면 드라이버가 firmware 표현 방식에 따라 별도의 구성 파서를 둘 필요를 줄일 수 있다.

그러나 가장 먼저 앞의 유효성 고려 사항을 적용해야 하며, 유효하지 않은 property set을 `_DSD`에서 반환해서는 안 된다. 이 때문에 특정 DT binding을 문자 그대로 완전하게 `_DSD`로 옮기는 것이 불가능할 수 있다.

코드 재사용을 위해 가능한 구성 데이터는 device properties로 제공하되, ACPI에서 안전하게 표현할 수 없는 부분은 해당 use case에 적합한 ACPI 전용 메커니즘으로 보완할 수 있다. 즉 DT binding과의 유사성보다 ACPI 제어 모델의 일관성이 우선한다.

어떤 경우에도 DT binding을 문자 그대로 따른 property set이 내용과 무관하게 ACPI 환경에서 자동으로 동작할 것이라고 기대해서는 안 된다. 각 property의 의미와 AML 충돌 가능성을 ACPI 관점에서 다시 검증해야 한다.

참고 문서 [1]은 UEFI의 `_DSD (Device Specific Data) Implementation Guide`이며 원문 URL은 `https://github.com/UEFI/DSD-Guide`다.

Property Sets and Device Tree Bindings
======================================

It often is useful to make _DSD return property sets that follow Device Tree
bindings.

In those cases, however, the above validity considerations must be taken into
account in the first place and returning invalid property sets from _DSD must be
avoided.  For this reason, it may not be possible to make _DSD return a property
set following the given DT binding literally and completely.  Still, for the
sake of code re-use, it may make sense to provide as much of the configuration
data as possible in the form of device properties and complement that with an
ACPI-specific mechanism suitable for the use case at hand.

In any case, property sets following DT bindings literally should not be
expected to automatically work in the ACPI environment regardless of their
contents.

References
==========

.. [1] https://github.com/UEFI/DSD-Guide