diff options
Diffstat (limited to 'Documentation/wmi')
| -rw-r--r-- | Documentation/wmi/acpi-interface.rst | 15 | ||||
| -rw-r--r-- | Documentation/wmi/devices/alienware-wmi.rst | 322 | ||||
| -rw-r--r-- | Documentation/wmi/devices/dell-wmi-ddv.rst | 50 | ||||
| -rw-r--r-- | Documentation/wmi/devices/msi-wmi-platform.rst | 198 | ||||
| -rw-r--r-- | Documentation/wmi/driver-development-guide.rst | 191 | ||||
| -rw-r--r-- | Documentation/wmi/index.rst | 1 |
6 files changed, 759 insertions, 18 deletions
diff --git a/Documentation/wmi/acpi-interface.rst b/Documentation/wmi/acpi-interface.rst index 06fb7fcf4413..1ef003b033bf 100644 --- a/Documentation/wmi/acpi-interface.rst +++ b/Documentation/wmi/acpi-interface.rst @@ -36,7 +36,7 @@ Offset Size (in bytes) Content The WMI object flags control whether the method or notification ID is used: -- 0x1: Data block usage is expensive and must be explicitly enabled/disabled. +- 0x1: Data block is expensive to collect. - 0x2: Data block contains WMI methods. - 0x4: Data block contains ASCIZ string. - 0x8: Data block describes a WMI event, use notification ID instead @@ -83,11 +83,18 @@ event as hexadecimal value. Their first parameter is an integer with a value of 0 if the WMI event should be disabled, other values will enable the WMI event. +Those ACPI methods are always called even for WMI events not registered as +being expensive to collect to match the behavior of the Windows driver. + WCxx ACPI methods ----------------- -Similar to the ``WExx`` ACPI methods, except that it controls data collection -instead of events and thus the last two characters of the ACPI method name are -the method ID of the data block to enable/disable. +Similar to the ``WExx`` ACPI methods, except that instead of WMI events it controls +data collection of data blocks registered as being expensive to collect. Thus the +last two characters of the ACPI method name are the method ID of the data block +to enable/disable. + +Those ACPI methods are also called before setting data blocks to match the +behavior of the Windows driver. _WED ACPI method ---------------- diff --git a/Documentation/wmi/devices/alienware-wmi.rst b/Documentation/wmi/devices/alienware-wmi.rst new file mode 100644 index 000000000000..1d9d43e2e314 --- /dev/null +++ b/Documentation/wmi/devices/alienware-wmi.rst @@ -0,0 +1,322 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +============================================== +Dell AWCC WMI interface driver (alienware-wmi) +============================================== + +Introduction +============ + +The WMI device WMAX has been implemented for many Alienware and Dell's G-Series +models. Throughout these models, two implementations have been identified. The +first one, used by older systems, deals with HDMI, brightness, RGB, amplifier +and deep sleep control. The second one used by newer systems deals primarily +with thermal control and overclocking. + +It is suspected that the latter is used by Alienware Command Center (AWCC) to +manage manufacturer predefined thermal profiles. The alienware-wmi driver +exposes Thermal_Information and Thermal_Control methods through the Platform +Profile API to mimic AWCC's behavior. + +This newer interface, named AWCCMethodFunction has been reverse engineered, as +Dell has not provided any official documentation. We will try to describe to the +best of our ability its discovered inner workings. + +.. note:: + The following method description may be incomplete and some operations have + different implementations between devices. + +WMI interface description +------------------------- + +The WMI interface description can be decoded from the embedded binary MOF (bmof) +data using the `bmfdec <https://github.com/pali/bmfdec>`_ utility: + +:: + + [WMI, Dynamic, Provider("WmiProv"), Locale("MS\\0x409"), Description("WMI Function"), guid("{A70591CE-A997-11DA-B012-B622A1EF5492}")] + class AWCCWmiMethodFunction { + [key, read] string InstanceName; + [read] boolean Active; + + [WmiMethodId(13), Implemented, read, write, Description("Return Overclocking Report.")] void Return_OverclockingReport([out] uint32 argr); + [WmiMethodId(14), Implemented, read, write, Description("Set OCUIBIOS Control.")] void Set_OCUIBIOSControl([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(15), Implemented, read, write, Description("Clear OC FailSafe Flag.")] void Clear_OCFailSafeFlag([out] uint32 argr); + [WmiMethodId(19), Implemented, read, write, Description("Get Fan Sensors.")] void GetFanSensors([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(20), Implemented, read, write, Description("Thermal Information.")] void Thermal_Information([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(21), Implemented, read, write, Description("Thermal Control.")] void Thermal_Control([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(23), Implemented, read, write, Description("MemoryOCControl.")] void MemoryOCControl([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(26), Implemented, read, write, Description("System Information.")] void SystemInformation([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(28), Implemented, read, write, Description("Power Information.")] void PowerInformation([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(32), Implemented, read, write, Description("FW Update GPIO toggle.")] void FWUpdateGPIOtoggle([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(33), Implemented, read, write, Description("Read Total of GPIOs.")] void ReadTotalofGPIOs([out] uint32 argr); + [WmiMethodId(34), Implemented, read, write, Description("Read GPIO pin Status.")] void ReadGPIOpPinStatus([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(35), Implemented, read, write, Description("Read Chassis Color.")] void ReadChassisColor([out] uint32 argr); + [WmiMethodId(36), Implemented, read, write, Description("Read Platform Properties.")] void ReadPlatformProperties([out] uint32 argr); + [WmiMethodId(37), Implemented, read, write, Description("Game Shift Status.")] void GameShiftStatus([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(128), Implemented, read, write, Description("Caldera SW installation.")] void CalderaSWInstallation([out] uint32 argr); + [WmiMethodId(129), Implemented, read, write, Description("Caldera SW is released.")] void CalderaSWReleased([out] uint32 argr); + [WmiMethodId(130), Implemented, read, write, Description("Caldera Connection Status.")] void CalderaConnectionStatus([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(131), Implemented, read, write, Description("Surprise Unplugged Flag Status.")] void SurpriseUnpluggedFlagStatus([out] uint32 argr); + [WmiMethodId(132), Implemented, read, write, Description("Clear Surprise Unplugged Flag.")] void ClearSurpriseUnpluggedFlag([out] uint32 argr); + [WmiMethodId(133), Implemented, read, write, Description("Cancel Undock Request.")] void CancelUndockRequest([out] uint32 argr); + [WmiMethodId(135), Implemented, read, write, Description("Devices in Caldera.")] void DevicesInCaldera([in] uint32 arg2, [out] uint32 argr); + [WmiMethodId(136), Implemented, read, write, Description("Notify BIOS for SW ready to disconnect Caldera.")] void NotifyBIOSForSWReadyToDisconnectCaldera([out] uint32 argr); + [WmiMethodId(160), Implemented, read, write, Description("Tobii SW installation.")] void TobiiSWinstallation([out] uint32 argr); + [WmiMethodId(161), Implemented, read, write, Description("Tobii SW Released.")] void TobiiSWReleased([out] uint32 argr); + [WmiMethodId(162), Implemented, read, write, Description("Tobii Camera Power Reset.")] void TobiiCameraPowerReset([out] uint32 argr); + [WmiMethodId(163), Implemented, read, write, Description("Tobii Camera Power On.")] void TobiiCameraPowerOn([out] uint32 argr); + [WmiMethodId(164), Implemented, read, write, Description("Tobii Camera Power Off.")] void TobiiCameraPowerOff([out] uint32 argr); + }; + +Methods not described in the following document have unknown behavior. + +Argument Structure +------------------ + +All input arguments have type **uint32** and their structure is very similar +between methods. Usually, the first byte corresponds to a specific *operation* +the method performs, and the subsequent bytes correspond to *arguments* passed +to this *operation*. For example, if an operation has code 0x01 and requires an +ID 0xA0, the argument you would pass to the method is 0xA001. + + +Thermal Methods +=============== + +WMI method GetFanSensors([in] uint32 arg2, [out] uint32 argr) +------------------------------------------------------------- + ++--------------------+------------------------------------+--------------------+ +| Operation (Byte 0) | Description | Arguments | ++====================+====================================+====================+ +| 0x01 | Get the number of temperature | - Byte 1: Fan ID | +| | sensors related with a fan ID | | ++--------------------+------------------------------------+--------------------+ +| 0x02 | Get the temperature sensor IDs | - Byte 1: Fan ID | +| | related to a fan sensor ID | - Byte 2: Index | ++--------------------+------------------------------------+--------------------+ + +WMI method Thermal_Information([in] uint32 arg2, [out] uint32 argr) +------------------------------------------------------------------- + ++--------------------+------------------------------------+--------------------+ +| Operation (Byte 0) | Description | Arguments | ++====================+====================================+====================+ +| 0x01 | Unknown. | - None | ++--------------------+------------------------------------+--------------------+ +| 0x02 | Get system description number with | - None | +| | the following structure: | | +| | | | +| | - Byte 0: Number of fans | | +| | - Byte 1: Number of temperature | | +| | sensors | | +| | - Byte 2: Unknown | | +| | - Byte 3: Number of thermal | | +| | profiles | | ++--------------------+------------------------------------+--------------------+ +| 0x03 | List an ID or resource at a given | - Byte 1: Index | +| | index. Fan IDs, temperature IDs, | | +| | unknown IDs and thermal profile | | +| | IDs are listed in that exact | | +| | order. | | +| | | | +| | Operation 0x02 is used to know | | +| | which indexes map to which | | +| | resources. | | +| | | | +| | **Returns:** ID at a given index | | ++--------------------+------------------------------------+--------------------+ +| 0x04 | Get the current temperature for a | - Byte 1: Sensor | +| | given temperature sensor. | ID | ++--------------------+------------------------------------+--------------------+ +| 0x05 | Get the current RPM for a given | - Byte 1: Fan ID | +| | fan. | | ++--------------------+------------------------------------+--------------------+ +| 0x06 | Get fan speed percentage. (not | - Byte 1: Fan ID | +| | implemented in every model) | | ++--------------------+------------------------------------+--------------------+ +| 0x07 | Unknown. | - Unknown | ++--------------------+------------------------------------+--------------------+ +| 0x08 | Get minimum RPM for a given FAN | - Byte 1: Fan ID | +| | ID. | | ++--------------------+------------------------------------+--------------------+ +| 0x09 | Get maximum RPM for a given FAN | - Byte 1: Fan ID | +| | ID. | | ++--------------------+------------------------------------+--------------------+ +| 0x0A | Get balanced thermal profile ID. | - None | ++--------------------+------------------------------------+--------------------+ +| 0x0B | Get current thermal profile ID. | - None | ++--------------------+------------------------------------+--------------------+ +| 0x0C | Get current `boost` value for a | - Byte 1: Fan ID | +| | given fan ID. | | ++--------------------+------------------------------------+--------------------+ + +WMI method Thermal_Control([in] uint32 arg2, [out] uint32 argr) +--------------------------------------------------------------- + ++--------------------+------------------------------------+--------------------+ +| Operation (Byte 0) | Description | Arguments | ++====================+====================================+====================+ +| 0x01 | Activate a given thermal profile. | - Byte 1: Thermal | +| | | profile ID | ++--------------------+------------------------------------+--------------------+ +| 0x02 | Set a `boost` value for a given | - Byte 1: Fan ID | +| | fan ID. | - Byte 2: Boost | ++--------------------+------------------------------------+--------------------+ + +These are the known thermal profile codes: + ++------------------------------+----------+------+ +| Thermal Profile | Type | ID | ++==============================+==========+======+ +| Custom | Special | 0x00 | ++------------------------------+----------+------+ +| G-Mode | Special | 0xAB | ++------------------------------+----------+------+ +| Quiet | Legacy | 0x96 | ++------------------------------+----------+------+ +| Balanced | Legacy | 0x97 | ++------------------------------+----------+------+ +| Balanced Performance | Legacy | 0x98 | ++------------------------------+----------+------+ +| Performance | Legacy | 0x99 | ++------------------------------+----------+------+ +| Balanced | USTT | 0xA0 | ++------------------------------+----------+------+ +| Balanced Performance | USTT | 0xA1 | ++------------------------------+----------+------+ +| Cool | USTT | 0xA2 | ++------------------------------+----------+------+ +| Quiet | USTT | 0xA3 | ++------------------------------+----------+------+ +| Performance | USTT | 0xA4 | ++------------------------------+----------+------+ +| Low Power | USTT | 0xA5 | ++------------------------------+----------+------+ + +If a model supports the User Selectable Thermal Tables (USTT) profiles, it will +not support the Legacy profiles and vice-versa. + +Every model supports the CUSTOM (0x00) thermal profile. GMODE replaces +PERFORMANCE in G-Series laptops. + +WMI method GameShiftStatus([in] uint32 arg2, [out] uint32 argr) +--------------------------------------------------------------- + ++--------------------+------------------------------------+--------------------+ +| Operation (Byte 0) | Description | Arguments | ++====================+====================================+====================+ +| 0x01 | Toggle *Game Shift*. | - None | ++--------------------+------------------------------------+--------------------+ +| 0x02 | Get *Game Shift* status. | - None | ++--------------------+------------------------------------+--------------------+ + +Game Shift Status does not change the fan speed profile but it could be some +sort of CPU/GPU power profile. Benchmarks have not been done. + +This method is only present on Dell's G-Series laptops and it's implementation +implies GMODE thermal profile is available, even if operation 0x03 of +Thermal_Information does not list it. + +G-key on Dell's G-Series laptops also changes Game Shift status, so both are +directly related. + +Overclocking Methods +==================== + +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 +========================= + +WMI method ReadChassisColor([out] uint32 argr) +---------------------------------------------- + +Returns the chassis color internal ID. + +.. _acknowledgements: + +Acknowledgements +================ + +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. diff --git a/Documentation/wmi/devices/dell-wmi-ddv.rst b/Documentation/wmi/devices/dell-wmi-ddv.rst index 2fcdfcf03327..109d4c5c922e 100644 --- a/Documentation/wmi/devices/dell-wmi-ddv.rst +++ b/Documentation/wmi/devices/dell-wmi-ddv.rst @@ -8,7 +8,7 @@ Introduction ============ Many Dell notebooks made after ~2020 support a WMI-based interface for -retrieving various system data like battery temperature, ePPID, diagostic data +retrieving various system data like battery temperature, ePPID, diagnostic data and fan/thermal sensor data. This interface is likely used by the `Dell Data Vault` software on Windows, @@ -118,9 +118,6 @@ The date is encoded in the following manner: - bits 5 to 8 contain the manufacture month. - bits 9 to 15 contain the manufacture year biased by 1980. -.. note:: - The data format needs to be verified on more machines. - WMI method BatterySerialNumber() -------------------------------- @@ -153,7 +150,40 @@ Returns the voltage flow of the battery in mV as an u16. WMI method BatteryManufactureAccess() ------------------------------------- -Returns a manufacture-defined value as an u16. +Returns the health status of the battery as a u16. +The health status encoded in the following manner: + + - the third nibble contains the general failure mode + - the fourth nibble contains the specific failure code + +Valid failure modes are: + + - permanent failure (``0x9``) + - overheat failure (``0xa``) + - overcurrent failure (``0xb``) + +All other failure modes are to be considered normal. + +The following failure codes are valid for a permanent failure: + + - fuse blown (``0x0``) + - cell imbalance (``0x1``) + - overvoltage (``0x2``) + - fet failure (``0x3``) + +The last two bits of the failure code are to be ignored when the battery +signals a permanent failure. + +The following failure codes a valid for a overheat failure: + + - overheat at start of charging (``0x5``) + - overheat during charging (``0x7``) + - overheat during discharging (``0x8``) + +The following failure codes are valid for a overcurrent failure: + + - overcurrent during charging (``0x6``) + - overcurrent during discharging (``0xb``) WMI method BatteryRelativeStateOfCharge() ----------------------------------------- @@ -260,14 +290,6 @@ Some machines like the Dell Inspiron 3505 only support a single battery and thus ignore the battery index. Because of this the driver depends on the ACPI battery hook mechanism to discover batteries. -.. note:: - The ACPI battery matching algorithm currently used inside the driver is - outdated and does not match the algorithm described above. The reasons for - this are differences in the handling of the ToHexString() ACPI opcode between - Linux and Windows, which distorts the serial number of ACPI batteries on many - machines. Until this issue is resolved, the driver cannot use the above - algorithm. - Reverse-Engineering the DDV WMI interface ========================================= @@ -277,7 +299,7 @@ Reverse-Engineering the DDV WMI interface 4. Try to deduce the meaning of a certain WMI method by comparing the control flow with other ACPI methods (_BIX or _BIF for battery related methods for example). -5. Use the built-in UEFI diagostics to view sensor types/values for fan/thermal +5. Use the built-in UEFI diagnostics to view sensor types/values for fan/thermal related methods (sometimes overwriting static ACPI data fields can be used to test different sensor type values, since on some machines this data is not reinitialized upon a warm reset). diff --git a/Documentation/wmi/devices/msi-wmi-platform.rst b/Documentation/wmi/devices/msi-wmi-platform.rst new file mode 100644 index 000000000000..73197b31926a --- /dev/null +++ b/Documentation/wmi/devices/msi-wmi-platform.rst @@ -0,0 +1,198 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +=================================================== +MSI WMI Platform Features driver (msi-wmi-platform) +=================================================== + +Introduction +============ + +Many MSI notebooks support various features like reading fan sensors. This features are controlled +by the embedded controller, with the ACPI firmware exposing a standard ACPI WMI interface on top +of the embedded controller interface. + +WMI interface description +========================= + +The WMI interface description can be decoded from the embedded binary MOF (bmof) +data using the `bmfdec <https://github.com/pali/bmfdec>`_ utility: + +:: + + [WMI, Locale("MS\0x409"), + Description("This class contains the definition of the package used in other classes"), + guid("{ABBC0F60-8EA1-11d1-00A0-C90629100000}")] + class Package { + [WmiDataId(1), read, write, Description("16 bytes of data")] uint8 Bytes[16]; + }; + + [WMI, Locale("MS\0x409"), + Description("This class contains the definition of the package used in other classes"), + guid("{ABBC0F63-8EA1-11d1-00A0-C90629100000}")] + class Package_32 { + [WmiDataId(1), read, write, Description("32 bytes of data")] uint8 Bytes[32]; + }; + + [WMI, Dynamic, Provider("WmiProv"), Locale("MS\0x409"), + Description("Class used to operate methods on a package"), + guid("{ABBC0F6E-8EA1-11d1-00A0-C90629100000}")] + class MSI_ACPI { + [key, read] string InstanceName; + [read] boolean Active; + + [WmiMethodId(1), Implemented, read, write, Description("Return the contents of a package")] + void GetPackage([out, id(0)] Package Data); + + [WmiMethodId(2), Implemented, read, write, Description("Set the contents of a package")] + void SetPackage([in, id(0)] Package Data); + + [WmiMethodId(3), Implemented, read, write, Description("Return the contents of a package")] + void Get_EC([out, id(0)] Package_32 Data); + + [WmiMethodId(4), Implemented, read, write, Description("Set the contents of a package")] + void Set_EC([in, id(0)] Package_32 Data); + + [WmiMethodId(5), Implemented, read, write, Description("Return the contents of a package")] + void Get_BIOS([in, out, id(0)] Package_32 Data); + + [WmiMethodId(6), Implemented, read, write, Description("Set the contents of a package")] + void Set_BIOS([in, out, id(0)] Package_32 Data); + + [WmiMethodId(7), Implemented, read, write, Description("Return the contents of a package")] + void Get_SMBUS([in, out, id(0)] Package_32 Data); + + [WmiMethodId(8), Implemented, read, write, Description("Set the contents of a package")] + void Set_SMBUS([in, out, id(0)] Package_32 Data); + + [WmiMethodId(9), Implemented, read, write, Description("Return the contents of a package")] + void Get_MasterBattery([in, out, id(0)] Package_32 Data); + + [WmiMethodId(10), Implemented, read, write, Description("Set the contents of a package")] + void Set_MasterBattery([in, out, id(0)] Package_32 Data); + + [WmiMethodId(11), Implemented, read, write, Description("Return the contents of a package")] + void Get_SlaveBattery([in, out, id(0)] Package_32 Data); + + [WmiMethodId(12), Implemented, read, write, Description("Set the contents of a package")] + void Set_SlaveBattery([in, out, id(0)] Package_32 Data); + + [WmiMethodId(13), Implemented, read, write, Description("Return the contents of a package")] + void Get_Temperature([in, out, id(0)] Package_32 Data); + + [WmiMethodId(14), Implemented, read, write, Description("Set the contents of a package")] + void Set_Temperature([in, out, id(0)] Package_32 Data); + + [WmiMethodId(15), Implemented, read, write, Description("Return the contents of a package")] + void Get_Thermal([in, out, id(0)] Package_32 Data); + + [WmiMethodId(16), Implemented, read, write, Description("Set the contents of a package")] + void Set_Thermal([in, out, id(0)] Package_32 Data); + + [WmiMethodId(17), Implemented, read, write, Description("Return the contents of a package")] + void Get_Fan([in, out, id(0)] Package_32 Data); + + [WmiMethodId(18), Implemented, read, write, Description("Set the contents of a package")] + void Set_Fan([in, out, id(0)] Package_32 Data); + + [WmiMethodId(19), Implemented, read, write, Description("Return the contents of a package")] + void Get_Device([in, out, id(0)] Package_32 Data); + + [WmiMethodId(20), Implemented, read, write, Description("Set the contents of a package")] + void Set_Device([in, out, id(0)] Package_32 Data); + + [WmiMethodId(21), Implemented, read, write, Description("Return the contents of a package")] + void Get_Power([in, out, id(0)] Package_32 Data); + + [WmiMethodId(22), Implemented, read, write, Description("Set the contents of a package")] + void Set_Power([in, out, id(0)] Package_32 Data); + + [WmiMethodId(23), Implemented, read, write, Description("Return the contents of a package")] + void Get_Debug([in, out, id(0)] Package_32 Data); + + [WmiMethodId(24), Implemented, read, write, Description("Set the contents of a package")] + void Set_Debug([in, out, id(0)] Package_32 Data); + + [WmiMethodId(25), Implemented, read, write, Description("Return the contents of a package")] + void Get_AP([in, out, id(0)] Package_32 Data); + + [WmiMethodId(26), Implemented, read, write, Description("Set the contents of a package")] + void Set_AP([in, out, id(0)] Package_32 Data); + + [WmiMethodId(27), Implemented, read, write, Description("Return the contents of a package")] + void Get_Data([in, out, id(0)] Package_32 Data); + + [WmiMethodId(28), Implemented, read, write, Description("Set the contents of a package")] + void Set_Data([in, out, id(0)] Package_32 Data); + + [WmiMethodId(29), Implemented, read, write, Description("Return the contents of a package")] + void Get_WMI([out, id(0)] Package_32 Data); + }; + +Due to a peculiarity in how Windows handles the ``CreateByteField()`` ACPI operator (errors only +happen when a invalid byte field is ultimately accessed), all methods require a 32 byte input +buffer, even if the Binary MOF says otherwise. + +The input buffer contains a single byte to select the subfeature to be accessed and 31 bytes of +input data, the meaning of which depends on the subfeature being accessed. + +The output buffer contains a single byte which signals success or failure (``0x00`` on failure) +and 31 bytes of output data, the meaning if which depends on the subfeature being accessed. + +.. note:: + The ACPI control method responsible for handling the WMI method calls is not thread-safe. + This is a firmware bug that needs to be handled inside the driver itself. + +WMI method Get_EC() +------------------- + +Returns embedded controller information, the selected subfeature does not matter. The output +data contains a flag byte and a 28 byte controller firmware version string. + +The first 4 bits of the flag byte contain the minor version of the embedded controller interface, +with the next 2 bits containing the major version of the embedded controller interface. + +The 7th bit signals if the embedded controller page changed (exact meaning is unknown), and the +last bit signals if the platform is a Tigerlake platform. + +The MSI software seems to only use this interface when the last bit is set. + +WMI method Get_Fan() +-------------------- + +Fan speed sensors can be accessed by selecting subfeature ``0x00``. The output data contains +up to four 16-bit fan speed readings in big-endian format. Most machines do not support all +four fan speed sensors, so the remaining reading are hardcoded to ``0x0000``. + +The fan RPM readings can be calculated with the following formula: + + RPM = 480000 / <fan speed reading> + +If the fan speed reading is zero, then the fan RPM is zero too. + +WMI method Get_WMI() +-------------------- + +Returns the version of the ACPI WMI interface, the selected subfeature does not matter. +The output data contains two bytes, the first one contains the major version and the last one +contains the minor revision of the ACPI WMI interface. + +The MSI software seems to only use this interface when the major version is greater than two. + +Reverse-Engineering the MSI WMI Platform interface +================================================== + +.. warning:: Randomly poking the embedded controller interface can potentially cause damage + to the machine and other unwanted side effects, please be careful. + +The underlying embedded controller interface is used by the ``msi-ec`` driver, and it seems +that many methods just copy a part of the embedded controller memory into the output buffer. + +This means that the remaining WMI methods can be reverse-engineered by looking which part of +the embedded controller memory is accessed by the ACPI AML code. The driver also supports a +debugfs interface for directly executing WMI methods. Additionally, any safety checks regarding +unsupported hardware can be disabled by loading the module with ``force=true``. + +More information about the MSI embedded controller interface can be found at the +`msi-ec project <https://github.com/BeardOverflow/msi-ec>`_. + +Special thanks go to github user `glpnk` for showing how to decode the fan speed readings. diff --git a/Documentation/wmi/driver-development-guide.rst b/Documentation/wmi/driver-development-guide.rst new file mode 100644 index 000000000000..99ef21fc1c1e --- /dev/null +++ b/Documentation/wmi/driver-development-guide.rst @@ -0,0 +1,191 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +============================ +WMI driver development guide +============================ + +The WMI subsystem provides a rich driver API for implementing WMI drivers, +documented at Documentation/driver-api/wmi.rst. This document will serve +as an introductory guide for WMI driver writers using this API. It is supposed +to be a successor to the original LWN article [1]_ which deals with WMI drivers +using the deprecated GUID-based WMI interface. + +Obtaining WMI device information +-------------------------------- + +Before developing an WMI driver, information about the WMI device in question +must be obtained. The `lswmi <https://pypi.org/project/lswmi>`_ utility can be +used to extract detailed WMI device information using the following command: + +:: + + lswmi -V + +The resulting output will contain information about all WMI devices available on +a given machine, plus some extra information. + +In order to find out more about the interface used to communicate with a WMI device, +the `bmfdec <https://github.com/pali/bmfdec>`_ utilities can be used to decode +the Binary MOF (Managed Object Format) information used to describe WMI devices. +The ``wmi-bmof`` driver exposes this information to userspace, see +Documentation/wmi/devices/wmi-bmof.rst. + +In order to retrieve the decoded Binary MOF information, use the following command (requires root): + +:: + + ./bmf2mof /sys/bus/wmi/devices/05901221-D566-11D1-B2F0-00A0C9062910[-X]/bmof + +Sometimes, looking at the disassembled ACPI tables used to describe the WMI device +helps in understanding how the WMI device is supposed to work. The path of the ACPI +method associated with a given WMI device can be retrieved using the ``lswmi`` utility +as mentioned above. + +If you are attempting to port a driver to Linux and are working on a Windows +system, `WMIExplorer <https://github.com/vinaypamnani/wmie2>`_ can be useful +for inspecting available WMI methods and invoking them directly. + +Basic WMI driver structure +-------------------------- + +The basic WMI driver is build around the struct wmi_driver, which is then bound +to matching WMI devices using a struct wmi_device_id table: + +:: + + static const struct wmi_device_id foo_id_table[] = { + { "936DA01F-9ABD-4D9D-80C7-02AF85C822A8", NULL }, + { } + }; + MODULE_DEVICE_TABLE(wmi, foo_id_table); + + static struct wmi_driver foo_driver = { + .driver = { + .name = "foo", + .probe_type = PROBE_PREFER_ASYNCHRONOUS, /* recommended */ + .pm = pm_sleep_ptr(&foo_dev_pm_ops), /* optional */ + }, + .id_table = foo_id_table, + .probe = foo_probe, + .remove = foo_remove, /* optional, devres is preferred */ + .shutdown = foo_shutdown, /* optional, called during shutdown */ + .notify = foo_notify, /* optional, for event handling */ + .no_notify_data = true, /* optional, enables events containing no additional data */ + .no_singleton = true, /* required for new WMI drivers */ + }; + module_wmi_driver(foo_driver); + +The probe() callback is called when the WMI driver is bound to a matching WMI device. Allocating +driver-specific data structures and initialising interfaces to other kernel subsystems should +normally be done in this function. + +The remove() callback is then called when the WMI driver is unbound from a WMI device. In order +to unregister interfaces to other kernel subsystems and release resources, devres should be used. +This simplifies error handling during probe and often allows to omit this callback entirely, see +Documentation/driver-api/driver-model/devres.rst for details. + +The shutdown() callback is called during shutdown, reboot or kexec. Its sole purpose is to disable +the WMI device and put it in a well-known state for the WMI driver to pick up later after reboot +or kexec. Most WMI drivers need no special shutdown handling and can thus omit this callback. + +Please note that new WMI drivers are required to be able to be instantiated multiple times, +and are forbidden from using any deprecated GUID-based WMI functions. This means that the +WMI driver should be prepared for the scenario that multiple matching WMI devices are present +on a given machine. + +Because of this, WMI drivers should use the state container design pattern as described in +Documentation/driver-api/driver-model/design-patterns.rst. + +.. warning:: Using both GUID-based and non-GUID-based functions for querying WMI data blocks and + handling WMI events simultaneously on the same device is guaranteed to corrupt the + WMI device state and might lead to erratic behaviour. + +WMI method drivers +------------------ + +WMI drivers can call WMI device methods using wmidev_evaluate_method(), the +structure of the ACPI buffer passed to this function is device-specific and usually +needs some tinkering to get right. Looking at the ACPI tables containing the WMI +device usually helps here. The method id and instance number passed to this function +are also device-specific, looking at the decoded Binary MOF is usually enough to +find the right values. + +The maximum instance number can be retrieved during runtime using wmidev_instance_count(). + +Take a look at drivers/platform/x86/inspur_platform_profile.c for an example WMI method driver. + +WMI data block drivers +---------------------- + +WMI drivers can query WMI device data blocks using wmidev_block_query(), the +structure of the returned ACPI object is again device-specific. Some WMI devices +also allow for setting data blocks using wmidev_block_set(). + +The maximum instance number can also be retrieved using wmidev_instance_count(). + +Take a look at drivers/platform/x86/intel/wmi/sbl-fw-update.c for an example +WMI data block driver. + +WMI event drivers +----------------- + +WMI drivers can receive WMI events via the notify() callback inside the struct wmi_driver. +The WMI subsystem will then take care of setting up the WMI event accordingly. Please note that +the structure of the ACPI object passed to this callback is device-specific, and freeing the +ACPI object is being done by the WMI subsystem, not the driver. + +The WMI driver core will take care that the notify() callback will only be called after +the probe() callback has been called, and that no events are being received by the driver +right before and after calling its remove() or shutdown() callback. + +However WMI driver developers should be aware that multiple WMI events can be received concurrently, +so any locking (if necessary) needs to be provided by the WMI driver itself. + +In order to be able to receive WMI events containing no additional event data, +the ``no_notify_data`` flag inside struct wmi_driver should be set to ``true``. + +Take a look at drivers/platform/x86/xiaomi-wmi.c for an example WMI event driver. + +Handling multiple WMI devices at once +------------------------------------- + +There are many cases of firmware vendors using multiple WMI devices to control different aspects +of a single physical device. This can make developing WMI drivers complicated, as those drivers +might need to communicate with each other to present a unified interface to userspace. + +On such case involves a WMI event device which needs to talk to a WMI data block device or WMI +method device upon receiving an WMI event. In such a case, two WMI drivers should be developed, +one for the WMI event device and one for the other WMI device. + +The WMI event device driver has only one purpose: to receive WMI events, validate any additional +event data and invoke a notifier chain. The other WMI driver adds itself to this notifier chain +during probing and thus gets notified every time a WMI event is received. This WMI driver might +then process the event further for example by using an input device. + +For other WMI device constellations, similar mechanisms can be used. + +Things to avoid +--------------- + +When developing WMI drivers, there are a couple of things which should be avoided: + +- usage of the deprecated GUID-based WMI interface which uses GUIDs instead of WMI device structs +- bypassing of the WMI subsystem when talking to WMI devices +- WMI drivers which cannot be instantiated multiple times. + +Many older WMI drivers violate one or more points from this list. The reason for +this is that the WMI subsystem evolved significantly over the last two decades, +so there is a lot of legacy cruft inside older WMI drivers. + +New WMI drivers are also required to conform to the linux kernel coding style as specified in +Documentation/process/coding-style.rst. The checkpatch utility can catch many common coding style +violations, you can invoke it with the following command: + +:: + + ./scripts/checkpatch.pl --strict <path to driver file> + +References +========== + +.. [1] https://lwn.net/Articles/391230/ diff --git a/Documentation/wmi/index.rst b/Documentation/wmi/index.rst index 537cff188e14..fec4b6ae97b3 100644 --- a/Documentation/wmi/index.rst +++ b/Documentation/wmi/index.rst @@ -8,6 +8,7 @@ WMI Subsystem :maxdepth: 1 acpi-interface + driver-development-guide devices/index .. only:: subproject and html |