[PATCH v6 10/12] Documentation: wmi: Improve and update alienware-wmi documentation

Kurt Borja
2025-03-13T14:30:34Z

Use tables to describe method operations instead of using pseudo-code.
Drop unknown method descriptions to avoid redundancy. Drop GPIO section
as it is currently irrelevant to this driver. Update Thermal_Information
method documentation. Add one more helpful developer to the kudos section.

Reviewed-by: Armin Wolf <W_Armin@gmx.de>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Kurt Borja <kuurtb@gmail.com>
---
Documentation/wmi/devices/alienware-wmi.rst | 383 +++++++++-------------------
1 file changed, 117 insertions(+), 266 deletions(-)

diff --git a/Documentation/wmi/devices/alienware-wmi.rst b/Documentation/wmi/devices/alienware-wmi.rst
index ddc5e561960e05fc7cffe700d7d278e32ff2e7b2..79238051b18bc5de9b502325017cd5c5fcf41748 100644
--- a/Documentation/wmi/devices/alienware-wmi.rst
+++ b/Documentation/wmi/devices/alienware-wmi.rst
@@ -11,7 +11,7 @@ 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, overclocking, and GPIO control.
+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
@@ -69,9 +69,6 @@ data using the `bmfdec <https://github.com/pali/bmfdec>`_ utility:
[WmiMethodId(164), Implemented, read, write, Description("Tobii Camera Power Off.")] void TobiiCameraPowerOff([out] uint32 argr);
};

-Some of these methods get quite intricate so we will describe them using
-pseudo-code that vaguely resembles the original ASL code.
-
Methods not described in the following document have unknown behavior.

Argument Structure
@@ -87,175 +84,133 @@ ID 0xA0, the argument you would pass to the method is 0xA001.
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 |
++--------------------+------------------------------------+--------------------+
+
WMI method Thermal_Information([in] uint32 arg2, [out] uint32 argr)
-------------------------------------------------------------------

-::
-
- if BYTE_0(arg2) == 0x01:
- argr = 1
-
- if BYTE_0(arg2) == 0x02:
- argr = SYSTEM_DESCRIPTION
-
- if BYTE_0(arg2) == 0x03:
- if BYTE_1(arg2) == 0x00:
- argr = FAN_ID_0
-
- if BYTE_1(arg2) == 0x01:
- argr = FAN_ID_1
-
- if BYTE_1(arg2) == 0x02:
- argr = FAN_ID_2
-
- if BYTE_1(arg2) == 0x03:
- argr = FAN_ID_3
-
- if BYTE_1(arg2) == 0x04:
- argr = SENSOR_ID_CPU | 0x0100
-
- if BYTE_1(arg2) == 0x05:
- argr = SENSOR_ID_GPU | 0x0100
-
- if BYTE_1(arg2) == 0x06:
- argr = THERMAL_MODE_QUIET_ID
-
- if BYTE_1(arg2) == 0x07:
- argr = THERMAL_MODE_BALANCED_ID
-
- if BYTE_1(arg2) == 0x08:
- argr = THERMAL_MODE_BALANCED_PERFORMANCE_ID
-
- if BYTE_1(arg2) == 0x09:
- argr = THERMAL_MODE_PERFORMANCE_ID
-
- if BYTE_1(arg2) == 0x0A:
- argr = THERMAL_MODE_LOW_POWER_ID
-
- if BYTE_1(arg2) == 0x0B:
- argr = THERMAL_MODE_GMODE_ID
-
- else:
- argr = 0xFFFFFFFF
-
- if BYTE_0(arg2) == 0x04:
- if is_valid_sensor(BYTE_1(arg2)):
- argr = SENSOR_TEMP_C
- else:
- argr = 0xFFFFFFFF
-
- if BYTE_0(arg2) == 0x05:
- if is_valid_fan(BYTE_1(arg2)):
- argr = FAN_RPM()
-
- if BYTE_0(arg2) == 0x06:
- skip
-
- if BYTE_0(arg2) == 0x07:
- argr = 0
-
- If BYTE_0(arg2) == 0x08:
- if is_valid_fan(BYTE_1(arg2)):
- argr = 0
- else:
- argr = 0xFFFFFFFF
-
- if BYTE_0(arg2) == 0x09:
- if is_valid_fan(BYTE_1(arg2)):
- argr = FAN_UNKNOWN_STAT_0()
-
- else:
- argr = 0xFFFFFFFF
-
- if BYTE_0(arg2) == 0x0A:
- argr = THERMAL_MODE_BALANCED_ID
-
- if BYTE_0(arg2) == 0x0B:
- argr = CURRENT_THERMAL_MODE()
-
- if BYTE_0(arg2) == 0x0C:
- if is_valid_fan(BYTE_1(arg2)):
- argr = FAN_UNKNOWN_STAT_1()
- else:
- argr = 0xFFFFFFFF
-
-Operation 0x02 returns a *system description* buffer with the following
-structure:
-
-::
-
- out[0] -> Number of fans
- out[1] -> Number of sensors
- out[2] -> 0x00
- out[3] -> Number of thermal modes
-
-Operation 0x03 list all available fan IDs, sensor IDs and thermal profile
-codes in order, but different models may have different number of fans and
-thermal profiles. These are the known ranges:
-
-* Fan IDs: from 2 up to 4
-* Sensor IDs: 2
-* Thermal profile codes: from 1 up to 7
-
-In total BYTE_1(ARG2) may range from 0x5 up to 0xD depending on the model.
++--------------------+------------------------------------+--------------------+
+| 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. | |
++--------------------+------------------------------------+--------------------+

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

