Dell AWCC WMI interface driver (alienware-wmi)

WMAX의 두 구현과 문서 범위

WMI 장치 `WMAX`는 여러 Alienware 및 Dell G-Series 모델에 구현되어 있으며 두 종류의 구현이 확인되었습니다. 구형 구현은 HDMI, 밝기, RGB, amplifier, deep sleep 제어를 담당하고, 신형 구현은 주로 thermal 제어와 overclocking을 담당합니다.

신형 구현은 Alienware Command Center(AWCC)가 제조사가 미리 정의한 thermal profile을 관리하는 데 사용하는 것으로 추정됩니다. `alienware-wmi` 드라이버는 AWCC 동작을 모방하기 위해 `Thermal_Information`과 `Thermal_Control`을 Platform Profile API로 노출합니다.

신형 `AWCCMethodFunction` interface에는 Dell의 공식 문서가 없어 reverse engineering으로 동작을 파악했습니다. 따라서 아래 설명은 불완전할 수 있고 같은 operation도 장치마다 구현이 다를 수 있습니다.

.. SPDX-License-Identifier: GPL-2.0-or-later

==============================================
Dell AWCC WMI interface driver (alienware-wmi)
==============================================

Introduction
============

The WMI device WMAX has been implemented for many Alienware and Dell's G-Series
models. Throughout these models, two implementations have been identified. The
first one, used by older systems, deals with HDMI, brightness, RGB, amplifier
and deep sleep control. The second one used by newer systems deals primarily
with thermal control and overclocking.

It is suspected that the latter is used by Alienware Command Center (AWCC) to
manage manufacturer predefined thermal profiles. The alienware-wmi driver
exposes Thermal_Information and Thermal_Control methods through the Platform
Profile API to mimic AWCC's behavior.

This newer interface, named AWCCMethodFunction has been reverse engineered, as
Dell has not provided any official documentation. We will try to describe to the
best of our ability its discovered inner workings.

.. note::
   The following method description may be incomplete and some operations have
   different implementations between devices.

embedded binary MOF의 method 선언

embedded binary MOF(bmof)는 `bmfdec` 도구로 해석할 수 있습니다. GUID `{A70591CE-A997-11DA-B012-B622A1EF5492}`의 `AWCCWmiMethodFunction` class에는 읽기 가능한 `InstanceName`, `Active` 속성과 아래 28개 WMI method가 선언되어 있습니다.

이후 문서에서 별도로 설명하지 않는 method의 동작은 알려져 있지 않습니다.

WMI interface description
-------------------------

The WMI interface description can be decoded from the embedded binary MOF (bmof)
data using the `bmfdec <https://github.com/pali/bmfdec>`_ utility:

