diff mbox series

[v4,11/12] Documentation: admin-guide: laptops: Add documentation for alienware-wmi

Message ID 20250308-hwm-v4-11-afa1342828f5@gmail.com (mailing list archive)
State Changes Requested, archived
Headers show
Series platform/x86: alienware-wmi-wmax: HWMON support + DebugFS + Improvements | expand

Commit Message

Kurt Borja March 8, 2025, 8:23 p.m. UTC 
Add driver admin-guide documentation for the alienware-wmi driver.

Signed-off-by: Kurt Borja <kuurtb@gmail.com>
---
 .../admin-guide/laptops/alienware-wmi.rst          | 128 +++++++++++++++++++++
 Documentation/admin-guide/laptops/index.rst        |   1 +
 MAINTAINERS                                        |   1 +
 3 files changed, 130 insertions(+)

Comments

Armin Wolf March 11, 2025, 7:27 p.m. UTC | #1 
Am 08.03.25 um 21:23 schrieb Kurt Borja:

> Add driver admin-guide documentation for the alienware-wmi driver.
>
> Signed-off-by: Kurt Borja <kuurtb@gmail.com>
> ---
>   .../admin-guide/laptops/alienware-wmi.rst          | 128 +++++++++++++++++++++
>   Documentation/admin-guide/laptops/index.rst        |   1 +
>   MAINTAINERS                                        |   1 +
>   3 files changed, 130 insertions(+)
>
> diff --git a/Documentation/admin-guide/laptops/alienware-wmi.rst b/Documentation/admin-guide/laptops/alienware-wmi.rst
> new file mode 100644
> index 0000000000000000000000000000000000000000..fa3980de77fa457ea431b20c5131d7c59a836419
> --- /dev/null
> +++ b/Documentation/admin-guide/laptops/alienware-wmi.rst
> @@ -0,0 +1,128 @@
> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +
> +====================
> +Alienware WMI Driver
> +====================
> +
> +Kurt Borja <kuurtb@gmail.com>
> +
> +This is a driver for the "WMAX" WMI device, which is found in most Dell gaming
> +laptops and controls various special features.
> +
> +Before the launch of M-Series laptops (~2018), the "WMAX" device controlled
> +basic RGB lighting, deep sleep mode, HDMI mode and amplifier status.
> +
> +Later, this device was completely repurpused. Now it mostly deals with thermal
> +profiles, sensor monitoring and overclocking. This interface is named "AWCC" and
> +is known to be used by the AWCC OEM application to control these features.
> +
> +The alienware-wmi driver controls both interfaces.
> +
> +AWCC Interface
> +==============
> +
> +WMI device Documentation: Documentation/wmi/devices/alienware-wmi.rst

Documentation -> documentation.