-::
-
- if BYTE_0(arg2) == 0x01:
- if is_valid_thermal_profile(BYTE_1(arg2)):
- SET_THERMAL_PROFILE(BYTE_1(arg2))
- argr = 0
-
- if BYTE_0(arg2) == 0x02:
- if is_valid_fan(BYTE_1(arg2)):
- SET_FAN_SPEED_MULTIPLIER(BYTE_2(arg2))
- argr = 0
- else:
- argr = 0xFFFFFFFF
-
-.. note::
- While you can manually change the fan speed multiplier with this method,
- Dell's BIOS tends to overwrite this changes anyway.
++--------------------+------------------------------------+--------------------+
+| 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 |
++--------------------+------------------------------------+--------------------+

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 |
++------------------------------+----------+------+

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

- BALANCED_USTT 0xA0
- BALANCED_PERFORMANCE_USTT 0xA1
- COOL_USTT 0xA2
- QUIET_USTT 0xA3
- PERFORMANCE_USTT 0xA4
- LOW_POWER_USTT 0xA5
-
- QUIET 0x96
- BALANCED 0x97
- BALANCED_PERFORMANCE 0x98
- PERFORMANCE 0x99
-
- GMODE 0xAB
-
-Usually if a model doesn't support the first four profiles they will support
-the User Selectable Thermal Tables (USTT) profiles and vice-versa.
-
-GMODE replaces PERFORMANCE in G-Series laptops.
+Every model supports the CUSTOM (0x00) thermal profile. GMODE replaces
+PERFORMANCE in G-Series laptops.

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

-::
-
- if BYTE_0(arg2) == 0x1:
- TOGGLE_GAME_SHIFT()
- argr = GET_GAME_SHIFT_STATUS()
-
- if BYTE_0(arg2) == 0x2:
- argr = GET_GAME_SHIFT_STATUS()
++--------------------+------------------------------------+--------------------+
+| 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.
@@ -267,131 +222,27 @@ Thermal_Information does not list it.
G-key on Dell's G-Series laptops also changes Game Shift status, so both are
directly related.

-WMI method GetFanSensors([in] uint32 arg2, [out] uint32 argr)
--------------------------------------------------------------
-
-::
-
- if BYTE_0(arg2) == 0x1:
- if is_valid_fan(BYTE_1(arg2)):
- argr = 1
- else:
- argr = 0
-
- if BYTE_0(arg2) == 0x2:
- if is_valid_fan(BYTE_1(arg2)):
- if BYTE_2(arg2) == 0:
- argr == SENSOR_ID
- else
- argr == 0xFFFFFFFF
- else:
- argr = 0
-
Overclocking Methods
====================

-.. warning::
- These methods have not been tested and are only partially reverse
- engineered.
-
-WMI method Return_OverclockingReport([out] uint32 argr)
--------------------------------------------------------
-
-::
-
- CSMI (0xE3, 0x99)
- argr = 0
-
-CSMI is an unknown operation.
-
-WMI method Set_OCUIBIOSControl([in] uint32 arg2, [out] uint32 argr)
--------------------------------------------------------------------
-
-::
-
- CSMI (0xE3, 0x99)
- argr = 0
-
-CSMI is an unknown operation.
-
-WMI method Clear_OCFailSafeFlag([out] uint32 argr)
---------------------------------------------------
-
-::
-
- CSMI (0xE3, 0x99)
- argr = 0
-
-CSMI is an unknown operation.
-
-
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.

-GPIO methods
-============
-
-These methods are probably related to some kind of firmware update system,
-through a GPIO device.
-
-.. warning::
- These methods have not been tested and are only partially reverse
- engineered.
-
-WMI method FWUpdateGPIOtoggle([in] uint32 arg2, [out] uint32 argr)
-------------------------------------------------------------------
-
-::
-
- if BYTE_0(arg2) == 0:
- if BYTE_1(arg2) == 1:
- SET_PIN_A_HIGH()
- else:
- SET_PIN_A_LOW()
-
- if BYTE_0(arg2) == 1:
- if BYTE_1(arg2) == 1:
- SET_PIN_B_HIGH()
-
- else:
- SET_PIN_B_LOW()
-
- else:
- argr = 1
-
-WMI method ReadTotalofGPIOs([out] uint32 argr)
-----------------------------------------------
-
-::
-
- argr = 0x02
-
-WMI method ReadGPIOpPinStatus([in] uint32 arg2, [out] uint32 argr)
-------------------------------------------------------------------
-
-::
-
- if BYTE_0(arg2) == 0:
- argr = PIN_A_STATUS
-
- if BYTE_0(arg2) == 1:
- argr = PIN_B_STATUS
-
Other information Methods
=========================

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

-::
-
- argr = CHASSIS_COLOR_ID
+Returns the chassis color internal ID.

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

-Kudos to `AlexIII <https://github.com/AlexIII/tcc-g15>`_ for documenting
-and testing available thermal profile codes.
+Kudos to `AlexIII <https://github.com/AlexIII/tcc-g15>`_ and
+`T-Troll <https://github.com/T-Troll/alienfx-tools/>`_ for documenting and
+testing some of this device's functionality, making it possible to generalize
+this driver.

--
2.48.1