Chrome OS ACPI Device

Chrome OS ACPI 장치와 지원 객체

Chrome OS에 특화된 하드웨어 기능은 하나의 Chrome OS ACPI 장치를 통해 노출된다. 이 장치의 플러그 앤 플레이 ID는 `GGL0001`이고 하드웨어 ID는 `GOOG0016`이다. 운영체제는 이 식별자를 사용해 장치를 찾은 뒤, 아래의 ACPI 제어 메서드를 개별 기능 인터페이스로 호출한다.

지원 객체 표는 스위치 상태, 기기·펌웨어 식별 정보, 현재 부팅 정보, GPIO 배선, 검증 부팅용 NVRAM과 데이터, 플래시맵 주소, 지원 메서드 목록을 구분한다. 표에는 `MECK`가 없지만 문서 후반에는 Management Engine 해시를 반환하는 별도 메서드로 정의되어 있으므로 구현은 `MLST` 결과까지 확인해야 한다.

.. SPDX-License-Identifier: GPL-2.0

=====================
Chrome OS ACPI Device
=====================

Hardware functionality specific to Chrome OS is exposed through a Chrome OS ACPI device.
The plug and play ID of a Chrome OS ACPI device is GGL0001 and the hardware ID is
GOOG0016.  The following ACPI objects are supported:

.. flat-table:: Supported ACPI Objects
   :widths: 1 2
   :header-rows: 1

   * - Object
     - Description

   * - CHSW
     - Chrome OS switch positions

   * - HWID
     - Chrome OS hardware ID

   * - FWID
     - Chrome OS firmware version

   * - FRID
     - Chrome OS read-only firmware version

   * - BINF
     - Chrome OS boot information

   * - GPIO
     - Chrome OS GPIO assignments

   * - VBNV
     - Chrome OS NVRAM locations

   * - VDTA
     - Chrome OS verified boot data

   * - FMAP
     - Chrome OS flashmap base address

   * - MLST
     - Chrome OS method list

CHSW 스위치 상태와 HWID

`CHSW` 제어 메서드는 Chrome OS 전용 하드웨어 스위치가 부팅 시점에 어떤 위치였는지를 반환한다. 인수는 없으며, 결과는 각 상태를 비트로 표현한 정수다. 이 값은 현재의 물리 상태가 아니라 x86 펌웨어 또는 EC 펌웨어가 부팅될 때 관찰한 상태라는 점이 중요하다.

비트 `0x00000002`는 x86 펌웨어 부팅 때 복구 버튼이 눌렸음을 뜻한다. `0x00000004`는 EC 펌웨어 부팅 때 복구 버튼이 눌렸음을 뜻하며, EC EEPROM을 다시 쓸 수 있는 시스템에서는 필수이고 그렇지 않으면 선택 사항이다.

비트 `0x00000020`은 x86 펌웨어 부팅 때 개발자 스위치가 활성화되었음을 뜻한다. `0x00000200`은 같은 시점에 펌웨어 쓰기 보호가 비활성화되었음을 뜻하며, x86 BIOS가 쓰기 보호를 제어하는 경우 필수이고 그 밖에는 선택 사항이다. 정의되지 않은 모든 비트는 예약되어 있으므로 0이어야 한다.

`HWID` 제어 메서드도 인수를 받지 않는다. 이 메서드는 EEPROM의 Model-Specific Data 영역에 저장된 Chromebook 하드웨어 ID를 널 종료 ASCII 문자열로 반환한다. 종료 널 문자를 포함한 최대 길이는 256자이므로, 호출자는 최대 길이와 종료 문자를 함께 검증해야 한다.

CHSW (Chrome OS switch positions)
=================================
This control method returns the switch positions for Chrome OS specific hardware switches.

Arguments:
----------
None

Result code:
------------
An integer containing the switch positions as bitfields:

.. flat-table::
   :widths: 1 2

   * - 0x00000002
     - Recovery button was pressed when x86 firmware booted.

   * - 0x00000004
     - Recovery button was pressed when EC firmware booted. (required if EC EEPROM is
       rewritable; otherwise optional)

   * - 0x00000020
     - Developer switch was enabled when x86 firmware booted.

   * - 0x00000200
     - Firmware write protection was disabled when x86 firmware booted. (required if
       firmware write protection is controlled through x86 BIOS; otherwise optional)

All other bits are reserved and should be set to 0.

HWID (Chrome OS hardware ID)
============================
This control method returns the hardware ID for the Chromebook.