> +
> +Supported devices
> +-----------------
> +
> +- Alienware M-Series laptops
> +- Alienware X-Series laptops
> +- Alienware Aurora Desktops
> +- Dell G-Series laptops
> +
> +If you believe your device supports the AWCC interface and you don't have any of
> +the features described in this document, try the following alienware-wmi module
> +parameters:
> +
> +- ``force_platform_profile=1``: Forces probing for platform profile support
> +- ``force_hwmon=1``: Forces probing for HWMON support
> +
> +If the module loads successfully with these parameters, consider submitting a
> +patch adding your model to the ``awcc_dmi_table`` located in
> +``drivers/platform/x86/dell/alienware-wmi-wmax.c`` or contacting the maintainer
> +for further guidance.
> +
> +Status
> +------
> +
> +The following features are currently supported:
> +
> +- :ref:`Platform Profile <platform-profile>`:
> +
> +  - Thermal profile control
> +
> +  - G-Mode toggling
> +
> +- :ref:`HWMON <hwmon>`:
> +
> +  - Sensor monitoring
> +
> +  - Manual fan control
> +
> +.. _platform-profile:
> +
> +Platform Profile
> +----------------
> +
> +The AWCC interface exposes various firmware defined thermal profiles. We expose
> +these profiles to user-space through the Platform Profile class interface.
> +Refer to
> +:ref:`sysfs-class-platform-profile <abi_file_testing_sysfs_class_platform_profile>`
> +for more information.
> +
> +The name of the platform-profile class device exported by this driver is
> +"alienware-wmi" and it's path can be found with:
> +
> +::
> +
> + grep -l "alienware-wmi" /sys/class/platform-profile/platform-profile-*/name | sed 's|/[^/]*$||'
> +
> +If the device supports G-Mode, it is also toggled when selecting the
> +``performance`` profile.
> +
> +.. note::
> +   You may set the ``force_gmode`` module parameter to always try to toggle this
> +   feature, without checking if your model supports it.
> +
> +.. _hwmon:
> +
> +HWMON
> +-----
> +
> +The AWCC interface also supports sensor monitoring and manual fan control. Both
> +of these features are exposed to user-space through the HWMON interface.
> +
> +The name of the hwmon class device exported by this driver is "alienware_wmi"
> +and it's path can be found with:
> +
> +::
> +
> + grep -l "alienware_wmi" /sys/class/hwmon/hwmon*/name | sed 's|/[^/]*$||'
> +
> +Sensor monitoring is done through the standard HWMON interface. Refer to
> +:ref:`sysfs-class-hwmon <abi_file_testing_sysfs_class_hwmon>` for more
> +information.
> +
> +Manual fan control on the other hand, is not exposed directly by the AWCC
> +interface. Instead it let's us control a fan `boost` value. This `boost` value
> +has the following aproximate behavior over the fan pwm:
> +
> +::
> +
> + pwm = pwm_base + (fan_boost / 255) * (pwm_max - pwm_base)
> +
> +Due to the above behavior, we expose the fan `boost` control to user-space
> +through the following, custom hwmon sysfs attribute:
> +
> +=============================== ======= =======================================
> +Name				Perm	Description
> +=============================== ======= =======================================
> +fan[1-4]_boost			RW	Fan boost value.
> +
> +					Integer value between 0 and 255
> +=============================== ======= =======================================
> +
> +.. note::
> +   In some devices, manual fan control only works reliably, if the ``custom``

... works reliably if the ...

Other than that:
Reviewed-by: Armin Wolf <W_Armin@gmx.de>

> +   platform profile is selected.
> diff --git a/Documentation/admin-guide/laptops/index.rst b/Documentation/admin-guide/laptops/index.rst
> index e71c8984c23e43ca7cd6373b88803354dff6bc60..db842b629303c1bcf02646204d51938f9bd4043e 100644
> --- a/Documentation/admin-guide/laptops/index.rst
> +++ b/Documentation/admin-guide/laptops/index.rst
> @@ -7,6 +7,7 @@ Laptop Drivers
>   .. toctree::
>      :maxdepth: 1
>
> +   alienware-wmi
>      asus-laptop
>      disk-shock-protection
>      laptop-mode
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 1afd30d00aecf9a48f8c71e156affd5f329539bd..c609bc321b8dc3ab0e8d92b04e42483be8cc171c 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -796,6 +796,7 @@ M:	Kurt Borja <kuurtb@gmail.com>
>   L:	platform-driver-x86@vger.kernel.org
>   L:	Dell.Client.Kernel@dell.com
>   S:	Maintained
> +F:	Documentation/admin-guide/laptops/alienware-wmi.rst
>   F:	Documentation/wmi/devices/alienware-wmi.rst
>   F:	drivers/platform/x86/dell/alienware-wmi*
>
>
diff mbox series

Patch

