alienware-wmi.rst

  1.. SPDX-License-Identifier: GPL-2.0-or-later
  2
  3====================
  4Alienware WMI Driver
  5====================
  6
  7Kurt Borja <kuurtb@gmail.com>
  8
  9This is a driver for the "WMAX" WMI device, which is found in most Dell gaming
 10laptops and controls various special features.
 11
 12Before the launch of M-Series laptops (~2018), the "WMAX" device controlled
 13basic RGB lighting, deep sleep mode, HDMI mode and amplifier status.
 14
 15Later, this device was completely repurpused. Now it mostly deals with thermal
 16profiles, sensor monitoring and overclocking. This interface is named "AWCC" and
 17is known to be used by the AWCC OEM application to control these features.
 18
 19The alienware-wmi driver controls both interfaces.
 20
 21AWCC Interface
 22==============
 23
 24WMI device documentation: Documentation/wmi/devices/alienware-wmi.rst
 25
 26Supported devices
 27-----------------
 28
 29- Alienware M-Series laptops
 30- Alienware X-Series laptops
 31- Alienware Aurora Desktops
 32- Dell G-Series laptops
 33
 34If you believe your device supports the AWCC interface and you don't have any of
 35the features described in this document, try the following alienware-wmi module
 36parameters:
 37
 38- ``force_platform_profile=1``: Forces probing for platform profile support
 39- ``force_hwmon=1``: Forces probing for HWMON support
 40
 41If the module loads successfully with these parameters, consider submitting a
 42patch adding your model to the ``awcc_dmi_table`` located in
 43``drivers/platform/x86/dell/alienware-wmi-wmax.c`` or contacting the maintainer
 44for further guidance.
 45
 46Status
 47------
 48
 49The following features are currently supported:
 50
 51- :ref:`Platform Profile <platform-profile>`:
 52
 53  - Thermal profile control
 54
 55  - G-Mode toggling
 56
 57- :ref:`HWMON <hwmon>`:
 58
 59  - Sensor monitoring
 60
 61  - Manual fan control
 62
 63.. _platform-profile:
 64
 65Platform Profile
 66----------------
 67
 68The AWCC interface exposes various firmware defined thermal profiles. These are
 69exposed to user-space through the Platform Profile class interface. Refer to
 70:ref:`sysfs-class-platform-profile <abi_file_testing_sysfs_class_platform_profile>`
 71for more information.
 72
 73The name of the platform-profile class device exported by this driver is
 74"alienware-wmi" and it's path can be found with:
 75
 76::
 77
 78 grep -l "alienware-wmi" /sys/class/platform-profile/platform-profile-*/name | sed 's|/[^/]*$||'
 79
 80If the device supports G-Mode, it is also toggled when selecting the
 81``performance`` profile.
 82
 83.. note::
 84   You may set the ``force_gmode`` module parameter to always try to toggle this
 85   feature, without checking if your model supports it.
 86
 87.. _hwmon:
 88
 89HWMON
 90-----
 91
 92The AWCC interface also supports sensor monitoring and manual fan control. Both
 93of these features are exposed to user-space through the HWMON interface.
 94
 95The name of the hwmon class device exported by this driver is "alienware_wmi"
 96and it's path can be found with:
 97
 98::
 99
100 grep -l "alienware_wmi" /sys/class/hwmon/hwmon*/name | sed 's|/[^/]*$||'
101
102Sensor monitoring is done through the standard HWMON interface. Refer to
103:ref:`sysfs-class-hwmon <abi_file_testing_sysfs_class_hwmon>` for more
104information.
105
106Manual fan control on the other hand, is not exposed directly by the AWCC
107interface. Instead it let's us control a fan `boost` value. This `boost` value
108has the following approximate behavior over the fan pwm:
109
110::
111
112 pwm = pwm_base + (fan_boost / 255) * (pwm_max - pwm_base)
113
114Due to the above behavior, the fan `boost` control is exposed to user-space
115through the following, custom hwmon sysfs attribute:
116
117=============================== ======= =======================================
118Name				Perm	Description
119=============================== ======= =======================================
120fan[1-4]_boost			RW	Fan boost value.
121
122					Integer value between 0 and 255
123=============================== ======= =======================================
124
125.. note::
126   In some devices, manual fan control only works reliably if the ``custom``
127   platform profile is selected.