Arguments:
----------
None

Result code:
------------
A null-terminated ASCII string containing the hardware ID from the Model-Specific Data area of
EEPROM.

Note that the hardware ID can be up to 256 characters long, including the terminating null.

FWID와 FRID 펌웨어 버전

`FWID` 제어 메서드는 메인 프로세서 펌웨어의 재기록 가능한 부분에 대한 완전한 펌웨어 버전을 반환한다. 인수는 없고 결과는 널 종료 ASCII 문자열이다. 업데이트 가능한 주 펌웨어 버전을 식별할 때 이 값을 사용한다.

`FRID` 제어 메서드는 메인 프로세서 펌웨어의 읽기 전용 부분에 대한 완전한 버전을 반환한다. 이 읽기 전용 부분은 부트스트랩과 복구 펌웨어를 포함한다. `FRID` 역시 인수가 없고 널 종료 ASCII 문자열을 반환한다.

두 값은 모두 메인 프로세서 펌웨어를 설명하지만 대상 영역이 다르다. 펌웨어 상태를 보고할 때 `FWID`와 `FRID`를 서로 대체해서는 안 되며, 재기록 가능 영역과 복구 가능한 신뢰 기반을 각각 별도 필드로 유지해야 한다.

FWID (Chrome OS firmware version)
=================================
This control method returns the firmware version for the rewritable portion of the main
processor firmware.

Arguments:
----------
None

Result code:
------------
A null-terminated ASCII string containing the complete firmware version for the rewritable
portion of the main processor firmware.

FRID (Chrome OS read-only firmware version)
===========================================
This control method returns the firmware version for the read-only portion of the main
processor firmware.

Arguments:
----------
None

Result code:
------------
A null-terminated ASCII string containing the complete firmware version for the read-only
(bootstrap + recovery ) portion of the main processor firmware.

BINF 현재 부팅 정보

`BINF` 제어 메서드는 현재 부팅에 관한 정보를 반환하며 인수는 없다. 결과 패키지는 `Reserved1`, `Reserved2`, `Active EC Firmware`, `Active Main Firmware Type`, `Reserved5`의 다섯 필드로 구성되고, 각 필드의 형식은 `DWORD`다.

`Reserved1`, `Reserved2`, `Reserved5`는 더 이상 사용되지 않는 필드임을 나타내기 위해 모두 256(`0x100`)으로 설정한다. 이름이 예약 필드라고 해서 0으로 채우는 것이 아니라 명시된 호환성 값 `0x100`을 써야 한다.

`Active EC Firmware`는 부팅에 사용된 EC 펌웨어를 나타낸다. 값 0은 읽기 전용 복구 펌웨어, 값 1은 재기록 가능 펌웨어다. EC 펌웨어가 항상 읽기 전용인 시스템에서는 0으로 설정한다.

`Active Main Firmware Type`은 부팅에 사용된 메인 펌웨어 유형이다. 값 0은 Recovery, 1은 Normal, 2는 Developer, 3은 공장 설치 전용 netboot를 뜻하며, 다른 값은 예약되어 있다.

BINF (Chrome OS boot information)
=================================
This control method returns information about the current boot.

Arguments:
----------
None

Result code:
------------

.. code-block::

   Package {
           Reserved1
           Reserved2
           Active EC Firmware
           Active Main Firmware Type
           Reserved5
   }

.. flat-table::
   :widths: 1 1 2
   :header-rows: 1

   * - Field
     - Format
     - Description

   * - Reserved1
     - DWORD
     - Set to 256 (0x100). This indicates this field is no longer used.

   * - Reserved2
     - DWORD
     - Set to 256 (0x100). This indicates this field is no longer used.

   * - Active EC firmware
     - DWORD
     - The EC firmware which was used during boot.

       - 0 - Read-only (recovery) firmware
       - 1 - Rewritable firmware.

       Set to 0 if EC firmware is always read-only.

   * - Active Main Firmware Type
     - DWORD
     - The main firmware type which was used during boot.

       - 0 - Recovery
       - 1 - Normal
       - 2 - Developer
       - 3 - netboot (factory installation only)

       Other values are reserved.

   * - Reserved5
     - DWORD
     - Set to 256 (0x100). This indicates this field is no longer used.

GPIO 할당 패키지