diff --git a/Documentation/admin-guide/laptops/alienware-wmi.rst b/Documentation/admin-guide/laptops/alienware-wmi.rst
new file mode 100644
index 0000000000000000000000000000000000000000..fa3980de77fa457ea431b20c5131d7c59a836419
--- /dev/null
+++ b/Documentation/admin-guide/laptops/alienware-wmi.rst
@@ -0,0 +1,128 @@ 
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+====================
+Alienware WMI Driver
+====================
+
+Kurt Borja <kuurtb@gmail.com>
+
+This is a driver for the "WMAX" WMI device, which is found in most Dell gaming
+laptops and controls various special features.
+
+Before the launch of M-Series laptops (~2018), the "WMAX" device controlled
+basic RGB lighting, deep sleep mode, HDMI mode and amplifier status.
+
+Later, this device was completely repurpused. Now it mostly deals with thermal
+profiles, sensor monitoring and overclocking. This interface is named "AWCC" and
+is known to be used by the AWCC OEM application to control these features.
+
+The alienware-wmi driver controls both interfaces.
+
+AWCC Interface
+==============
+
+WMI device Documentation: Documentation/wmi/devices/alienware-wmi.rst
+
+Supported devices
+-----------------
+
+- Alienware M-Series laptops
+- Alienware X-Series laptops
+- Alienware Aurora Desktops
+- Dell G-Series laptops
+
+If you believe your device supports the AWCC interface and you don't have any of
+the features described in this document, try the following alienware-wmi module
+parameters:
+
+- ``force_platform_profile=1``: Forces probing for platform profile support
+- ``force_hwmon=1``: Forces probing for HWMON support
+
+If the module loads successfully with these parameters, consider submitting a
+patch adding your model to the ``awcc_dmi_table`` located in
+``drivers/platform/x86/dell/alienware-wmi-wmax.c`` or contacting the maintainer
+for further guidance.
+
+Status
+------
+
+The following features are currently supported:
+
+- :ref:`Platform Profile <platform-profile>`:
+
+  - Thermal profile control
+
+  - G-Mode toggling
+
+- :ref:`HWMON <hwmon>`:
+
+  - Sensor monitoring
+
+  - Manual fan control
+
+.. _platform-profile:
+
+Platform Profile
+----------------
+
+The AWCC interface exposes various firmware defined thermal profiles. We expose
+these profiles to user-space through the Platform Profile class interface.
+Refer to
+:ref:`sysfs-class-platform-profile <abi_file_testing_sysfs_class_platform_profile>`
+for more information.
+
+The name of the platform-profile class device exported by this driver is
+"alienware-wmi" and it's path can be found with:
+
+::
+
+ grep -l "alienware-wmi" /sys/class/platform-profile/platform-profile-*/name | sed 's|/[^/]*$||'
+
+If the device supports G-Mode, it is also toggled when selecting the
+``performance`` profile.
+
+.. note::
+   You may set the ``force_gmode`` module parameter to always try to toggle this
+   feature, without checking if your model supports it.
+
+.. _hwmon:
+
+HWMON
+-----
+
+The AWCC interface also supports sensor monitoring and manual fan control. Both
+of these features are exposed to user-space through the HWMON interface.
+
+The name of the hwmon class device exported by this driver is "alienware_wmi"
+and it's path can be found with:
+
+::
+
+ grep -l "alienware_wmi" /sys/class/hwmon/hwmon*/name | sed 's|/[^/]*$||'
+
+Sensor monitoring is done through the standard HWMON interface. Refer to
+:ref:`sysfs-class-hwmon <abi_file_testing_sysfs_class_hwmon>` for more
+information.
+
+Manual fan control on the other hand, is not exposed directly by the AWCC
+interface. Instead it let's us control a fan `boost` value. This `boost` value
+has the following aproximate behavior over the fan pwm:
+
+::
+
+ pwm = pwm_base + (fan_boost / 255) * (pwm_max - pwm_base)
+
+Due to the above behavior, we expose the fan `boost` control to user-space
+through the following, custom hwmon sysfs attribute:
+
+=============================== ======= =======================================
+Name				Perm	Description
+=============================== ======= =======================================
+fan[1-4]_boost			RW	Fan boost value.
+
+					Integer value between 0 and 255
+=============================== ======= =======================================
+
+.. note::
+   In some devices, manual fan control only works reliably, if the ``custom``
+   platform profile is selected.
diff --git a/Documentation/admin-guide/laptops/index.rst b/Documentation/admin-guide/laptops/index.rst
index e71c8984c23e43ca7cd6373b88803354dff6bc60..db842b629303c1bcf02646204d51938f9bd4043e 100644
--- a/Documentation/admin-guide/laptops/index.rst
+++ b/Documentation/admin-guide/laptops/index.rst
@@ -7,6 +7,7 @@  Laptop Drivers
 .. toctree::
    :maxdepth: 1
 
+   alienware-wmi
    asus-laptop
    disk-shock-protection
    laptop-mode
diff --git a/MAINTAINERS b/MAINTAINERS
index 1afd30d00aecf9a48f8c71e156affd5f329539bd..c609bc321b8dc3ab0e8d92b04e42483be8cc171c 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -796,6 +796,7 @@  M:	Kurt Borja <kuurtb@gmail.com>
 L:	platform-driver-x86@vger.kernel.org
 L:	Dell.Client.Kernel@dell.com
 S:	Maintained
+F:	Documentation/admin-guide/laptops/alienware-wmi.rst
 F:	Documentation/wmi/devices/alienware-wmi.rst
 F:	drivers/platform/x86/dell/alienware-wmi*