요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
======
Graphs
======
_DSD
====
_DSD (Device Specific Data) [dsd-guide] is a predefined ACPI device
configuration object that can be used to convey information on
hardware features which are not specifically covered by the ACPI
specification [acpi]. There are two _DSD extensions that are relevant
for graphs: property [dsd-guide] and hierarchical data extensions. The
property extension provides generic key-value pairs whereas the
hierarchical data extension supports nodes with references to other
nodes, forming a tree. The nodes in the tree may contain properties as
defined by the property extension. The two extensions together provide
a tree-like structure with zero or more properties (key-value pairs)
in each node of the tree.
The data structure may be accessed at runtime by using the device_*
and fwnode_* functions defined in include/linux/fwnode.h .
Fwnode represents a generic firmware node object. It is independent on
the firmware type. In ACPI, fwnodes are _DSD hierarchical data
extensions objects. A device's _DSD object is represented by an
fwnode.
The data structure may be referenced to elsewhere in the ACPI tables
by using a hard reference to the device itself and an index to the
hierarchical data extension array on each depth.
Ports and endpoints
===================
The port and endpoint concepts are very similar to those in Devicetree
[devicetree, graph-bindings]. A port represents an interface in a device, and
an endpoint represents a connection to that interface. Also see [data-node-ref]
for generic data node references.
All port nodes are located under the device's "_DSD" node in the hierarchical
data extension tree. The data extension related to each port node must begin
with "port" and must be followed by the "@" character and the number of the
port as its key. The target object it refers to should be called "PRTX", where
"X" is the number of the port. An example of such a package would be::
Package() { "port@4", "PRT4" }
Further on, endpoints are located under the port nodes. The hierarchical
data extension key of the endpoint nodes must begin with
"endpoint" and must be followed by the "@" character and the number of the
endpoint. The object it refers to should be called "EPXY", where "X" is the
number of the port and "Y" is the number of the endpoint. An example of such a
package would be::
Package() { "endpoint@0", "EP40" }
Each port node contains a property extension key "port", the value of which is
the number of the port. Each endpoint is similarly numbered with a property
extension key "reg", the value of which is the number of the endpoint. Port
numbers must be unique within a device and endpoint numbers must be unique
within a port. If a device object may only has a single port, then the number
of that port shall be zero. Similarly, if a port may only have a single
endpoint, the number of that endpoint shall be zero.
The endpoint reference uses property extension with "remote-endpoint" property
name followed by a string reference in the same package. [data-node-ref]::
"device.datanode"
In the above example, "X" is the number of the port and "Y" is the number of
the endpoint.
The references to endpoints must be always done both ways, to the
remote endpoint and back from the referred remote endpoint node.
A simple example of this is show below::
Scope (\_SB.PCI0.I2C2)
{
Device (CAM0)
{
Name (_DSD, Package () {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () {
Package () { "compatible", Package () { "nokia,smia" } },
},
ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
Package () {
Package () { "port@0", "PRT0" },
}
})
Name (PRT0, Package() {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () {
Package () { "reg", 0 },
},
ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
Package () {
Package () { "endpoint@0", "EP00" },
}
})
Name (EP00, Package() {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () {
Package () { "reg", 0 },
Package () { "remote-endpoint", "\\_SB.PCI0.ISP.EP40" },
}
})
}
}
Scope (\_SB.PCI0)
{
Device (ISP)
{
Name (_DSD, Package () {
ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
Package () {
Package () { "port@4", "PRT4" },
}
})
Name (PRT4, Package() {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () {
Package () { "reg", 4 }, /* CSI-2 port number */
},
ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
Package () {
Package () { "endpoint@0", "EP40" },
}
})
Name (EP40, Package() {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () {
Package () { "reg", 0 },
Package () { "remote-endpoint", "\\_SB.PCI0.I2C2.CAM0.EP00" },
}
})
}
}
Here, the port 0 of the "CAM0" device is connected to the port 4 of
the "ISP" device and vice versa.
References
==========
[acpi] Advanced Configuration and Power Interface Specification.
https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30.
[data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst
[devicetree] Devicetree. https://www.devicetree.org, referenced 2016-10-03.
[dsd-guide] DSD Guide.
https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
2021-11-30.
[dsd-rules] _DSD Device Properties Usage Rules.
Documentation/firmware-guide/acpi/DSD-properties-rules.rst
[graph-bindings] Common bindings for device graphs (Devicetree).
https://github.com/devicetree-org/dt-schema/blob/main/schemas/graph.yaml,
referenced 2021-11-30.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
_DSD graph의 기반 구조
1-33`_DSD`(Device Specific Data) [dsd-guide]는 ACPI specification [acpi]이 구체적으로 다루지 않는 하드웨어 기능 정보를 전달하는 데 사용할 수 있는 사전 정의 ACPI device configuration object다.
graph와 관련된 `_DSD` extension은 property extension과 hierarchical data extension 두 가지다. property extension은 범용 key-value pair를 제공하고, hierarchical data extension은 다른 node를 참조하는 node를 지원해 tree를 구성한다. tree의 각 node는 property extension이 정의한 property를 포함할 수 있다.
두 extension을 결합하면 tree의 각 node가 0개 이상의 property, 즉 key-value pair를 갖는 tree-like structure가 된다. graph 표현은 이 계층과 node 사이의 참조를 함께 사용한다.
두 extension이 담당하는 역할과 결합 결과를 구분한다.
런타임에는 `include/linux/fwnode.h`에 정의된 `device_*` 함수와 `fwnode_*` 함수를 사용해 이 data structure에 접근할 수 있다. `fwnode`는 firmware type과 독립적인 범용 firmware node object다.
ACPI에서 fwnode는 `_DSD` hierarchical data extension object를 나타내며, device의 `_DSD` object도 하나의 fwnode로 표현된다. 따라서 드라이버는 ACPI 전용 package 구조를 직접 해석하기보다 firmware node API를 사용할 수 있다.
ACPI table의 다른 위치에서 이 data structure를 참조할 때는 device 자체에 대한 hard reference와 각 depth의 hierarchical data extension array index를 사용한다. 각 단계의 index를 보존해야 원하는 하위 node를 정확히 찾을 수 있다.
원시 _DSD package가 드라이버의 범용 fwnode 접근으로 이어지는 흐름이다.
.. SPDX-License-Identifier: GPL-2.0
======
Graphs
======
_DSD
====
_DSD (Device Specific Data) [dsd-guide] is a predefined ACPI device
configuration object that can be used to convey information on
hardware features which are not specifically covered by the ACPI
specification [acpi]. There are two _DSD extensions that are relevant
for graphs: property [dsd-guide] and hierarchical data extensions. The
property extension provides generic key-value pairs whereas the
hierarchical data extension supports nodes with references to other
nodes, forming a tree. The nodes in the tree may contain properties as
defined by the property extension. The two extensions together provide
a tree-like structure with zero or more properties (key-value pairs)
in each node of the tree.
The data structure may be accessed at runtime by using the device_*
and fwnode_* functions defined in include/linux/fwnode.h .
Fwnode represents a generic firmware node object. It is independent on
the firmware type. In ACPI, fwnodes are _DSD hierarchical data
extensions objects. A device's _DSD object is represented by an
fwnode.
The data structure may be referenced to elsewhere in the ACPI tables
by using a hard reference to the device itself and an index to the
hierarchical data extension array on each depth.
Port와 endpoint 규칙
34-78port와 endpoint 개념은 Devicetree [devicetree, graph-bindings]의 개념과 매우 비슷하다. port는 device의 interface를 나타내고 endpoint는 그 interface에 대한 connection을 나타낸다. 일반 data node reference 규칙은 [data-node-ref]도 함께 참조한다.
모든 port node는 device의 `_DSD` node 아래 hierarchical data extension tree에 놓인다. 각 port node의 data extension key는 `port`, `@`, port number 순서로 구성하며, 참조 대상 object 이름은 port number X를 넣은 `PRTX`여야 한다. 예를 들어 `Package() { "port@4", "PRT4" }`는 port 4를 `PRT4` object에 연결한다.
endpoint는 port node 아래에 놓인다. endpoint node의 hierarchical data extension key는 `endpoint`, `@`, endpoint number로 구성하고, 대상 object 이름은 port number X와 endpoint number Y를 넣은 `EPXY`여야 한다. `Package() { "endpoint@0", "EP40" }`는 port 4의 endpoint 0을 `EP40`에 연결한다.
Key, object name, 숫자 X·Y의 의미를 원문 규칙대로 대응시켰다.
Port와 endpoint가 _DSD hierarchical tree 안에 배치되는 순서다.
각 port node는 property extension key `port`를 포함하고 그 값은 port number다. 각 endpoint는 비슷하게 `reg` key를 포함하고 그 값은 endpoint number다. device 안의 port number는 고유해야 하고, 한 port 안의 endpoint number도 고유해야 한다.
하나의 port만 가질 수 있는 device에서는 그 port number가 0이어야 한다. 마찬가지로 하나의 endpoint만 가질 수 있는 port에서는 endpoint number가 0이어야 한다.
원문 규칙 문장은 port node의 숫자 property를 `port`라고 부르지만, 이어지는 ASL 예제의 `PRT0`과 `PRT4`는 각각 `Package () { "reg", 0 }`, `Package () { "reg", 4 }`를 사용한다. 이 차이는 원문에 존재하므로 전문 번역과 원문 코드에서 모두 그대로 보존하며 임의로 하나로 정규화하지 않는다.
Port와 endpoint 번호의 범위별 고유성과 단일 항목 규칙이다.
endpoint reference는 property extension의 `remote-endpoint` property name과 같은 package 안에 놓인 문자열 참조를 사용한다. 일반 형식은 `"device.datanode"`다. endpoint 참조는 반드시 양방향이어야 하므로 local endpoint에서 remote endpoint를 가리키는 참조와, remote endpoint에서 다시 local endpoint를 가리키는 역참조가 모두 있어야 한다.
한쪽 참조만으로는 유효한 graph edge가 완성되지 않는다.
Ports and endpoints
===================
The port and endpoint concepts are very similar to those in Devicetree
[devicetree, graph-bindings]. A port represents an interface in a device, and
an endpoint represents a connection to that interface. Also see [data-node-ref]
for generic data node references.
All port nodes are located under the device's "_DSD" node in the hierarchical
data extension tree. The data extension related to each port node must begin
with "port" and must be followed by the "@" character and the number of the
port as its key. The target object it refers to should be called "PRTX", where
"X" is the number of the port. An example of such a package would be::
Package() { "port@4", "PRT4" }
Further on, endpoints are located under the port nodes. The hierarchical
data extension key of the endpoint nodes must begin with
"endpoint" and must be followed by the "@" character and the number of the
endpoint. The object it refers to should be called "EPXY", where "X" is the
number of the port and "Y" is the number of the endpoint. An example of such a
package would be::
Package() { "endpoint@0", "EP40" }
Each port node contains a property extension key "port", the value of which is
the number of the port. Each endpoint is similarly numbered with a property
extension key "reg", the value of which is the number of the endpoint. Port
numbers must be unique within a device and endpoint numbers must be unique
within a port. If a device object may only has a single port, then the number
of that port shall be zero. Similarly, if a port may only have a single
endpoint, the number of that endpoint shall be zero.
The endpoint reference uses property extension with "remote-endpoint" property
name followed by a string reference in the same package. [data-node-ref]::
"device.datanode"
In the above example, "X" is the number of the port and "Y" is the number of
the endpoint.
The references to endpoints must be always done both ways, to the
remote endpoint and back from the referred remote endpoint node.
CAM0의 port 0과 endpoint 0
79-114간단한 ASL 예제의 첫 부분은 scope `\_SB.PCI0.I2C2` 아래에 `CAM0` device를 정의한다. `CAM0._DSD`의 Device Properties UUID `daffd814-6eba-4d8c-8a91-bc9bbf4aa301` package는 `compatible` property에 `"nokia,smia"` 문자열 package를 제공한다.
같은 `CAM0._DSD`의 Hierarchical Data Extension UUID `dbb8e3e6-5886-4ba6-8795-1319f52a966b` package는 `"port@0" → "PRT0"`을 정의한다. 이 device의 port 0 object가 `PRT0`이라는 뜻이다.
`PRT0`은 Device Properties UUID package에서 `reg=0`을 제공하고, Hierarchical Data Extension UUID package에서 `"endpoint@0" → "EP00"`을 제공한다. `EP00`이라는 이름은 port X=0, endpoint Y=0의 `EPXY` 규칙과 일치한다.
`EP00`은 Device Properties UUID package에서 `reg=0`과 `remote-endpoint="\_SB.PCI0.ISP.EP40"`을 제공한다. 따라서 카메라 endpoint는 PCI0 아래 ISP device의 `EP40`을 원격 endpoint로 가리킨다.
ASL의 CAM0 package를 device에서 원격 endpoint까지 펼친 구조다.
CAM0 측 device, port, endpoint object의 property와 참조를 구분한다.
A simple example of this is show below::
Scope (\_SB.PCI0.I2C2)
{
Device (CAM0)
{
Name (_DSD, Package () {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () {
Package () { "compatible", Package () { "nokia,smia" } },
},
ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
Package () {
Package () { "port@0", "PRT0" },
}
})
Name (PRT0, Package() {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () {
Package () { "reg", 0 },
},
ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
Package () {
Package () { "endpoint@0", "EP00" },
}
})
Name (EP00, Package() {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () {
Package () { "reg", 0 },
Package () { "remote-endpoint", "\\_SB.PCI0.ISP.EP40" },
}
})
}
}
ISP의 port 4와 양방향 연결
115-150예제의 두 번째 부분은 scope `\_SB.PCI0` 아래에 `ISP` device를 정의한다. `ISP._DSD`의 Hierarchical Data Extension UUID package는 `"port@4" → "PRT4"`를 제공한다.
`PRT4`는 Device Properties UUID package에서 CSI-2 port number인 `reg=4`를 제공한다. 이어지는 Hierarchical Data Extension UUID package는 `"endpoint@0" → "EP40"`을 정의한다. object 이름 `EP40`은 port X=4와 endpoint Y=0을 결합한 것이다.
`EP40`은 Device Properties UUID package에 `reg=0`과 `remote-endpoint="\_SB.PCI0.I2C2.CAM0.EP00"`을 둔다. 이 값은 CAM0 쪽 endpoint `EP00`으로 되돌아가는 역참조다.
결과적으로 `CAM0` device의 port 0은 `ISP` device의 port 4와 연결되고, 반대 방향 참조도 존재한다. `EP00 → EP40`과 `EP40 → EP00`이 함께 있어 양방향 endpoint 규칙을 만족한다.
ASL의 ISP package를 port 4에서 CAM0 endpoint 역참조까지 펼쳤다.
ISP 측 device, port, endpoint object의 property와 참조다.
두 endpoint의 remote-endpoint가 서로를 가리키는 최종 관계다.
Scope (\_SB.PCI0)
{
Device (ISP)
{
Name (_DSD, Package () {
ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
Package () {
Package () { "port@4", "PRT4" },
}
})
Name (PRT4, Package() {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () {
Package () { "reg", 4 }, /* CSI-2 port number */
},
ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"),
Package () {
Package () { "endpoint@0", "EP40" },
}
})
Name (EP40, Package() {
ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"),
Package () {
Package () { "reg", 0 },
Package () { "remote-endpoint", "\\_SB.PCI0.I2C2.CAM0.EP00" },
}
})
}
}
Here, the port 0 of the "CAM0" device is connected to the port 4 of
the "ISP" device and vice versa.
참고 문서
151-170[acpi]는 Advanced Configuration and Power Interface Specification이며 원문은 ACPI 6.4 URL `https://uefi.org/specifications/ACPI/6.4/`을 가리킨다. 문서에 기록된 참조일은 2021-11-30이다.
[data-node-ref]는 같은 커널 문서 트리의 `Documentation/firmware-guide/acpi/dsd/data-node-references.rst`다. 일반 hierarchical data node 문자열 참조 규칙은 이 문서를 따른다.
[devicetree]는 `https://www.devicetree.org`이며 참조일은 2016-10-03이다. [dsd-guide]는 `https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc`의 DSD Guide이고 참조일은 2021-11-30이다.
[dsd-rules]는 `Documentation/firmware-guide/acpi/DSD-properties-rules.rst`의 `_DSD Device Properties Usage Rules`다. [graph-bindings]는 Devicetree의 common device graph binding인 `https://github.com/devicetree-org/dt-schema/blob/main/schemas/graph.yaml`이며 참조일은 2021-11-30이다.
원문 reference label, 문서와 기록된 참조일을 보존했다.
References
==========
[acpi] Advanced Configuration and Power Interface Specification.
https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30.
[data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst
[devicetree] Devicetree. https://www.devicetree.org, referenced 2016-10-03.
[dsd-guide] DSD Guide.
https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced
2021-11-30.
[dsd-rules] _DSD Device Properties Usage Rules.
Documentation/firmware-guide/acpi/DSD-properties-rules.rst
[graph-bindings] Common bindings for device graphs (Devicetree).
https://github.com/devicetree-org/dt-schema/blob/main/schemas/graph.yaml,
referenced 2021-11-30.
요약·해설
graph.rst:1-170ACPI `_DSD` graph는 property extension과 hierarchical data extension을 결합해 device 아래에 port와 endpoint node를 만든다. Linux에서는 이 계층을 firmware type과 독립적인 `fwnode` API로 탐색한다.
Port X는 `port@X → PRTX`, port X 아래 endpoint Y는 `endpoint@Y → EPXY` 규칙을 사용한다. Port number는 device 안에서, endpoint number는 port 안에서 고유해야 하며 단일 항목이면 0을 사용한다.
연결은 `remote-endpoint` 문자열 참조를 양쪽 endpoint에 모두 기록해야 한다. 예제는 CAM0의 `EP00`과 ISP의 `EP40`이 서로를 참조해 CAM0 port 0과 ISP port 4를 연결한다.
노드 명명부터 양방향 연결까지 확인하는 핵심 절차다.