1.. SPDX-License-Identifier: GPL-2.0-or-later
2
3============================================
4Dell DDV WMI interface driver (dell-wmi-ddv)
5============================================
6
7Introduction
8============
9
10Many Dell notebooks made after ~2020 support a WMI-based interface for
11retrieving various system data like battery temperature, ePPID, diagostic data
12and fan/thermal sensor data.
13
14This interface is likely used by the `Dell Data Vault` software on Windows,
15so it was called `DDV`. Currently the ``dell-wmi-ddv`` driver supports
16version 2 and 3 of the interface, with support for new interface versions
17easily added.
18
19.. warning:: The interface is regarded as internal by Dell, so no vendor
20             documentation is available. All knowledge was thus obtained by
21             trial-and-error, please keep that in mind.
22
23Dell ePPID (electronic Piece Part Identification)
24=================================================
25
26The Dell ePPID is used to uniquely identify components in Dell machines,
27including batteries. It has a form similar to `CC-PPPPPP-MMMMM-YMD-SSSS-FFF`
28and contains the following information:
29
30* Country code of origin (CC).
31* Part number with the first character being a filling number (PPPPPP).
32* Manufacture Identification (MMMMM).
33* Manufacturing Year/Month/Date (YMD) in base 36, with Y being the last digit
34  of the year.
35* Manufacture Sequence Number (SSSS).
36* Optional Firmware Version/Revision (FFF).
37
38The `eppidtool <https://pypi.org/project/eppidtool>`_ python utility can be used
39to decode and display this information.
40
41All information regarding the Dell ePPID was gathered using Dell support
42documentation and `this website <https://telcontar.net/KBK/Dell/date_codes>`_.
43
44WMI interface description
45=========================
46
47The WMI interface description can be decoded from the embedded binary MOF (bmof)
48data using the `bmfdec <https://github.com/pali/bmfdec>`_ utility:
49
50::
51
52 [WMI, Dynamic, Provider("WmiProv"), Locale("MS\\0x409"), Description("WMI Function"), guid("{8A42EA14-4F2A-FD45-6422-0087F7A7E608}")]
53 class DDVWmiMethodFunction {
54   [key, read] string InstanceName;
55   [read] boolean Active;
56
57   [WmiMethodId(1), Implemented, read, write, Description("Return Battery Design Capacity.")] void BatteryDesignCapacity([in] uint32 arg2, [out] uint32 argr);
58   [WmiMethodId(2), Implemented, read, write, Description("Return Battery Full Charge Capacity.")] void BatteryFullChargeCapacity([in] uint32 arg2, [out] uint32 argr);
59   [WmiMethodId(3), Implemented, read, write, Description("Return Battery Manufacture Name.")] void BatteryManufactureName([in] uint32 arg2, [out] string argr);
60   [WmiMethodId(4), Implemented, read, write, Description("Return Battery Manufacture Date.")] void BatteryManufactureDate([in] uint32 arg2, [out] uint32 argr);
61   [WmiMethodId(5), Implemented, read, write, Description("Return Battery Serial Number.")] void BatterySerialNumber([in] uint32 arg2, [out] uint32 argr);
62   [WmiMethodId(6), Implemented, read, write, Description("Return Battery Chemistry Value.")] void BatteryChemistryValue([in] uint32 arg2, [out] string argr);
63   [WmiMethodId(7), Implemented, read, write, Description("Return Battery Temperature.")] void BatteryTemperature([in] uint32 arg2, [out] uint32 argr);
64   [WmiMethodId(8), Implemented, read, write, Description("Return Battery Current.")] void BatteryCurrent([in] uint32 arg2, [out] uint32 argr);
65   [WmiMethodId(9), Implemented, read, write, Description("Return Battery Voltage.")] void BatteryVoltage([in] uint32 arg2, [out] uint32 argr);
66   [WmiMethodId(10), Implemented, read, write, Description("Return Battery Manufacture Access(MA code).")] void BatteryManufactureAceess([in] uint32 arg2, [out] uint32 argr);
67   [WmiMethodId(11), Implemented, read, write, Description("Return Battery Relative State-Of-Charge.")] void BatteryRelativeStateOfCharge([in] uint32 arg2, [out] uint32 argr);
68   [WmiMethodId(12), Implemented, read, write, Description("Return Battery Cycle Count")] void BatteryCycleCount([in] uint32 arg2, [out] uint32 argr);
69   [WmiMethodId(13), Implemented, read, write, Description("Return Battery ePPID")] void BatteryePPID([in] uint32 arg2, [out] string argr);
70   [WmiMethodId(14), Implemented, read, write, Description("Return Battery Raw Analytics Start")] void BatteryeRawAnalyticsStart([in] uint32 arg2, [out] uint32 argr);
71   [WmiMethodId(15), Implemented, read, write, Description("Return Battery Raw Analytics")] void BatteryeRawAnalytics([in] uint32 arg2, [out] uint32 RawSize, [out, WmiSizeIs("RawSize") : ToInstance] uint8 RawData[]);
72   [WmiMethodId(16), Implemented, read, write, Description("Return Battery Design Voltage.")] void BatteryDesignVoltage([in] uint32 arg2, [out] uint32 argr);
73   [WmiMethodId(17), Implemented, read, write, Description("Return Battery Raw Analytics A Block")] void BatteryeRawAnalyticsABlock([in] uint32 arg2, [out] uint32 RawSize, [out, WmiSizeIs("RawSize") : ToInstance] uint8 RawData[]);
74   [WmiMethodId(18), Implemented, read, write, Description("Return Version.")] void ReturnVersion([in] uint32 arg2, [out] uint32 argr);
75   [WmiMethodId(32), Implemented, read, write, Description("Return Fan Sensor Information")] void FanSensorInformation([in] uint32 arg2, [out] uint32 RawSize, [out, WmiSizeIs("RawSize") : ToInstance] uint8 RawData[]);
76   [WmiMethodId(34), Implemented, read, write, Description("Return Thermal Sensor Information")] void ThermalSensorInformation([in] uint32 arg2, [out] uint32 RawSize, [out, WmiSizeIs("RawSize") : ToInstance] uint8 RawData[]);
77 };
78
79Each WMI method takes an ACPI buffer containing a 32-bit index as input argument,
80with the first 8 bit being used to specify the battery when using battery-related
81WMI methods. Other WMI methods may ignore this argument or interpret it
82differently. The WMI method output format varies:
83
84* if the function has only a single output, then an ACPI object
85  of the corresponding type is returned
86* if the function has multiple outputs, when an ACPI package
87  containing the outputs in the same order is returned
88
89The format of the output should be thoroughly checked, since many methods can
90return malformed data in case of an error.
91
92The data format of many battery-related methods seems to be based on the
93`Smart Battery Data Specification`, so unknown battery-related methods are
94likely to follow this standard in some way.
95
96WMI method GetBatteryDesignCapacity()
97-------------------------------------
98
99Returns the design capacity of the battery in mAh as an u16.
100
101WMI method BatteryFullCharge()
102------------------------------
103
104Returns the full charge capacity of the battery in mAh as an u16.
105
106WMI method BatteryManufactureName()
107-----------------------------------
108
109Returns the manufacture name of the battery as an ASCII string.
110
111WMI method BatteryManufactureDate()
112-----------------------------------
113
114Returns the manufacture date of the battery as an u16.
115The date is encoded in the following manner:
116
117- bits 0 to 4 contain the manufacture day.
118- bits 5 to 8 contain the manufacture month.
119- bits 9 to 15 contain the manufacture year biased by 1980.
120
121.. note::
122   The data format needs to be verified on more machines.
123
124WMI method BatterySerialNumber()
125--------------------------------
126
127Returns the serial number of the battery as an u16.
128
129WMI method BatteryChemistryValue()
130----------------------------------
131
132Returns the chemistry of the battery as an ASCII string.
133Known values are:
134
135- "Li-I" for Li-Ion
136
137WMI method BatteryTemperature()
138-------------------------------
139
140Returns the temperature of the battery in tenth degree kelvin as an u16.
141
142WMI method BatteryCurrent()
143---------------------------
144
145Returns the current flow of the battery in mA as an s16.
146Negative values indicate discharging.
147
148WMI method BatteryVoltage()
149---------------------------
150
151Returns the voltage flow of the battery in mV as an u16.
152
153WMI method BatteryManufactureAccess()
154-------------------------------------
155
156Returns a manufacture-defined value as an u16.
157
158WMI method BatteryRelativeStateOfCharge()
159-----------------------------------------
160
161Returns the capacity of the battery in percent as an u16.
162
163WMI method BatteryCycleCount()
164------------------------------
165
166Returns the cycle count of the battery as an u16.
167
168WMI method BatteryePPID()
169-------------------------
170
171Returns the ePPID of the battery as an ASCII string.
172
173WMI method BatteryeRawAnalyticsStart()
174--------------------------------------
175
176Performs an analysis of the battery and returns a status code:
177
178- ``0x0``: Success
179- ``0x1``: Interface not supported
180- ``0xfffffffe``: Error/Timeout
181
182.. note::
183   The meaning of this method is still largely unknown.
184
185WMI method BatteryeRawAnalytics()
186---------------------------------
187
188Returns a buffer usually containg 12 blocks of analytics data.
189Those blocks contain:
190
191- a block number starting with 0 (u8)
192- 31 bytes of unknown data
193
194.. note::
195   The meaning of this method is still largely unknown.
196
197WMI method BatteryDesignVoltage()
198---------------------------------
199
200Returns the design voltage of the battery in mV as an u16.
201
202WMI method BatteryeRawAnalyticsABlock()
203---------------------------------------
204
205Returns a single block of analytics data, with the second byte
206of the index being used for selecting the block number.
207
208*Supported since WMI interface version 3!*
209
210.. note::
211   The meaning of this method is still largely unknown.
212
213WMI method ReturnVersion()
214--------------------------
215
216Returns the WMI interface version as an u32.
217
218WMI method FanSensorInformation()
219---------------------------------
220
221Returns a buffer containg fan sensor entries, terminated
222with a single ``0xff``.
223Those entries contain:
224
225- fan type (u8)
226- fan speed in RPM (little endian u16)
227
228WMI method ThermalSensorInformation()
229-------------------------------------
230
231Returns a buffer containing thermal sensor entries, terminated
232with a single ``0xff``.
233Those entries contain:
234
235- thermal type (u8)
236- current temperature (s8)
237- min. temperature (s8)
238- max. temperature (s8)
239- unknown field (u8)
240
241.. note::
242   TODO: Find out what the meaning of the last byte is.
243
244ACPI battery matching algorithm
245===============================
246
247The algorithm used to match ACPI batteries to indices is based on information
248which was found inside the logging messages of the OEM software.
249
250Basically for each new ACPI battery, the serial numbers of the batteries behind
251indices 1 till 3 are compared with the serial number of the ACPI battery.
252Since the serial number of the ACPI battery can either be encoded as a normal
253integer or as a hexadecimal value, both cases need to be checked. The first
254index with a matching serial number is then selected.
255
256A serial number of 0 indicates that the corresponding index is not associated
257with an actual battery, or that the associated battery is not present.
258
259Some machines like the Dell Inspiron 3505 only support a single battery and thus
260ignore the battery index. Because of this the driver depends on the ACPI battery
261hook mechanism to discover batteries.
262
263.. note::
264   The ACPI battery matching algorithm currently used inside the driver is
265   outdated and does not match the algorithm described above. The reasons for
266   this are differences in the handling of the ToHexString() ACPI opcode between
267   Linux and Windows, which distorts the serial number of ACPI batteries on many
268   machines. Until this issue is resolved, the driver cannot use the above
269   algorithm.
270
271Reverse-Engineering the DDV WMI interface
272=========================================
273
2741. Find a supported Dell notebook, usually made after ~2020.
2752. Dump the ACPI tables and search for the WMI device (usually called "ADDV").
2763. Decode the corresponding bmof data and look at the ASL code.
2774. Try to deduce the meaning of a certain WMI method by comparing the control
278   flow with other ACPI methods (_BIX or _BIF for battery related methods
279   for example).
2805. Use the built-in UEFI diagostics to view sensor types/values for fan/thermal
281   related methods (sometimes overwriting static ACPI data fields can be used
282   to test different sensor type values, since on some machines this data is
283   not reinitialized upon a warm reset).
284
285Alternatively:
286
2871. Load the ``dell-wmi-ddv`` driver, use the ``force`` module param
288   if necessary.
2892. Use the debugfs interface to access the raw fan/thermal sensor buffer data.
2903. Compare the data with the built-in UEFI diagnostics.
291
292In case the DDV WMI interface version available on your Dell notebook is not
293supported or you are seeing unknown fan/thermal sensors, please submit a
294bugreport on `bugzilla <https://bugzilla.kernel.org>`_ so they can be added
295to the ``dell-wmi-ddv`` driver.
296
297See Documentation/admin-guide/reporting-issues.rst for further information.
298