Documentation/wmi/devices/alienware-wmi.rst

   1 .. SPDX-License-Identifier: GPL-2.0-or-later
   2
   3 ==============================================
   4 Dell AWCC WMI interface driver (alienware-wmi)
   5 ==============================================
   6
   7 Introduction
   8 ============
   9
  10 The WMI device WMAX has been implemented for many Alienware and Dell's G-Series
  11 models. Throughout these models, two implementations have been identified. The
  12 first one, used by older systems, deals with HDMI, brightness, RGB, amplifier
  13 and deep sleep control. The second one used by newer systems deals primarily
  14 with thermal, overclocking, and GPIO control.
  15
  16 It is suspected that the latter is used by Alienware Command Center (AWCC) to
  17 manage manufacturer predefined thermal profiles. The alienware-wmi driver
  18 exposes Thermal_Information and Thermal_Control methods through the Platform
  19 Profile API to mimic AWCC's behavior.
  20
  21 This newer interface, named AWCCMethodFunction has been reverse engineered, as
  22 Dell has not provided any official documentation. We will try to describe to the
  23 best 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
  29 WMI interface description
  30 -------------------------
  31
  32 The WMI interface description can be decoded from the embedded binary MOF (bmof)
  33 data 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
  72 Some of these methods get quite intricate so we will describe them using
  73 pseudo-code that vaguely resembles the original ASL code.
  74
  75 Methods not described in the following document have unknown behavior.
  76
  77 Argument Structure
  78 ------------------
  79
  80 All input arguments have type **uint32** and their structure is very similar
  81 between methods. Usually, the first byte corresponds to a specific *operation*
  82 the method performs, and the subsequent bytes correspond to *arguments* passed
  83 to this *operation*. For example, if an operation has code 0x01 and requires an
  84 ID 0xA0, the argument you would pass to the method is 0xA001.
  85
  86
  87 Thermal Methods
  88 ===============
  89
  90 WMI method Thermal_Information([in] uint32 arg2, [out] uint32 argr)
  91 -------------------------------------------------------------------
  92
  93 ::
  94
  95  if BYTE_0(arg2) == 0x01:
  96          argr = 1
  97
  98  if BYTE_0(arg2) == 0x02:
  99          argr = SYSTEM_DESCRIPTION
 100
 101  if BYTE_0(arg2) == 0x03:
 102          if BYTE_1(arg2) == 0x00:
 103                  argr = FAN_ID_0
 104
 105          if BYTE_1(arg2) == 0x01:
 106                  argr = FAN_ID_1
 107
 108          if BYTE_1(arg2) == 0x02:
 109                  argr = FAN_ID_2
 110
 111          if BYTE_1(arg2) == 0x03:
 112                  argr = FAN_ID_3
 113
 114          if BYTE_1(arg2) == 0x04:
 115                  argr = SENSOR_ID_CPU | 0x0100
 116
 117          if BYTE_1(arg2) == 0x05:
 118                  argr = SENSOR_ID_GPU | 0x0100
 119
 120          if BYTE_1(arg2) == 0x06:
 121                  argr = THERMAL_MODE_QUIET_ID
 122
 123          if BYTE_1(arg2) == 0x07:
 124                  argr = THERMAL_MODE_BALANCED_ID
 125
 126          if BYTE_1(arg2) == 0x08:
 127                  argr = THERMAL_MODE_BALANCED_PERFORMANCE_ID
 128
 129          if BYTE_1(arg2) == 0x09:
 130                  argr = THERMAL_MODE_PERFORMANCE_ID
 131
 132          if BYTE_1(arg2) == 0x0A:
 133                  argr = THERMAL_MODE_LOW_POWER_ID
 134
 135          if BYTE_1(arg2) == 0x0B:
 136                  argr = THERMAL_MODE_GMODE_ID
 137
 138          else:
 139                  argr = 0xFFFFFFFF
 140
 141  if BYTE_0(arg2) == 0x04:
 142          if is_valid_sensor(BYTE_1(arg2)):
 143                  argr = SENSOR_TEMP_C
 144          else:
 145                  argr = 0xFFFFFFFF
 146
 147  if BYTE_0(arg2) == 0x05:
 148          if is_valid_fan(BYTE_1(arg2)):
 149                  argr = FAN_RPM()
 150
 151  if BYTE_0(arg2) == 0x06:
 152          skip
 153
 154  if BYTE_0(arg2) == 0x07:
 155          argr = 0
 156
 157  If BYTE_0(arg2) == 0x08:
 158          if is_valid_fan(BYTE_1(arg2)):
 159                  argr = 0
 160          else:
 161                  argr = 0xFFFFFFFF
 162
 163  if BYTE_0(arg2) == 0x09:
 164          if is_valid_fan(BYTE_1(arg2)):
 165                  argr = FAN_UNKNOWN_STAT_0()
 166
 167          else:
 168                  argr = 0xFFFFFFFF
 169
 170  if BYTE_0(arg2) == 0x0A:
 171          argr = THERMAL_MODE_BALANCED_ID
 172
 173  if BYTE_0(arg2) == 0x0B:
 174          argr = CURRENT_THERMAL_MODE()
 175
 176  if BYTE_0(arg2) == 0x0C:
 177          if is_valid_fan(BYTE_1(arg2)):
 178                  argr = FAN_UNKNOWN_STAT_1()
 179          else:
 180                  argr = 0xFFFFFFFF
 181
 182 Operation 0x02 returns a *system description* buffer with the following
 183 structure:
 184
 185 ::
 186
 187  out[0] -> Number of fans
 188  out[1] -> Number of sensors
 189  out[2] -> 0x00
 190  out[3] -> Number of thermal modes
 191
 192 Operation 0x03 list all available fan IDs, sensor IDs and thermal profile
 193 codes in order, but different models may have different number of fans and
 194 thermal profiles. These are the known ranges:
 195
 196 * Fan IDs: from 2 up to 4
 197 * Sensor IDs: 2
 198 * Thermal profile codes: from 1 up to 7
 199
 200 In total BYTE_1(ARG2) may range from 0x5 up to 0xD depending on the model.
 201
 202 WMI method Thermal_Control([in] uint32 arg2, [out] uint32 argr)
 203 ---------------------------------------------------------------
 204
 205 ::
 206
 207  if BYTE_0(arg2) == 0x01:
 208          if is_valid_thermal_profile(BYTE_1(arg2)):
 209                  SET_THERMAL_PROFILE(BYTE_1(arg2))
 210                  argr = 0
 211
 212  if BYTE_0(arg2) == 0x02:
 213          if is_valid_fan(BYTE_1(arg2)):
 214                  SET_FAN_SPEED_MULTIPLIER(BYTE_2(arg2))
 215                  argr = 0
 216          else:
 217                  argr = 0xFFFFFFFF
 218
 219 .. note::
 220    While you can manually change the fan speed multiplier with this method,
 221    Dell's BIOS tends to overwrite this changes anyway.
 222
 223 These are the known thermal profile codes:
 224
 225 ::
 226
 227  CUSTOM                         0x00
 228
 229  BALANCED_USTT                  0xA0
 230  BALANCED_PERFORMANCE_USTT      0xA1
 231  COOL_USTT                      0xA2
 232  QUIET_USTT                     0xA3
 233  PERFORMANCE_USTT               0xA4
 234  LOW_POWER_USTT                 0xA5
 235
 236  QUIET                          0x96
 237  BALANCED                       0x97
 238  BALANCED_PERFORMANCE           0x98
 239  PERFORMANCE                    0x99
 240
 241  GMODE                          0xAB
 242
 243 Usually if a model doesn't support the first four profiles they will support
 244 the User Selectable Thermal Tables (USTT) profiles and vice-versa.
 245
 246 GMODE replaces PERFORMANCE in G-Series laptops.
 247
 248 WMI method GameShiftStatus([in] uint32 arg2, [out] uint32 argr)
 249 ---------------------------------------------------------------
 250
 251 ::
 252
 253  if BYTE_0(arg2) == 0x1:
 254          TOGGLE_GAME_SHIFT()
 255          argr = GET_GAME_SHIFT_STATUS()
 256
 257  if BYTE_0(arg2) == 0x2:
 258          argr = GET_GAME_SHIFT_STATUS()
 259
 260 Game Shift Status does not change the fan speed profile but it could be some
 261 sort of CPU/GPU power profile. Benchmarks have not been done.
 262
 263 This method is only present on Dell's G-Series laptops and it's implementation
 264 implies GMODE thermal profile is available, even if operation 0x03 of
 265 Thermal_Information does not list it.
 266
 267 G-key on Dell's G-Series laptops also changes Game Shift status, so both are
 268 directly related.
 269
 270 WMI method GetFanSensors([in] uint32 arg2, [out] uint32 argr)
 271 -------------------------------------------------------------
 272
 273 ::
 274
 275  if BYTE_0(arg2) == 0x1:
 276         if is_valid_fan(BYTE_1(arg2)):
 277                 argr = 1
 278         else:
 279                 argr = 0
 280
 281  if BYTE_0(arg2) == 0x2:
 282         if is_valid_fan(BYTE_1(arg2)):
 283                 if BYTE_2(arg2) == 0:
 284                         argr == SENSOR_ID
 285                 else
 286                         argr == 0xFFFFFFFF
 287         else:
 288                 argr = 0
 289
 290 Overclocking Methods
 291 ====================
 292
 293 .. warning::
 294    These methods have not been tested and are only partially reverse
 295    engineered.
 296
 297 WMI method Return_OverclockingReport([out] uint32 argr)
 298 -------------------------------------------------------
 299
 300 ::
 301
 302  CSMI (0xE3, 0x99)
 303  argr = 0
 304
 305 CSMI is an unknown operation.
 306
 307 WMI method Set_OCUIBIOSControl([in] uint32 arg2, [out] uint32 argr)
 308 -------------------------------------------------------------------
 309
 310 ::
 311
 312  CSMI (0xE3, 0x99)
 313  argr = 0
 314
 315 CSMI is an unknown operation.
 316
 317 WMI method Clear_OCFailSafeFlag([out] uint32 argr)
 318 --------------------------------------------------
 319
 320 ::
 321
 322  CSMI (0xE3, 0x99)
 323  argr = 0
 324
 325 CSMI is an unknown operation.
 326
 327
 328 WMI method MemoryOCControl([in] uint32 arg2, [out] uint32 argr)
 329 ---------------------------------------------------------------
 330
 331 AWCC supports memory overclocking, but this method is very intricate and has
 332 not been deciphered yet.
 333
 334 GPIO methods
 335 ============
 336
 337 These methods are probably related to some kind of firmware update system,
 338 through a GPIO device.
 339
 340 .. warning::
 341    These methods have not been tested and are only partially reverse
 342    engineered.
 343
 344 WMI method FWUpdateGPIOtoggle([in] uint32 arg2, [out] uint32 argr)
 345 ------------------------------------------------------------------
 346
 347 ::
 348
 349  if BYTE_0(arg2) == 0:
 350          if BYTE_1(arg2) == 1:
 351                  SET_PIN_A_HIGH()
 352          else:
 353                  SET_PIN_A_LOW()
 354
 355  if BYTE_0(arg2) == 1:
 356          if BYTE_1(arg2) == 1:
 357                  SET_PIN_B_HIGH()
 358
 359          else:
 360                  SET_PIN_B_LOW()
 361
 362  else:
 363          argr = 1
 364
 365 WMI method ReadTotalofGPIOs([out] uint32 argr)
 366 ----------------------------------------------
 367
 368 ::
 369
 370  argr = 0x02
 371
 372 WMI method ReadGPIOpPinStatus([in] uint32 arg2, [out] uint32 argr)
 373 ------------------------------------------------------------------
 374
 375 ::
 376
 377  if BYTE_0(arg2) == 0:
 378          argr = PIN_A_STATUS
 379
 380  if BYTE_0(arg2) == 1:
 381          argr = PIN_B_STATUS
 382
 383 Other information Methods
 384 =========================
 385
 386 WMI method ReadChassisColor([out] uint32 argr)
 387 ----------------------------------------------
 388
 389 ::
 390
 391  argr = CHASSIS_COLOR_ID
 392
 393 Acknowledgements
 394 ================
 395
 396 Kudos to `AlexIII <https://github.com/AlexIII/tcc-g15>`_ for documenting
 397 and testing available thermal profile codes.