1.. SPDX-License-Identifier: GPL-2.0-or-later 2 3============================================== 4Dell AWCC WMI interface driver (alienware-wmi) 5============================================== 6 7Introduction 8============ 9 10The WMI device WMAX has been implemented for many Alienware and Dell's G-Series 11models. Throughout these models, two implementations have been identified. The 12first one, used by older systems, deals with HDMI, brightness, RGB, amplifier 13and deep sleep control. The second one used by newer systems deals primarily 14with thermal control and overclocking. 15 16It is suspected that the latter is used by Alienware Command Center (AWCC) to 17manage manufacturer predefined thermal profiles. The alienware-wmi driver 18exposes Thermal_Information and Thermal_Control methods through the Platform 19Profile API to mimic AWCC's behavior. 20 21This newer interface, named AWCCMethodFunction has been reverse engineered, as 22Dell has not provided any official documentation. We will try to describe to the 23best of our ability its discovered inner workings. 24 25.. note:: 26 The following method description may be incomplete and some operations have 27 different implementations between devices. 28 29WMI interface description 30------------------------- 31 32The WMI interface description can be decoded from the embedded binary MOF (bmof) 33data using the `bmfdec <https://github.com/pali/bmfdec>`_ utility: 34 35:: 36 37 [WMI, Dynamic, Provider("WmiProv"), Locale("MS\\0x409"), Description("WMI Function"), guid("{A70591CE-A997-11DA-B012-B622A1EF5492}")] 38 class AWCCWmiMethodFunction { 39 [key, read] string InstanceName; 40 [read] boolean Active; 41 42 [WmiMethodId(13), Implemented, read, write, Description("Return Overclocking Report.")] void Return_OverclockingReport([out] uint32 argr); 43 [WmiMethodId(14), Implemented, read, write, Description("Set OCUIBIOS Control.")] void Set_OCUIBIOSControl([in] uint32 arg2, [out] uint32 argr); 44 [WmiMethodId(15), Implemented, read, write, Description("Clear OC FailSafe Flag.")] void Clear_OCFailSafeFlag([out] uint32 argr); 45 [WmiMethodId(19), Implemented, read, write, Description("Get Fan Sensors.")] void GetFanSensors([in] uint32 arg2, [out] uint32 argr); 46 [WmiMethodId(20), Implemented, read, write, Description("Thermal Information.")] void Thermal_Information([in] uint32 arg2, [out] uint32 argr); 47 [WmiMethodId(21), Implemented, read, write, Description("Thermal Control.")] void Thermal_Control([in] uint32 arg2, [out] uint32 argr); 48 [WmiMethodId(23), Implemented, read, write, Description("MemoryOCControl.")] void MemoryOCControl([in] uint32 arg2, [out] uint32 argr); 49 [WmiMethodId(26), Implemented, read, write, Description("System Information.")] void SystemInformation([in] uint32 arg2, [out] uint32 argr); 50 [WmiMethodId(28), Implemented, read, write, Description("Power Information.")] void PowerInformation([in] uint32 arg2, [out] uint32 argr); 51 [WmiMethodId(32), Implemented, read, write, Description("FW Update GPIO toggle.")] void FWUpdateGPIOtoggle([in] uint32 arg2, [out] uint32 argr); 52 [WmiMethodId(33), Implemented, read, write, Description("Read Total of GPIOs.")] void ReadTotalofGPIOs([out] uint32 argr); 53 [WmiMethodId(34), Implemented, read, write, Description("Read GPIO pin Status.")] void ReadGPIOpPinStatus([in] uint32 arg2, [out] uint32 argr); 54 [WmiMethodId(35), Implemented, read, write, Description("Read Chassis Color.")] void ReadChassisColor([out] uint32 argr); 55 [WmiMethodId(36), Implemented, read, write, Description("Read Platform Properties.")] void ReadPlatformProperties([out] uint32 argr); 56 [WmiMethodId(37), Implemented, read, write, Description("Game Shift Status.")] void GameShiftStatus([in] uint32 arg2, [out] uint32 argr); 57 [WmiMethodId(128), Implemented, read, write, Description("Caldera SW installation.")] void CalderaSWInstallation([out] uint32 argr); 58 [WmiMethodId(129), Implemented, read, write, Description("Caldera SW is released.")] void CalderaSWReleased([out] uint32 argr); 59 [WmiMethodId(130), Implemented, read, write, Description("Caldera Connection Status.")] void CalderaConnectionStatus([in] uint32 arg2, [out] uint32 argr); 60 [WmiMethodId(131), Implemented, read, write, Description("Surprise Unplugged Flag Status.")] void SurpriseUnpluggedFlagStatus([out] uint32 argr); 61 [WmiMethodId(132), Implemented, read, write, Description("Clear Surprise Unplugged Flag.")] void ClearSurpriseUnpluggedFlag([out] uint32 argr); 62 [WmiMethodId(133), Implemented, read, write, Description("Cancel Undock Request.")] void CancelUndockRequest([out] uint32 argr); 63 [WmiMethodId(135), Implemented, read, write, Description("Devices in Caldera.")] void DevicesInCaldera([in] uint32 arg2, [out] uint32 argr); 64 [WmiMethodId(136), Implemented, read, write, Description("Notify BIOS for SW ready to disconnect Caldera.")] void NotifyBIOSForSWReadyToDisconnectCaldera([out] uint32 argr); 65 [WmiMethodId(160), Implemented, read, write, Description("Tobii SW installation.")] void TobiiSWinstallation([out] uint32 argr); 66 [WmiMethodId(161), Implemented, read, write, Description("Tobii SW Released.")] void TobiiSWReleased([out] uint32 argr); 67 [WmiMethodId(162), Implemented, read, write, Description("Tobii Camera Power Reset.")] void TobiiCameraPowerReset([out] uint32 argr); 68 [WmiMethodId(163), Implemented, read, write, Description("Tobii Camera Power On.")] void TobiiCameraPowerOn([out] uint32 argr); 69 [WmiMethodId(164), Implemented, read, write, Description("Tobii Camera Power Off.")] void TobiiCameraPowerOff([out] uint32 argr); 70 }; 71 72Methods not described in the following document have unknown behavior. 73 74Argument Structure 75------------------ 76 77All input arguments have type **uint32** and their structure is very similar 78between methods. Usually, the first byte corresponds to a specific *operation* 79the method performs, and the subsequent bytes correspond to *arguments* passed 80to this *operation*. For example, if an operation has code 0x01 and requires an 81ID 0xA0, the argument you would pass to the method is 0xA001. 82 83 84Thermal Methods 85=============== 86 87WMI method GetFanSensors([in] uint32 arg2, [out] uint32 argr) 88------------------------------------------------------------- 89 90+--------------------+------------------------------------+--------------------+ 91| Operation (Byte 0) | Description | Arguments | 92+====================+====================================+====================+ 93| 0x01 | Get the number of temperature | - Byte 1: Fan ID | 94| | sensors related with a fan ID | | 95+--------------------+------------------------------------+--------------------+ 96| 0x02 | Get the temperature sensor IDs | - Byte 1: Fan ID | 97| | related to a fan sensor ID | - Byte 2: Index | 98+--------------------+------------------------------------+--------------------+ 99 100WMI method Thermal_Information([in] uint32 arg2, [out] uint32 argr) 101------------------------------------------------------------------- 102 103+--------------------+------------------------------------+--------------------+ 104| Operation (Byte 0) | Description | Arguments | 105+====================+====================================+====================+ 106| 0x01 | Unknown. | - None | 107+--------------------+------------------------------------+--------------------+ 108| 0x02 | Get system description number with | - None | 109| | the following structure: | | 110| | | | 111| | - Byte 0: Number of fans | | 112| | - Byte 1: Number of temperature | | 113| | sensors | | 114| | - Byte 2: Unknown | | 115| | - Byte 3: Number of thermal | | 116| | profiles | | 117+--------------------+------------------------------------+--------------------+ 118| 0x03 | List an ID or resource at a given | - Byte 1: Index | 119| | index. Fan IDs, temperature IDs, | | 120| | unknown IDs and thermal profile | | 121| | IDs are listed in that exact | | 122| | order. | | 123| | | | 124| | Operation 0x02 is used to know | | 125| | which indexes map to which | | 126| | resources. | | 127| | | | 128| | **Returns:** ID at a given index | | 129+--------------------+------------------------------------+--------------------+ 130| 0x04 | Get the current temperature for a | - Byte 1: Sensor | 131| | given temperature sensor. | ID | 132+--------------------+------------------------------------+--------------------+ 133| 0x05 | Get the current RPM for a given | - Byte 1: Fan ID | 134| | fan. | | 135+--------------------+------------------------------------+--------------------+ 136| 0x06 | Get fan speed percentage. (not | - Byte 1: Fan ID | 137| | implemented in every model) | | 138+--------------------+------------------------------------+--------------------+ 139| 0x07 | Unknown. | - Unknown | 140+--------------------+------------------------------------+--------------------+ 141| 0x08 | Get minimum RPM for a given FAN | - Byte 1: Fan ID | 142| | ID. | | 143+--------------------+------------------------------------+--------------------+ 144| 0x09 | Get maximum RPM for a given FAN | - Byte 1: Fan ID | 145| | ID. | | 146+--------------------+------------------------------------+--------------------+ 147| 0x0A | Get balanced thermal profile ID. | - None | 148+--------------------+------------------------------------+--------------------+ 149| 0x0B | Get current thermal profile ID. | - None | 150+--------------------+------------------------------------+--------------------+ 151| 0x0C | Get current `boost` value for a | - Byte 1: Fan ID | 152| | given fan ID. | | 153+--------------------+------------------------------------+--------------------+ 154 155WMI method Thermal_Control([in] uint32 arg2, [out] uint32 argr) 156--------------------------------------------------------------- 157 158+--------------------+------------------------------------+--------------------+ 159| Operation (Byte 0) | Description | Arguments | 160+====================+====================================+====================+ 161| 0x01 | Activate a given thermal profile. | - Byte 1: Thermal | 162| | | profile ID | 163+--------------------+------------------------------------+--------------------+ 164| 0x02 | Set a `boost` value for a given | - Byte 1: Fan ID | 165| | fan ID. | - Byte 2: Boost | 166+--------------------+------------------------------------+--------------------+ 167 168These are the known thermal profile codes: 169 170+------------------------------+----------+------+ 171| Thermal Profile | Type | ID | 172+==============================+==========+======+ 173| Custom | Special | 0x00 | 174+------------------------------+----------+------+ 175| G-Mode | Special | 0xAB | 176+------------------------------+----------+------+ 177| Quiet | Legacy | 0x96 | 178+------------------------------+----------+------+ 179| Balanced | Legacy | 0x97 | 180+------------------------------+----------+------+ 181| Balanced Performance | Legacy | 0x98 | 182+------------------------------+----------+------+ 183| Performance | Legacy | 0x99 | 184+------------------------------+----------+------+ 185| Balanced | USTT | 0xA0 | 186+------------------------------+----------+------+ 187| Balanced Performance | USTT | 0xA1 | 188+------------------------------+----------+------+ 189| Cool | USTT | 0xA2 | 190+------------------------------+----------+------+ 191| Quiet | USTT | 0xA3 | 192+------------------------------+----------+------+ 193| Performance | USTT | 0xA4 | 194+------------------------------+----------+------+ 195| Low Power | USTT | 0xA5 | 196+------------------------------+----------+------+ 197 198If a model supports the User Selectable Thermal Tables (USTT) profiles, it will 199not support the Legacy profiles and vice-versa. 200 201Every model supports the CUSTOM (0x00) thermal profile. GMODE replaces 202PERFORMANCE in G-Series laptops. 203 204WMI method GameShiftStatus([in] uint32 arg2, [out] uint32 argr) 205--------------------------------------------------------------- 206 207+--------------------+------------------------------------+--------------------+ 208| Operation (Byte 0) | Description | Arguments | 209+====================+====================================+====================+ 210| 0x01 | Toggle *Game Shift*. | - None | 211+--------------------+------------------------------------+--------------------+ 212| 0x02 | Get *Game Shift* status. | - None | 213+--------------------+------------------------------------+--------------------+ 214 215Game Shift Status does not change the fan speed profile but it could be some 216sort of CPU/GPU power profile. Benchmarks have not been done. 217 218This method is only present on Dell's G-Series laptops and it's implementation 219implies GMODE thermal profile is available, even if operation 0x03 of 220Thermal_Information does not list it. 221 222G-key on Dell's G-Series laptops also changes Game Shift status, so both are 223directly related. 224 225Overclocking Methods 226==================== 227 228WMI method MemoryOCControl([in] uint32 arg2, [out] uint32 argr) 229--------------------------------------------------------------- 230 231AWCC supports memory overclocking, but this method is very intricate and has 232not been deciphered yet. 233 234GPIO control Methods 235==================== 236 237Alienware and Dell G Series devices with the AWCC interface usually have an 238embedded STM32 RGB lighting controller with USB/HID capabilities. It's vendor ID 239is ``187c`` while it's product ID may vary from model to model. 240 241The control of two GPIO pins of this MCU is exposed as WMI methods for debugging 242purposes. 243 244+--------------+--------------------------------------------------------------+ 245| Pin | Description | 246+==============+===============================+==============================+ 247| 0 | Device Firmware Update (DFU) | **HIGH**: Enables DFU mode | 248| | mode pin. | on next MCU boot. | 249| | +------------------------------+ 250| | | **LOW**: Disables DFU mode | 251| | | on next MCU boot. | 252+--------------+-------------------------------+------------------------------+ 253| 1 | Negative Reset (NRST) pin. | **HIGH**: MCU is ON. | 254| | | | 255| | +------------------------------+ 256| | | **LOW**: MCU is OFF. | 257| | | | 258+--------------+-------------------------------+------------------------------+ 259 260See :ref:`acknowledgements` for more information on this MCU. 261 262.. note:: 263 Some GPIO control methods break the usual argument structure and take a 264 **Pin number** instead of an operation on the first byte. 265 266WMI method FWUpdateGPIOtoggle([in] uint32 arg2, [out] uint32 argr) 267------------------------------------------------------------------ 268 269+--------------------+------------------------------------+--------------------+ 270| Operation (Byte 0) | Description | Arguments | 271+====================+====================================+====================+ 272| Pin number | Set the pin status | - Byte 1: Pin | 273| | | status | 274+--------------------+------------------------------------+--------------------+ 275 276WMI method ReadTotalofGPIOs([out] uint32 argr) 277---------------------------------------------- 278 279+--------------------+------------------------------------+--------------------+ 280| Operation (Byte 0) | Description | Arguments | 281+====================+====================================+====================+ 282| N/A | Get the total number of GPIOs | - None | 283+--------------------+------------------------------------+--------------------+ 284 285.. note:: 286 Due to how WMI methods are implemented on the firmware level, this method 287 requires a dummy uint32 input argument when invoked. 288 289WMI method ReadGPIOpPinStatus([in] uint32 arg2, [out] uint32 argr) 290------------------------------------------------------------------ 291 292+--------------------+------------------------------------+--------------------+ 293| Operation (Byte 0) | Description | Arguments | 294+====================+====================================+====================+ 295| Pin number | Get the pin status | - None | 296+--------------------+------------------------------------+--------------------+ 297 298.. note:: 299 There known firmware bug in some laptops where reading the status of a pin 300 also flips it. 301 302Other information Methods 303========================= 304 305WMI method ReadChassisColor([out] uint32 argr) 306---------------------------------------------- 307 308Returns the chassis color internal ID. 309 310.. _acknowledgements: 311 312Acknowledgements 313================ 314 315Kudos to 316 317* `AlexIII <https://github.com/AlexIII/tcc-g15>`_ 318* `T-Troll <https://github.com/T-Troll/alienfx-tools/>`_ 319* `Gabriel Marcano <https://gabriel.marcanobrady.family/blog/2024/12/16/dell-g5-5505-se-acpi-or-figuring-out-how-to-reset-the-rgb-controller/>`_ 320 321for documenting and testing some of this device's functionality, making it 322possible to generalize this driver. 323