Unverified Commit df6061c2 authored by Kurt Borja's avatar Kurt Borja Committed by Ilpo Järvinen
Browse files

Documentation: wmi: alienware-wmi: Add GPIO control documentation 



Add documentation for the GPIO control methods.

Reviewed-by: default avatarArmin Wolf <W_Armin@gmx.de>
Signed-off-by: default avatarKurt Borja <kuurtb@gmail.com>
Link: https://lore.kernel.org/r/20250505-awcc-gpio-v4-2-edda44c3a0dc@gmail.com


Reviewed-by: default avatarIlpo Järvinen <ilpo.jarvinen@linux.intel.com>
Signed-off-by: default avatarIlpo Järvinen <ilpo.jarvinen@linux.intel.com>
parent aee5cf93

Documentation/wmi/devices/alienware-wmi.rst

+78 −4
Original line number Diff line number Diff line
@@ -231,6 +231,74 @@ 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 control Methods

====================



Alienware and Dell G Series devices with the AWCC interface usually have an

embedded STM32 RGB lighting controller with USB/HID capabilities. It's vendor ID

is ``187c`` while it's product ID may vary from model to model.



The control of two GPIO pins of this MCU is exposed as WMI methods for debugging

purposes.



+--------------+--------------------------------------------------------------+

| Pin          | Description                                                  |

+==============+===============================+==============================+

| 0            | Device Firmware Update (DFU)  | **HIGH**: Enables DFU mode   |

|              | mode pin.                     | on next MCU boot.            |

|              |                               +------------------------------+

|              |                               | **LOW**: Disables DFU mode   |

|              |                               | on next MCU boot.            |

+--------------+-------------------------------+------------------------------+

| 1            | Negative Reset (NRST) pin.    | **HIGH**: MCU is ON.         |

|              |                               |                              |

|              |                               +------------------------------+

|              |                               | **LOW**: MCU is OFF.         |

|              |                               |                              |

+--------------+-------------------------------+------------------------------+



See :ref:`acknowledgements` for more information on this MCU.



.. note::

   Some GPIO control methods break the usual argument structure and take a

   **Pin number** instead of an operation on the first byte.



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

------------------------------------------------------------------



+--------------------+------------------------------------+--------------------+

| Operation (Byte 0) | Description                        | Arguments          |

+====================+====================================+====================+

| Pin number         | Set the pin status                 | - Byte 1: Pin      |

|                    |                                    |   status           |

+--------------------+------------------------------------+--------------------+



WMI method ReadTotalofGPIOs([out] uint32 argr)

----------------------------------------------



+--------------------+------------------------------------+--------------------+

| Operation (Byte 0) | Description                        | Arguments          |

+====================+====================================+====================+

| N/A                | Get the total number of GPIOs      | - None             |

+--------------------+------------------------------------+--------------------+



.. note::

   Due to how WMI methods are implemented on the firmware level, this method

   requires a dummy uint32 input argument when invoked.



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

------------------------------------------------------------------



+--------------------+------------------------------------+--------------------+

| Operation (Byte 0) | Description                        | Arguments          |

+====================+====================================+====================+

| Pin number         | Get the pin status                 | - None             |

+--------------------+------------------------------------+--------------------+



.. note::

   There known firmware bug in some laptops where reading the status of a pin

   also flips it.



Other information Methods

=========================
@@ -239,10 +307,16 @@ WMI method ReadChassisColor([out] uint32 argr) 


Returns the chassis color internal ID.



.. _acknowledgements:



Acknowledgements

================



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.
 
Kudos to



* `AlexIII <https://github.com/AlexIII/tcc-g15>`_

* `T-Troll <https://github.com/T-Troll/alienfx-tools/>`_

* `Gabriel Marcano <https://gabriel.marcanobrady.family/blog/2024/12/16/dell-g5-5505-se-acpi-or-figuring-out-how-to-reset-the-rgb-controller/>`_



for documenting and testing some of this device's functionality, making it

possible to generalize this driver.