`GPIO` 제어 메서드는 Chrome OS 하드웨어에 특화된 GPIO 할당 정보를 반환한다. 이 정보를 통해 커널이 해당 하드웨어를 직접 제어할 수 있다. 인수는 없고, 결과는 GPIO 할당마다 하나의 내부 `Package`를 갖는 외부 `Package`다.

각 내부 패키지는 순서대로 `Signal Type`, `Attributes`, `Controller Offset`, `Controller Name`을 담는다. 앞의 세 값은 `DWORD`이고 컨트롤러 이름은 `ASCIIZ`, 즉 널 종료 ASCII 문자열이다. 반복되는 내부 패키지의 순서와 각 필드의 순서를 모두 보존해야 한다.

`Signal Type` 값 `0x00000001`은 복구 버튼, `0x00000002`는 개발자 모드 스위치, `0x00000003`은 펌웨어 쓰기 보호 스위치다. `0x00000100`부터 `0x000001FF`까지는 디버그 헤더 GPIO 0부터 255까지에 대응한다. 그 밖의 값은 예약되어 있다.

`Attributes`는 비트 필드다. 비트 `0x00000001`이 1이면 신호는 active-high이며, 버튼에서는 GPIO 값 1이 눌림을, 스위치에서는 값 1이 활성화를 뜻한다. 이 비트가 0이면 신호는 active-low다. 디버그 헤더 GPIO에서는 `Attributes`를 0으로 설정한다.

`Controller Offset`은 지정된 컨트롤러 안에서의 GPIO 번호다. `Controller Name`은 그 GPIO를 제공하는 컨트롤러의 이름이며, 현재 지원되는 이름은 Intel NM10 칩을 나타내는 문자열 `"NM10"`이다.

GPIO (Chrome OS GPIO assignments)
=================================
This control method returns information about Chrome OS specific GPIO assignments for
Chrome OS hardware, so the kernel can directly control that hardware.

Arguments:
----------
None

Result code:
------------
.. code-block::

        Package {
                Package {
                        // First GPIO assignment
                        Signal Type        //DWORD
                        Attributes         //DWORD
                        Controller Offset  //DWORD
                        Controller Name    //ASCIIZ
                },
                ...
                Package {
                        // Last GPIO assignment
                        Signal Type        //DWORD
                        Attributes         //DWORD
                        Controller Offset  //DWORD
                        Controller Name    //ASCIIZ
                }
        }

Where ASCIIZ means a null-terminated ASCII string.

.. flat-table::
   :widths: 1 1 2
   :header-rows: 1

   * - Field
     - Format
     - Description

   * - Signal Type
     - DWORD
     - Type of GPIO signal

       - 0x00000001 - Recovery button
       - 0x00000002 - Developer mode switch
       - 0x00000003 - Firmware write protection switch
       - 0x00000100 - Debug header GPIO 0
       - ...
       - 0x000001FF - Debug header GPIO 255

       Other values are reserved.

   * - Attributes
     - DWORD
     - Signal attributes as bitfields:

       - 0x00000001 - Signal is active-high (for button, a GPIO value
         of 1 means the button is pressed; for switches, a GPIO value
         of 1 means the switch is enabled). If this bit is 0, the signal
         is active low. Set to 0 for debug header GPIOs.

   * - Controller Offset
     - DWORD
     - GPIO number on the specified controller.

   * - Controller Name
     - ASCIIZ
     - Name of the controller for the GPIO.
       Currently supported names:
       "NM10" - Intel NM10 chip

VBNV NVRAM 위치와 FMAP 주소

`VBNV` 제어 메서드는 BIOS와 통신하는 데 쓰이는 NVRAM(CMOS) 위치 정보를 반환한다. 인수는 없으며 결과 패키지는 `NV Storage Block Offset`과 `NV Storage Block Size`라는 두 `DWORD` 필드를 순서대로 담는다.

`NV Storage Block Offset`은 검증 부팅 비휘발성 저장 블록이 CMOS bank 0의 어디에서 시작하는지를 나타낸다. 기준점은 CMOS의 첫 번째 쓰기 가능 바이트이므로, offset 0은 14바이트짜리 시계 데이터 바로 다음 바이트를 뜻한다. CMOS bank 0의 절대 시작점과 혼동해서는 안 된다.

`NV Storage Block Size`는 검증 부팅 비휘발성 저장 블록의 크기를 바이트 단위로 나타낸다. 오프셋과 크기를 함께 사용해야 블록의 정확한 범위를 계산할 수 있다.

