1 .. SPDX-License-Identifier: GPL-2.0-or-later
2
3 ============================================
4 Dell DDV WMI interface driver (dell-wmi-ddv)
5 ============================================
6
7 Introduction
8 ============
9
10 Many Dell notebooks made after ~2020 support a
11 retrieving various system data like battery te
12 and fan/thermal sensor data.
13
14 This interface is likely used by the `Dell Dat
15 so it was called `DDV`. Currently the ``dell-w
16 version 2 and 3 of the interface, with support
17 easily added.
18
19 .. warning:: The interface is regarded as inte
20 documentation is available. All k
21 trial-and-error, please keep that
22
23 Dell ePPID (electronic Piece Part Identificati
24 ==============================================
25
26 The Dell ePPID is used to uniquely identify co
27 including batteries. It has a form similar to
28 and contains the following information:
29
30 * Country code of origin (CC).
31 * Part number with the first character being a
32 * Manufacture Identification (MMMMM).
33 * Manufacturing Year/Month/Date (YMD) in base
34 of the year.
35 * Manufacture Sequence Number (SSSS).
36 * Optional Firmware Version/Revision (FFF).
37
38 The `eppidtool <https://pypi.org/project/eppid
39 to decode and display this information.
40
41 All information regarding the Dell ePPID was g
42 documentation and `this website <https://telco
43
44 WMI interface description
45 =========================
46
47 The WMI interface description can be decoded f
48 data using the `bmfdec <https://github.com/pal
49
50 ::
51
52 [WMI, Dynamic, Provider("WmiProv"), Locale("M
53 class DDVWmiMethodFunction {
54 [key, read] string InstanceName;
55 [read] boolean Active;
56
57 [WmiMethodId(1), Implemented, read, write,
58 [WmiMethodId(2), Implemented, read, write,
59 [WmiMethodId(3), Implemented, read, write,
60 [WmiMethodId(4), Implemented, read, write,
61 [WmiMethodId(5), Implemented, read, write,
62 [WmiMethodId(6), Implemented, read, write,
63 [WmiMethodId(7), Implemented, read, write,
64 [WmiMethodId(8), Implemented, read, write,
65 [WmiMethodId(9), Implemented, read, write,
66 [WmiMethodId(10), Implemented, read, write,
67 [WmiMethodId(11), Implemented, read, write,
68 [WmiMethodId(12), Implemented, read, write,
69 [WmiMethodId(13), Implemented, read, write,
70 [WmiMethodId(14), Implemented, read, write,
71 [WmiMethodId(15), Implemented, read, write,
72 [WmiMethodId(16), Implemented, read, write,
73 [WmiMethodId(17), Implemented, read, write,
74 [WmiMethodId(18), Implemented, read, write,
75 [WmiMethodId(32), Implemented, read, write,
76 [WmiMethodId(34), Implemented, read, write,
77 };
78
79 Each WMI method takes an ACPI buffer containin
80 with the first 8 bit being used to specify the
81 WMI methods. Other WMI methods may ignore this
82 differently. The WMI method output format vari
83
84 * if the function has only a single output, th
85 of the corresponding type is returned
86 * if the function has multiple outputs, when a
87 containing the outputs in the same order is
88
89 The format of the output should be thoroughly
90 return malformed data in case of an error.
91
92 The data format of many battery-related method
93 `Smart Battery Data Specification`, so unknown
94 likely to follow this standard in some way.
95
96 WMI method GetBatteryDesignCapacity()
97 -------------------------------------
98
99 Returns the design capacity of the battery in
100
101 WMI method BatteryFullCharge()
102 ------------------------------
103
104 Returns the full charge capacity of the batter
105
106 WMI method BatteryManufactureName()
107 -----------------------------------
108
109 Returns the manufacture name of the battery as
110
111 WMI method BatteryManufactureDate()
112 -----------------------------------
113
114 Returns the manufacture date of the battery as
115 The 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 bi
120
121 .. note::
122 The data format needs to be verified on mor
123
124 WMI method BatterySerialNumber()
125 --------------------------------
126
127 Returns the serial number of the battery as an
128
129 WMI method BatteryChemistryValue()
130 ----------------------------------
131
132 Returns the chemistry of the battery as an ASC
133 Known values are:
134
135 - "Li-I" for Li-Ion
136
137 WMI method BatteryTemperature()
138 -------------------------------
139
140 Returns the temperature of the battery in tent
141
142 WMI method BatteryCurrent()
143 ---------------------------
144
145 Returns the current flow of the battery in mA
146 Negative values indicate discharging.
147
148 WMI method BatteryVoltage()
149 ---------------------------
150
151 Returns the voltage flow of the battery in mV
152
153 WMI method BatteryManufactureAccess()
154 -------------------------------------
155
156 Returns a manufacture-defined value as an u16.
157
158 WMI method BatteryRelativeStateOfCharge()
159 -----------------------------------------
160
161 Returns the capacity of the battery in percent
162
163 WMI method BatteryCycleCount()
164 ------------------------------
165
166 Returns the cycle count of the battery as an u
167
168 WMI method BatteryePPID()
169 -------------------------
170
171 Returns the ePPID of the battery as an ASCII s
172
173 WMI method BatteryeRawAnalyticsStart()
174 --------------------------------------
175
176 Performs an analysis of the battery and return
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
184
185 WMI method BatteryeRawAnalytics()
186 ---------------------------------
187
188 Returns a buffer usually containing 12 blocks
189 Those 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
196
197 WMI method BatteryDesignVoltage()
198 ---------------------------------
199
200 Returns the design voltage of the battery in m
201
202 WMI method BatteryeRawAnalyticsABlock()
203 ---------------------------------------
204
205 Returns a single block of analytics data, with
206 of the index being used for selecting the bloc
207
208 *Supported since WMI interface version 3!*
209
210 .. note::
211 The meaning of this method is still largely
212
213 WMI method ReturnVersion()
214 --------------------------
215
216 Returns the WMI interface version as an u32.
217
218 WMI method FanSensorInformation()
219 ---------------------------------
220
221 Returns a buffer containing fan sensor entries
222 with a single ``0xff``.
223 Those entries contain:
224
225 - fan type (u8)
226 - fan speed in RPM (little endian u16)
227
228 WMI method ThermalSensorInformation()
229 -------------------------------------
230
231 Returns a buffer containing thermal sensor ent
232 with a single ``0xff``.
233 Those 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
243
244 ACPI battery matching algorithm
245 ===============================
246
247 The algorithm used to match ACPI batteries to
248 which was found inside the logging messages of
249
250 Basically for each new ACPI battery, the seria
251 indices 1 till 3 are compared with the serial
252 Since the serial number of the ACPI battery ca
253 integer or as a hexadecimal value, both cases
254 index with a matching serial number is then se
255
256 A serial number of 0 indicates that the corres
257 with an actual battery, or that the associated
258
259 Some machines like the Dell Inspiron 3505 only
260 ignore the battery index. Because of this the
261 hook mechanism to discover batteries.
262
263 .. note::
264 The ACPI battery matching algorithm current
265 outdated and does not match the algorithm d
266 this are differences in the handling of the
267 Linux and Windows, which distorts the seria
268 machines. Until this issue is resolved, the
269 algorithm.
270
271 Reverse-Engineering the DDV WMI interface
272 =========================================
273
274 1. Find a supported Dell notebook, usually mad
275 2. Dump the ACPI tables and search for the WMI
276 3. Decode the corresponding bmof data and look
277 4. Try to deduce the meaning of a certain WMI
278 flow with other ACPI methods (_BIX or _BIF
279 for example).
280 5. Use the built-in UEFI diagnostics to view s
281 related methods (sometimes overwriting stat
282 to test different sensor type values, since
283 not reinitialized upon a warm reset).
284
285 Alternatively:
286
287 1. Load the ``dell-wmi-ddv`` driver, use the `
288 if necessary.
289 2. Use the debugfs interface to access the raw
290 3. Compare the data with the built-in UEFI dia
291
292 In case the DDV WMI interface version availabl
293 supported or you are seeing unknown fan/therma
294 bugreport on `bugzilla <https://bugzilla.kerne
295 to the ``dell-wmi-ddv`` driver.
296
297 See Documentation/admin-guide/reporting-issues
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.