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