1.. SPDX-License-Identifier: GPL-2.0-or-later 2 3=================================================== 4MSI WMI Platform Features driver (msi-wmi-platform) 5=================================================== 6 7Introduction 8============ 9 10Many MSI notebooks support various features like reading fan sensors. This features are controlled 11by the embedded controller, with the ACPI firmware exposing a standard ACPI WMI interface on top 12of the embedded controller interface. 13 14WMI interface description 15========================= 16 17The WMI interface description can be decoded from the embedded binary MOF (bmof) 18data using the `bmfdec <https://github.com/pali/bmfdec>`_ utility: 19 20:: 21 22 [WMI, Locale("MS\0x409"), 23 Description("This class contains the definition of the package used in other classes"), 24 guid("{ABBC0F60-8EA1-11d1-00A0-C90629100000}")] 25 class Package { 26 [WmiDataId(1), read, write, Description("16 bytes of data")] uint8 Bytes[16]; 27 }; 28 29 [WMI, Locale("MS\0x409"), 30 Description("This class contains the definition of the package used in other classes"), 31 guid("{ABBC0F63-8EA1-11d1-00A0-C90629100000}")] 32 class Package_32 { 33 [WmiDataId(1), read, write, Description("32 bytes of data")] uint8 Bytes[32]; 34 }; 35 36 [WMI, Dynamic, Provider("WmiProv"), Locale("MS\0x409"), 37 Description("Class used to operate methods on a package"), 38 guid("{ABBC0F6E-8EA1-11d1-00A0-C90629100000}")] 39 class MSI_ACPI { 40 [key, read] string InstanceName; 41 [read] boolean Active; 42 43 [WmiMethodId(1), Implemented, read, write, Description("Return the contents of a package")] 44 void GetPackage([out, id(0)] Package Data); 45 46 [WmiMethodId(2), Implemented, read, write, Description("Set the contents of a package")] 47 void SetPackage([in, id(0)] Package Data); 48 49 [WmiMethodId(3), Implemented, read, write, Description("Return the contents of a package")] 50 void Get_EC([out, id(0)] Package_32 Data); 51 52 [WmiMethodId(4), Implemented, read, write, Description("Set the contents of a package")] 53 void Set_EC([in, id(0)] Package_32 Data); 54 55 [WmiMethodId(5), Implemented, read, write, Description("Return the contents of a package")] 56 void Get_BIOS([in, out, id(0)] Package_32 Data); 57 58 [WmiMethodId(6), Implemented, read, write, Description("Set the contents of a package")] 59 void Set_BIOS([in, out, id(0)] Package_32 Data); 60 61 [WmiMethodId(7), Implemented, read, write, Description("Return the contents of a package")] 62 void Get_SMBUS([in, out, id(0)] Package_32 Data); 63 64 [WmiMethodId(8), Implemented, read, write, Description("Set the contents of a package")] 65 void Set_SMBUS([in, out, id(0)] Package_32 Data); 66 67 [WmiMethodId(9), Implemented, read, write, Description("Return the contents of a package")] 68 void Get_MasterBattery([in, out, id(0)] Package_32 Data); 69 70 [WmiMethodId(10), Implemented, read, write, Description("Set the contents of a package")] 71 void Set_MasterBattery([in, out, id(0)] Package_32 Data); 72 73 [WmiMethodId(11), Implemented, read, write, Description("Return the contents of a package")] 74 void Get_SlaveBattery([in, out, id(0)] Package_32 Data); 75 76 [WmiMethodId(12), Implemented, read, write, Description("Set the contents of a package")] 77 void Set_SlaveBattery([in, out, id(0)] Package_32 Data); 78 79 [WmiMethodId(13), Implemented, read, write, Description("Return the contents of a package")] 80 void Get_Temperature([in, out, id(0)] Package_32 Data); 81 82 [WmiMethodId(14), Implemented, read, write, Description("Set the contents of a package")] 83 void Set_Temperature([in, out, id(0)] Package_32 Data); 84 85 [WmiMethodId(15), Implemented, read, write, Description("Return the contents of a package")] 86 void Get_Thermal([in, out, id(0)] Package_32 Data); 87 88 [WmiMethodId(16), Implemented, read, write, Description("Set the contents of a package")] 89 void Set_Thermal([in, out, id(0)] Package_32 Data); 90 91 [WmiMethodId(17), Implemented, read, write, Description("Return the contents of a package")] 92 void Get_Fan([in, out, id(0)] Package_32 Data); 93 94 [WmiMethodId(18), Implemented, read, write, Description("Set the contents of a package")] 95 void Set_Fan([in, out, id(0)] Package_32 Data); 96 97 [WmiMethodId(19), Implemented, read, write, Description("Return the contents of a package")] 98 void Get_Device([in, out, id(0)] Package_32 Data); 99 100 [WmiMethodId(20), Implemented, read, write, Description("Set the contents of a package")] 101 void Set_Device([in, out, id(0)] Package_32 Data); 102 103 [WmiMethodId(21), Implemented, read, write, Description("Return the contents of a package")] 104 void Get_Power([in, out, id(0)] Package_32 Data); 105 106 [WmiMethodId(22), Implemented, read, write, Description("Set the contents of a package")] 107 void Set_Power([in, out, id(0)] Package_32 Data); 108 109 [WmiMethodId(23), Implemented, read, write, Description("Return the contents of a package")] 110 void Get_Debug([in, out, id(0)] Package_32 Data); 111 112 [WmiMethodId(24), Implemented, read, write, Description("Set the contents of a package")] 113 void Set_Debug([in, out, id(0)] Package_32 Data); 114 115 [WmiMethodId(25), Implemented, read, write, Description("Return the contents of a package")] 116 void Get_AP([in, out, id(0)] Package_32 Data); 117 118 [WmiMethodId(26), Implemented, read, write, Description("Set the contents of a package")] 119 void Set_AP([in, out, id(0)] Package_32 Data); 120 121 [WmiMethodId(27), Implemented, read, write, Description("Return the contents of a package")] 122 void Get_Data([in, out, id(0)] Package_32 Data); 123 124 [WmiMethodId(28), Implemented, read, write, Description("Set the contents of a package")] 125 void Set_Data([in, out, id(0)] Package_32 Data); 126 127 [WmiMethodId(29), Implemented, read, write, Description("Return the contents of a package")] 128 void Get_WMI([out, id(0)] Package_32 Data); 129 }; 130 131Due to a peculiarity in how Windows handles the ``CreateByteField()`` ACPI operator (errors only 132happen when a invalid byte field is ultimately accessed), all methods require a 32 byte input 133buffer, even if the Binary MOF says otherwise. 134 135The input buffer contains a single byte to select the subfeature to be accessed and 31 bytes of 136input data, the meaning of which depends on the subfeature being accessed. 137 138The output buffer contains a single byte which signals success or failure (``0x00`` on failure) 139and 31 bytes of output data, the meaning if which depends on the subfeature being accessed. 140 141WMI method Get_EC() 142------------------- 143 144Returns embedded controller information, the selected subfeature does not matter. The output 145data contains a flag byte and a 28 byte controller firmware version string. 146 147The first 4 bits of the flag byte contain the minor version of the embedded controller interface, 148with the next 2 bits containing the major version of the embedded controller interface. 149 150The 7th bit signals if the embedded controller page changed (exact meaning is unknown), and the 151last bit signals if the platform is a Tigerlake platform. 152 153The MSI software seems to only use this interface when the last bit is set. 154 155WMI method Get_Fan() 156-------------------- 157 158Fan speed sensors can be accessed by selecting subfeature ``0x00``. The output data contains 159up to four 16-bit fan speed readings in big-endian format. Most machines do not support all 160four fan speed sensors, so the remaining reading are hardcoded to ``0x0000``. 161 162The fan RPM readings can be calculated with the following formula: 163 164 RPM = 480000 / <fan speed reading> 165 166If the fan speed reading is zero, then the fan RPM is zero too. 167 168WMI method Get_WMI() 169-------------------- 170 171Returns the version of the ACPI WMI interface, the selected subfeature does not matter. 172The output data contains two bytes, the first one contains the major version and the last one 173contains the minor revision of the ACPI WMI interface. 174 175The MSI software seems to only use this interface when the major version is greater than two. 176 177Reverse-Engineering the MSI WMI Platform interface 178================================================== 179 180.. warning:: Randomly poking the embedded controller interface can potentially cause damage 181 to the machine and other unwanted side effects, please be careful. 182 183The underlying embedded controller interface is used by the ``msi-ec`` driver, and it seems 184that many methods just copy a part of the embedded controller memory into the output buffer. 185 186This means that the remaining WMI methods can be reverse-engineered by looking which part of 187the embedded controller memory is accessed by the ACPI AML code. The driver also supports a 188debugfs interface for directly executing WMI methods. Additionally, any safety checks regarding 189unsupported hardware can be disabled by loading the module with ``force=true``. 190 191More information about the MSI embedded controller interface can be found at the 192`msi-ec project <https://github.com/BeardOverflow/msi-ec>`_. 193 194Special thanks go to github user `glpnk` for showing how to decode the fan speed readings. 195