요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GPL-2.0-or-later
3
==================
4
ACPI WMI interface
5
==================
7
The ACPI WMI interface is a proprietary extension of the ACPI specification made
8
by Microsoft to allow hardware vendors to embed WMI (Windows Management Instrumentation)
9
objects inside their ACPI firmware. Typical functions implemented over ACPI WMI
10
are hotkey events on modern notebooks and configuration of BIOS options.
12
PNP0C14 ACPI device
13
-------------------
15
Discovery of WMI objects is handled by defining ACPI devices with a PNP ID
16
of ``PNP0C14``. These devices will contain a set of ACPI buffers and methods
17
used for mapping and execution of WMI methods and/or queries. If there exist
18
multiple of such devices, then each device is required to have a
19
unique ACPI UID.
21
_WDG buffer
22
-----------
24
The ``_WDG`` buffer is used to discover WMI objects and is required to be
25
static. Its internal structure consists of data blocks with a size of 20 bytes,
26
containing the following data:
28
======= =============== =====================================================
29
Offset Size (in bytes) Content
30
======= =============== =====================================================
31
0x00 16 128 bit Variant 2 object GUID.
32
0x10 2 2 character method ID or single byte notification ID.
33
0x12 1 Object instance count.
34
0x13 1 Object flags.
35
======= =============== =====================================================
37
The WMI object flags control whether the method or notification ID is used:
39
- 0x1: Data block is expensive to collect.
40
- 0x2: Data block contains WMI methods.
41
- 0x4: Data block contains ASCIZ string.
42
- 0x8: Data block describes a WMI event, use notification ID instead
43
of method ID.
45
Each WMI object GUID can appear multiple times inside a system.
46
The method/notification ID is used to construct the ACPI method names used for
47
interacting with the WMI object.
49
WQxx ACPI methods
50
-----------------
52
If a data block does not contain WMI methods, then its content can be retrieved
53
by this required ACPI method. The last two characters of the ACPI method name
54
are the method ID of the data block to query. Their single parameter is an
55
integer describing the instance which should be queried. This parameter can be
56
omitted if the data block contains only a single instance.
58
WSxx ACPI methods
59
-----------------
61
Similar to the ``WQxx`` ACPI methods, except that it is optional and takes an
62
additional buffer as its second argument. The instance argument also cannot
63
be omitted.
65
WMxx ACPI methods
66
-----------------
68
Used for executing WMI methods associated with a data block. The last two
69
characters of the ACPI method name are the method ID of the data block
70
containing the WMI methods. Their first parameter is a integer describing the
71
instance which methods should be executed. The second parameter is an integer
72
describing the WMI method ID to execute, and the third parameter is a buffer
73
containing the WMI method parameters. If the data block is marked as containing
74
an ASCIZ string, then this buffer should contain an ASCIZ string. The ACPI
75
method will return the result of the executed WMI method.
77
WExx ACPI methods
78
-----------------
80
Used for optionally enabling/disabling WMI events, the last two characters of
81
the ACPI method are the notification ID of the data block describing the WMI
82
event as hexadecimal value. Their first parameter is an integer with a value
83
of 0 if the WMI event should be disabled, other values will enable
84
the WMI event.
86
Those ACPI methods are always called even for WMI events not registered as
87
being expensive to collect to match the behavior of the Windows driver.
89
WCxx ACPI methods
90
-----------------
91
Similar to the ``WExx`` ACPI methods, except that instead of WMI events it controls
92
data collection of data blocks registered as being expensive to collect. Thus the
93
last two characters of the ACPI method name are the method ID of the data block
94
to enable/disable.
96
Those ACPI methods are also called before setting data blocks to match the
97
behavior of the Windows driver.
99
_WED ACPI method
100
----------------
102
Used to retrieve additional WMI event data, its single parameter is a integer
103
holding the notification ID of the event. This method should be evaluated every
104
time an ACPI notification is received, since some ACPI implementations use a
105
queue to store WMI event data items. This queue will overflow after a couple
106
of WMI events are received without retrieving the associated WMI event data.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
ACPI WMI 개요
1-11ACPI WMI 인터페이스는 Microsoft가 만든 ACPI 사유 확장입니다. 하드웨어 공급업체는 이를 사용해 WMI(Windows Management Instrumentation) 객체를 ACPI firmware 안에 넣을 수 있습니다.
현대형 notebook의 hotkey 이벤트와 BIOS 옵션 설정이 ACPI WMI로 구현되는 대표 기능입니다.
.. SPDX-License-Identifier: GPL-2.0-or-later
==================
ACPI WMI interface
==================
The ACPI WMI interface is a proprietary extension of the ACPI specification made
by Microsoft to allow hardware vendors to embed WMI (Windows Management Instrumentation)
objects inside their ACPI firmware. Typical functions implemented over ACPI WMI
are hotkey events on modern notebooks and configuration of BIOS options.
PNP0C14 ACPI 장치
12-20WMI 객체는 PNP ID가 `PNP0C14`인 ACPI 장치를 정의해 탐색합니다. 이 장치는 WMI method 호출과 query의 mapping 및 실행에 쓰이는 ACPI buffer와 method 집합을 포함합니다.
한 시스템에 `PNP0C14` 장치가 여러 개 있으면 각 장치는 고유한 ACPI UID를 가져야 합니다.
PNP0C14 ACPI device
-------------------
Discovery of WMI objects is handled by defining ACPI devices with a PNP ID
of ``PNP0C14``. These devices will contain a set of ACPI buffers and methods
used for mapping and execution of WMI methods and/or queries. If there exist
multiple of such devices, then each device is required to have a
unique ACPI UID.
_WDG 탐색 buffer
21-47정적 `_WDG` buffer는 WMI 객체를 탐색하는 데 사용됩니다. 내부는 20바이트 data block의 연속이며, 각 block은 GUID, method 또는 notification ID, instance 수, flag를 담습니다.
Offset크기내용
0x0016바이트128비트 Variant 2 객체 GUID
0x102바이트2문자 method ID 또는 1바이트 notification ID
0x121바이트객체 instance 수
0x131바이트객체 flag
20바이트 WMI 객체 설명자의 byte layout입니다.
객체 flag `0x1`은 수집 비용이 큰 data block, `0x2`는 WMI method 포함, `0x4`는 ASCIZ 문자열 포함, `0x8`은 method ID 대신 notification ID를 사용하는 WMI event 설명을 뜻합니다.
같은 WMI 객체 GUID가 한 시스템에 여러 번 나타날 수 있습니다. method 또는 notification ID는 해당 WMI 객체와 상호작용할 ACPI method 이름을 만드는 데 사용됩니다.
Flag의미
0x1수집 비용이 큰 data block
0x2WMI method를 포함하는 data block
0x4ASCIZ 문자열을 포함하는 data block
0x8WMI event이며 method ID 대신 notification ID 사용
_WDG 객체의 성격과 ID 해석 방식을 정하는 bit입니다.
_WDG buffer
-----------
The ``_WDG`` buffer is used to discover WMI objects and is required to be
static. Its internal structure consists of data blocks with a size of 20 bytes,
containing the following data:
======= =============== =====================================================
Offset Size (in bytes) Content
======= =============== =====================================================
0x00 16 128 bit Variant 2 object GUID.
0x10 2 2 character method ID or single byte notification ID.
0x12 1 Object instance count.
0x13 1 Object flags.
======= =============== =====================================================
The WMI object flags control whether the method or notification ID is used:
- 0x1: Data block is expensive to collect.
- 0x2: Data block contains WMI methods.
- 0x4: Data block contains ASCIZ string.
- 0x8: Data block describes a WMI event, use notification ID instead
of method ID.
Each WMI object GUID can appear multiple times inside a system.
The method/notification ID is used to construct the ACPI method names used for
interacting with the WMI object.WQxx query method
48-57WMI method를 포함하지 않는 data block의 내용은 필수 ACPI method인 `WQxx`로 가져옵니다. 이름의 마지막 두 문자는 query할 data block의 method ID입니다.
단일 parameter는 query할 instance를 나타내는 정수입니다. data block에 instance가 하나뿐이면 이 parameter를 생략할 수 있습니다.
WQxx ACPI methods
-----------------
If a data block does not contain WMI methods, then its content can be retrieved
by this required ACPI method. The last two characters of the ACPI method name
are the method ID of the data block to query. Their single parameter is an
integer describing the instance which should be queried. This parameter can be
omitted if the data block contains only a single instance.
WSxx 설정 method
58-64선택 사항인 `WSxx`는 `WQxx`와 비슷하지만 두 번째 인수로 추가 buffer를 받습니다. 이 호출에서는 instance 인수를 생략할 수 없습니다.
WSxx ACPI methods
-----------------
Similar to the ``WQxx`` ACPI methods, except that it is optional and takes an
additional buffer as its second argument. The instance argument also cannot
be omitted.
WMxx 실행 method
65-76`WMxx`는 data block과 연결된 WMI method를 실행합니다. ACPI method 이름의 마지막 두 문자는 WMI method를 포함하는 data block의 method ID입니다.
첫 번째 parameter는 method를 실행할 instance, 두 번째는 실행할 WMI method ID, 세 번째는 WMI method parameter가 든 buffer입니다. data block에 ASCIZ 문자열 flag가 있으면 이 buffer도 ASCIZ 문자열을 담아야 합니다. ACPI method는 실행 결과를 반환합니다.
WMxx ACPI methods
-----------------
Used for executing WMI methods associated with a data block. The last two
characters of the ACPI method name are the method ID of the data block
containing the WMI methods. Their first parameter is a integer describing the
instance which methods should be executed. The second parameter is an integer
describing the WMI method ID to execute, and the third parameter is a buffer
containing the WMI method parameters. If the data block is marked as containing
an ASCIZ string, then this buffer should contain an ASCIZ string. The ACPI
method will return the result of the executed WMI method.
WExx event 제어 method
77-88선택 사항인 `WExx`는 WMI event를 활성화하거나 비활성화합니다. 이름의 마지막 두 문자는 event data block의 notification ID를 16진수로 표현한 값입니다.
첫 번째 정수 parameter가 0이면 event를 비활성화하고, 0이 아닌 값이면 활성화합니다. Windows driver 동작과 맞추기 위해 수집 비용이 크다고 등록되지 않은 WMI event에도 이 ACPI method를 항상 호출합니다.
WExx ACPI methods
-----------------
Used for optionally enabling/disabling WMI events, the last two characters of
the ACPI method are the notification ID of the data block describing the WMI
event as hexadecimal value. Their first parameter is an integer with a value
of 0 if the WMI event should be disabled, other values will enable
the WMI event.
Those ACPI methods are always called even for WMI events not registered as
being expensive to collect to match the behavior of the Windows driver.
WCxx data 수집 제어 method
89-98`WCxx`는 `WExx`와 비슷하지만 WMI event 대신 수집 비용이 크다고 등록된 data block의 수집을 제어합니다. 이름의 마지막 두 문자는 활성화하거나 비활성화할 data block의 method ID입니다.
Windows driver 동작과 맞추기 위해 data block을 설정하기 전에도 이 ACPI method를 호출합니다.
WCxx ACPI methods
-----------------
Similar to the ``WExx`` ACPI methods, except that instead of WMI events it controls
data collection of data blocks registered as being expensive to collect. Thus the
last two characters of the ACPI method name are the method ID of the data block
to enable/disable.
Those ACPI methods are also called before setting data blocks to match the
behavior of the Windows driver.
_WED event data method
99-106`_WED`는 WMI event의 추가 data를 가져옵니다. 단일 정수 parameter에는 event notification ID가 들어갑니다.
일부 ACPI 구현은 WMI event data를 queue에 저장하므로 ACPI notification을 받을 때마다 `_WED`를 평가해야 합니다. 연결된 event data를 몇 차례 가져오지 않으면 이 queue가 넘칠 수 있습니다.
Method역할핵심 인수
WQxxdata block queryinstance; 단일 instance이면 생략 가능
WSxxdata block 설정instance, buffer
WMxxWMI method 실행instance, method ID, parameter buffer
WExxWMI event 활성화 또는 비활성화0은 비활성화, 그 밖의 값은 활성화
WCxx고비용 data block 수집 제어method ID와 enable 값
_WED추가 event data 조회notification ID
WMI data와 event를 다루는 ACPI method 이름과 역할입니다.
_WED ACPI method
----------------
Used to retrieve additional WMI event data, its single parameter is a integer
holding the notification ID of the event. This method should be evaluated every
time an ACPI notification is received, since some ACPI implementations use a
queue to store WMI event data items. This queue will overflow after a couple
of WMI events are received without retrieving the associated WMI event data.
요약·해설
acpi-interface.rst:1-106PNP0C14 장치, _WDG 객체 layout과 WQxx·WSxx·WMxx·WExx·WCxx·_WED 호출 규약을 설명합니다.