::

 [WMI, Dynamic, Provider("WmiProv"), Locale("MS\\0x409"), Description("WMI Function"), guid("{A70591CE-A997-11DA-B012-B622A1EF5492}")]
 class AWCCWmiMethodFunction {
   [key, read] string InstanceName;
   [read] boolean Active;

   [WmiMethodId(13), Implemented, read, write, Description("Return Overclocking Report.")] void Return_OverclockingReport([out] uint32 argr);
   [WmiMethodId(14), Implemented, read, write, Description("Set OCUIBIOS Control.")] void Set_OCUIBIOSControl([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(15), Implemented, read, write, Description("Clear OC FailSafe Flag.")] void Clear_OCFailSafeFlag([out] uint32 argr);
   [WmiMethodId(19), Implemented, read, write, Description("Get Fan Sensors.")] void GetFanSensors([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(20), Implemented, read, write, Description("Thermal Information.")] void Thermal_Information([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(21), Implemented, read, write, Description("Thermal Control.")] void Thermal_Control([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(23), Implemented, read, write, Description("MemoryOCControl.")] void MemoryOCControl([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(26), Implemented, read, write, Description("System Information.")] void SystemInformation([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(28), Implemented, read, write, Description("Power Information.")] void PowerInformation([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(32), Implemented, read, write, Description("FW Update GPIO toggle.")] void FWUpdateGPIOtoggle([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(33), Implemented, read, write, Description("Read Total of GPIOs.")] void ReadTotalofGPIOs([out] uint32 argr);
   [WmiMethodId(34), Implemented, read, write, Description("Read GPIO pin Status.")] void ReadGPIOpPinStatus([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(35), Implemented, read, write, Description("Read Chassis Color.")] void ReadChassisColor([out] uint32 argr);
   [WmiMethodId(36), Implemented, read, write, Description("Read Platform Properties.")] void ReadPlatformProperties([out] uint32 argr);
   [WmiMethodId(37), Implemented, read, write, Description("Game Shift Status.")] void GameShiftStatus([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(128), Implemented, read, write, Description("Caldera SW installation.")] void CalderaSWInstallation([out] uint32 argr);
   [WmiMethodId(129), Implemented, read, write, Description("Caldera SW is released.")] void CalderaSWReleased([out] uint32 argr);
   [WmiMethodId(130), Implemented, read, write, Description("Caldera Connection Status.")] void CalderaConnectionStatus([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(131), Implemented, read, write, Description("Surprise Unplugged Flag Status.")] void SurpriseUnpluggedFlagStatus([out] uint32 argr);
   [WmiMethodId(132), Implemented, read, write, Description("Clear Surprise Unplugged Flag.")] void ClearSurpriseUnpluggedFlag([out] uint32 argr);
   [WmiMethodId(133), Implemented, read, write, Description("Cancel Undock Request.")] void CancelUndockRequest([out] uint32 argr);
   [WmiMethodId(135), Implemented, read, write, Description("Devices in Caldera.")] void DevicesInCaldera([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(136), Implemented, read, write, Description("Notify BIOS for SW ready to disconnect Caldera.")] void NotifyBIOSForSWReadyToDisconnectCaldera([out] uint32 argr);
   [WmiMethodId(160), Implemented, read, write, Description("Tobii SW installation.")] void TobiiSWinstallation([out] uint32 argr);
   [WmiMethodId(161), Implemented, read, write, Description("Tobii SW Released.")] void TobiiSWReleased([out] uint32 argr);
   [WmiMethodId(162), Implemented, read, write, Description("Tobii Camera Power Reset.")] void TobiiCameraPowerReset([out] uint32 argr);
   [WmiMethodId(163), Implemented, read, write, Description("Tobii Camera Power On.")] void TobiiCameraPowerOn([out] uint32 argr);
   [WmiMethodId(164), Implemented, read, write, Description("Tobii Camera Power Off.")] void TobiiCameraPowerOff([out] uint32 argr);
 };

Methods not described in the following document have unknown behavior.

uint32 argument 구조

모든 입력 인수는 `uint32`이며 method 사이의 구조가 매우 비슷합니다. 일반적으로 첫 번째 byte는 method가 수행할 `operation`, 이어지는 byte들은 그 operation에 전달하는 인수입니다.

예를 들어 operation code가 `0x01`이고 ID `0xA0`이 필요하면 method에 전달할 값은 `0xA001`입니다. 즉 낮은 byte에 operation, 그 다음 byte에 ID가 배치됩니다.

Argument Structure
------------------

All input arguments have type **uint32** and their structure is very similar
between methods. Usually, the first byte corresponds to a specific *operation*
the method performs, and the subsequent bytes correspond to *arguments* passed
to this *operation*. For example, if an operation has code 0x01 and requires an
ID 0xA0, the argument you would pass to the method is 0xA001.

GetFanSensors

`GetFanSensors`의 operation `0x01`은 지정한 fan ID와 관련된 temperature sensor 수를 조회하고, `0x02`는 fan sensor ID와 index를 이용해 관련 temperature sensor ID를 조회합니다.

Thermal Methods
===============

WMI method GetFanSensors([in] uint32 arg2, [out] uint32 argr)
-------------------------------------------------------------

+--------------------+------------------------------------+--------------------+
| Operation (Byte 0) | Description                        | Arguments          |
+====================+====================================+====================+
| 0x01               | Get the number of temperature      | - Byte 1: Fan ID   |
|                    | sensors related with a fan ID      |                    |
+--------------------+------------------------------------+--------------------+
| 0x02               | Get the temperature sensor IDs     | - Byte 1: Fan ID   |
|                    | related to a fan sensor ID         | - Byte 2: Index    |
+--------------------+------------------------------------+--------------------+

Thermal_Information

`Thermal_Information`은 system resource 구성, sensor 값, fan 속도와 thermal profile을 조회합니다. `0x02`의 반환값은 byte 0부터 fan 수, temperature sensor 수, 알려지지 않은 값, thermal profile 수의 순서입니다.

`0x03`은 index에 해당하는 ID 또는 resource를 반환합니다. 순서는 fan ID, temperature ID, 알려지지 않은 ID, thermal profile ID이며, `0x02`의 개수 정보를 이용해 각 index 구간을 해석합니다.

`0x06`의 fan 속도 백분율은 모든 모델에 구현되어 있지 않습니다. `0x01`과 `0x07`의 의미는 아직 알려지지 않았습니다.

WMI method Thermal_Information([in] uint32 arg2, [out] uint32 argr)
-------------------------------------------------------------------

+--------------------+------------------------------------+--------------------+
| Operation (Byte 0) | Description                        | Arguments          |
+====================+====================================+====================+
| 0x01               | Unknown.                           | - None             |
+--------------------+------------------------------------+--------------------+
| 0x02               | Get system description number with | - None             |
|                    | the following structure:           |                    |
|                    |                                    |                    |
|                    | - Byte 0: Number of fans           |                    |
|                    | - Byte 1: Number of temperature    |                    |
|                    |   sensors                          |                    |
|                    | - Byte 2: Unknown                  |                    |
|                    | - Byte 3: Number of thermal        |                    |
|                    |   profiles                         |                    |
+--------------------+------------------------------------+--------------------+
| 0x03               | List an ID or resource at a given  | - Byte 1: Index    |
|                    | index. Fan IDs, temperature IDs,   |                    |
|                    | unknown IDs and thermal profile    |                    |
|                    | IDs are listed in that exact       |                    |
|                    | order.                             |                    |
|                    |                                    |                    |
|                    | Operation 0x02 is used to know     |                    |
|                    | which indexes map to which         |                    |
|                    | resources.                         |                    |
|                    |                                    |                    |
|                    | **Returns:** ID at a given index   |                    |
+--------------------+------------------------------------+--------------------+
| 0x04               | Get the current temperature for a  | - Byte 1: Sensor   |
|                    | given temperature sensor.          |   ID               |
+--------------------+------------------------------------+--------------------+
| 0x05               | Get the current RPM for a given    | - Byte 1: Fan ID   |
|                    | fan.                               |                    |
+--------------------+------------------------------------+--------------------+
| 0x06               | Get fan speed percentage. (not     | - Byte 1: Fan ID   |
|                    | implemented in every model)        |                    |
+--------------------+------------------------------------+--------------------+
| 0x07               | Unknown.                           | - Unknown          |
+--------------------+------------------------------------+--------------------+
| 0x08               | Get minimum RPM for a given FAN    | - Byte 1: Fan ID   |
|                    | ID.                                |                    |
+--------------------+------------------------------------+--------------------+
| 0x09               | Get maximum RPM for a given FAN    | - Byte 1: Fan ID   |
|                    | ID.                                |                    |
+--------------------+------------------------------------+--------------------+
| 0x0A               | Get balanced thermal profile ID.   | - None             |
+--------------------+------------------------------------+--------------------+
| 0x0B               | Get current thermal profile ID.    | - None             |
+--------------------+------------------------------------+--------------------+
| 0x0C               | Get current `boost` value for a    | - Byte 1: Fan ID   |
|                    | given fan ID.                      |                    |
+--------------------+------------------------------------+--------------------+

Thermal_Control

`Thermal_Control`의 `0x01`은 thermal profile ID로 지정한 profile을 활성화합니다. `0x02`는 fan ID와 boost 값을 받아 해당 fan의 boost를 설정합니다.

WMI method Thermal_Control([in] uint32 arg2, [out] uint32 argr)
---------------------------------------------------------------

+--------------------+------------------------------------+--------------------+
| Operation (Byte 0) | Description                        | Arguments          |
+====================+====================================+====================+
| 0x01               | Activate a given thermal profile.  | - Byte 1: Thermal  |
|                    |                                    |   profile ID       |
+--------------------+------------------------------------+--------------------+
| 0x02               | Set a `boost` value for a given    | - Byte 1: Fan ID   |
|                    | fan ID.                            | - Byte 2: Boost    |
+--------------------+------------------------------------+--------------------+

thermal profile code

알려진 profile은 Special, Legacy, USTT(User Selectable Thermal Tables)로 나뉩니다. USTT와 Legacy 지원은 상호 배타적이어서 한 계열을 지원하는 모델은 다른 계열을 지원하지 않습니다.

모든 모델은 `CUSTOM(0x00)`을 지원합니다. Dell G-Series laptop에서는 `GMODE(0xAB)`가 `PERFORMANCE`를 대신합니다.

These are the known thermal profile codes:

+------------------------------+----------+------+
| Thermal Profile              | Type     | ID   |
+==============================+==========+======+
| Custom                       | Special  | 0x00 |
+------------------------------+----------+------+
| G-Mode                       | Special  | 0xAB |
+------------------------------+----------+------+
| Quiet                        | Legacy   | 0x96 |
+------------------------------+----------+------+
| Balanced                     | Legacy   | 0x97 |
+------------------------------+----------+------+
| Balanced Performance         | Legacy   | 0x98 |
+------------------------------+----------+------+
| Performance                  | Legacy   | 0x99 |
+------------------------------+----------+------+
| Balanced                     | USTT     | 0xA0 |
+------------------------------+----------+------+
| Balanced Performance         | USTT     | 0xA1 |
+------------------------------+----------+------+
| Cool                         | USTT     | 0xA2 |
+------------------------------+----------+------+
| Quiet                        | USTT     | 0xA3 |
+------------------------------+----------+------+
| Performance                  | USTT     | 0xA4 |
+------------------------------+----------+------+
| Low Power                    | USTT     | 0xA5 |
+------------------------------+----------+------+

If a model supports the User Selectable Thermal Tables (USTT) profiles, it will
not support the Legacy profiles and vice-versa.

Every model supports the CUSTOM (0x00) thermal profile. GMODE replaces
PERFORMANCE in G-Series laptops.

GameShiftStatus

`GameShiftStatus`의 `0x01`은 Game Shift를 전환하고 `0x02`는 현재 상태를 조회합니다.

Game Shift는 fan speed profile을 바꾸지 않습니다. CPU 또는 GPU power profile의 일종일 가능성이 있으나 benchmark가 수행되지 않아 확정할 수 없습니다.

이 method는 Dell G-Series laptop에만 있으며, 구현이 존재한다는 사실은 `Thermal_Information`의 `0x03` 목록에 없더라도 GMODE thermal profile을 사용할 수 있음을 시사합니다. G-Series의 G-key도 Game Shift 상태를 바꾸므로 둘은 직접 관련되어 있습니다.

WMI method GameShiftStatus([in] uint32 arg2, [out] uint32 argr)
---------------------------------------------------------------

+--------------------+------------------------------------+--------------------+
| Operation (Byte 0) | Description                        | Arguments          |
+====================+====================================+====================+
| 0x01               | Toggle *Game Shift*.               | - None             |
+--------------------+------------------------------------+--------------------+
| 0x02               | Get *Game Shift* status.           | - None             |
+--------------------+------------------------------------+--------------------+

Game Shift Status does not change the fan speed profile but it could be some
sort of CPU/GPU power profile. Benchmarks have not been done.

This method is only present on Dell's G-Series laptops and it's implementation
implies GMODE thermal profile is available, even if operation 0x03 of
Thermal_Information does not list it.

G-key on Dell's G-Series laptops also changes Game Shift status, so both are
directly related.

MemoryOCControl

AWCC는 memory overclocking을 지원하지만 `MemoryOCControl` method는 매우 복잡하며 아직 해석되지 않았습니다.

Overclocking Methods
====================

WMI method MemoryOCControl([in] uint32 arg2, [out] uint32 argr)
---------------------------------------------------------------

AWCC supports memory overclocking, but this method is very intricate and has
not been deciphered yet.

STM32 RGB controller와 GPIO

AWCC interface가 있는 Alienware와 Dell G-Series 장치에는 보통 USB/HID 기능을 갖춘 STM32 RGB lighting controller가 내장됩니다. vendor ID는 `187c`이고 product ID는 모델마다 다를 수 있습니다.

debugging을 위해 이 MCU의 GPIO pin 두 개가 WMI method로 노출됩니다. pin 0은 Device Firmware Update(DFU) mode pin으로 HIGH이면 다음 MCU 부팅 때 DFU mode를 활성화하고 LOW이면 비활성화합니다. pin 1은 active-low reset(NRST) pin으로 HIGH이면 MCU가 켜지고 LOW이면 꺼집니다.

일부 GPIO 제어 method는 일반적인 인수 구조를 따르지 않고 첫 번째 byte에 operation 대신 pin 번호를 받습니다.

GPIO control Methods
====================

Alienware and Dell G Series devices with the AWCC interface usually have an
embedded STM32 RGB lighting controller with USB/HID capabilities. It's vendor ID
is ``187c`` while it's product ID may vary from model to model.

The control of two GPIO pins of this MCU is exposed as WMI methods for debugging
purposes.

+--------------+--------------------------------------------------------------+
| Pin          | Description                                                  |
+==============+===============================+==============================+
| 0            | Device Firmware Update (DFU)  | **HIGH**: Enables DFU mode   |
|              | mode pin.                     | on next MCU boot.            |
|              |                               +------------------------------+
|              |                               | **LOW**: Disables DFU mode   |
|              |                               | on next MCU boot.            |
+--------------+-------------------------------+------------------------------+
| 1            | Negative Reset (NRST) pin.    | **HIGH**: MCU is ON.         |
|              |                               |                              |
|              |                               +------------------------------+
|              |                               | **LOW**: MCU is OFF.         |
|              |                               |                              |
+--------------+-------------------------------+------------------------------+

See :ref:`acknowledgements` for more information on this MCU.

.. note::
   Some GPIO control methods break the usual argument structure and take a
   **Pin number** instead of an operation on the first byte.

FWUpdateGPIOtoggle

`FWUpdateGPIOtoggle`은 첫 번째 byte의 pin 번호와 Byte 1의 pin 상태를 받아 해당 GPIO 상태를 설정합니다.

WMI method FWUpdateGPIOtoggle([in] uint32 arg2, [out] uint32 argr)
------------------------------------------------------------------

+--------------------+------------------------------------+--------------------+
| Operation (Byte 0) | Description                        | Arguments          |
+====================+====================================+====================+
| Pin number         | Set the pin status                 | - Byte 1: Pin      |
|                    |                                    |   status           |
+--------------------+------------------------------------+--------------------+

ReadTotalofGPIOs

`ReadTotalofGPIOs`는 GPIO의 전체 개수를 반환하며 별도의 operation은 없습니다. 다만 firmware 수준의 WMI method 구현 방식 때문에 호출할 때 dummy `uint32` 입력 인수가 필요합니다.

WMI method ReadTotalofGPIOs([out] uint32 argr)
----------------------------------------------

+--------------------+------------------------------------+--------------------+
| Operation (Byte 0) | Description                        | Arguments          |
+====================+====================================+====================+
| N/A                | Get the total number of GPIOs      | - None             |
+--------------------+------------------------------------+--------------------+

.. note::
   Due to how WMI methods are implemented on the firmware level, this method
   requires a dummy uint32 input argument when invoked.

ReadGPIOpPinStatus

`ReadGPIOpPinStatus`는 첫 번째 byte에 pin 번호를 받아 상태를 조회합니다. 일부 laptop firmware에는 pin 상태를 읽는 동시에 그 상태를 뒤집는 알려진 bug가 있습니다.

WMI method ReadGPIOpPinStatus([in] uint32 arg2, [out] uint32 argr)
------------------------------------------------------------------

+--------------------+------------------------------------+--------------------+
| Operation (Byte 0) | Description                        | Arguments          |
+====================+====================================+====================+
| Pin number         | Get the pin status                 | - None             |
+--------------------+------------------------------------+--------------------+

.. note::
   There known firmware bug in some laptops where reading the status of a pin
   also flips it.

ReadChassisColor

`ReadChassisColor`는 chassis 색상의 내부 ID를 반환합니다.

Other information Methods
=========================

WMI method ReadChassisColor([out] uint32 argr)
----------------------------------------------

Returns the chassis color internal ID.

감사의 말

AlexIII, T-Troll, Gabriel Marcano가 장치 기능의 일부를 문서화하고 시험해 이 드라이버를 일반화할 수 있게 한 공헌에 감사를 표합니다. 각 프로젝트와 분석 글의 link는 원문에 보존되어 있습니다.

.. _acknowledgements:

Acknowledgements
================

Kudos to

* `AlexIII <https://github.com/AlexIII/tcc-g15>`_
* `T-Troll <https://github.com/T-Troll/alienfx-tools/>`_
* `Gabriel Marcano <https://gabriel.marcanobrady.family/blog/2024/12/16/dell-g5-5505-se-acpi-or-figuring-out-how-to-reset-the-rgb-controller/>`_

for documenting and testing some of this device's functionality, making it
possible to generalize this driver.