`FMAP` 제어 메서드는 메인 프로세서 펌웨어 플래시맵이 시작되는 물리 메모리 주소를 반환한다. 인수는 없고 결과는 그 시작 주소를 담은 `DWORD`다. 원문에는 제목이 `NoneResult code:`로 붙어 있지만 의미상 인수 없음 다음의 결과 코드 절이며, 원문 자체는 아래 접이식 영역에 그대로 보존한다.

VBNV (Chrome OS NVRAM locations)
================================
This control method returns information about the NVRAM (CMOS) locations used to
communicate with the BIOS.

Arguments:
----------
None

Result code:
------------
.. code-block::

        Package {
                NV Storage Block Offset  //DWORD
                NV Storage Block Size    //DWORD
        }

.. flat-table::
   :widths: 1 1 2
   :header-rows: 1

   * - Field
     - Format
     - Description

   * - NV Storage Block Offset
     - DWORD
     - Offset in CMOS bank 0 of the verified boot non-volatile storage block, counting from
       the first writable CMOS byte (that is, offset=0 is the byte following the 14 bytes of
       clock data).

   * - NV Storage Block Size
     - DWORD
     - Size in bytes of the verified boot non-volatile storage block.

FMAP (Chrome OS flashmap address)
=================================
This control method returns the physical memory address of the start of the main processor
firmware flashmap.

Arguments:
----------
None

NoneResult code:
----------------
A DWORD containing the physical memory address of the start of the main processor firmware
flashmap.

VDTA 검증 부팅 데이터와 MECK

`VDTA` 제어 메서드는 펌웨어 검증 단계와 커널 검증 단계가 공유하는 검증 부팅 데이터 블록을 반환한다. 인수는 없고 결과는 해당 블록을 담은 버퍼다. 이 인터페이스는 주소이나 크기 필드가 아니라 데이터 자체를 버퍼로 전달한다.

`MECK` 제어 메서드는 부팅 중 Management Engine 확장 레지스터에서 읽은 SHA-1 또는 SHA-256 해시를 반환한다. ACPI를 통해 이 해시를 운영체제에 제공하면 운영체제가 ME 펌웨어가 변경되지 않았는지 검증할 수 있다.

Management Engine이 없거나 펌웨어가 확장 레지스터를 읽지 못했다면 `MECK` 버퍼는 0일 수 있다. 따라서 0 버퍼를 유효한 ME 펌웨어 해시로 간주해서는 안 되며, 부재 또는 읽기 실패 가능성을 별도 상태로 처리해야 한다.

VDTA (Chrome OS verified boot data)
===================================
This control method returns the verified boot data block shared between the firmware
verification step and the kernel verification step.

Arguments:
----------
None

Result code:
------------
A buffer containing the verified boot data block.

MECK (Management Engine Checksum)
=================================
This control method returns the SHA-1 or SHA-256 hash that is read out of the Management
Engine extended registers during boot. The hash is exported via ACPI so the OS can verify that
the ME firmware has not changed. If Management Engine is not present, or if the firmware was
unable to read the extended registers, this buffer can be zero.

Arguments:
----------
None

Result code:
------------
A buffer containing the ME hash.

MLST 지원 메서드 목록

`MLST` 제어 메서드는 Chrome OS 하드웨어 장치가 지원하는 다른 제어 메서드의 목록을 반환한다. 인수는 없으며, 결과는 지원되는 메서드마다 하나씩 들어 있는 널 종료 ASCII 문자열의 패키지다.

목록에는 `MLST` 메서드 자체를 포함하지 않는다. 이 규격 버전에서 결과는 `CHSW`, `FWID`, `HWID`, `FRID`, `BINF`, `GPIO`, `VBNV`, `FMAP`, `VDTA`, `MECK`의 열 개 문자열이다. 호출자는 고정 개수만 가정하기보다 실제 패키지 항목을 순회하는 편이 이후 규격 확장에 안전하다.

MLST (Chrome OS method list)
============================
This control method returns a list of the other control methods supported by the Chrome OS
hardware device.

Arguments:
----------
None

Result code:
------------
A package containing a list of null-terminated ASCII strings, one for each control method
supported by the Chrome OS hardware device, not including the MLST method itself.
For this version of the specification, the result is:

.. code-block::

        Package {
                "CHSW",
                "FWID",
                "HWID",
                "FRID",
                "BINF",
                "GPIO",
                "VBNV",
                "FMAP",
                "VDTA",
                "MECK"
        }