Documentation/wmi/devices/dell-wmi-ddv.rst

   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 WMI-based interface for
  11 retrieving various system data like battery temperature, ePPID, diagostic data
  12 and fan/thermal sensor data.
  13
  14 This interface is likely used by the `Dell Data Vault` software on Windows,
  15 so it was called `DDV`. Currently the ``dell-wmi-ddv`` driver supports
  16 version 2 and 3 of the interface, with support for new interface versions
  17 easily 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
  23 Dell ePPID (electronic Piece Part Identification)
  24 =================================================
  25
  26 The Dell ePPID is used to uniquely identify components in Dell machines,
  27 including batteries. It has a form similar to `CC-PPPPPP-MMMMM-YMD-SSSS-FFF`
  28 and 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
  38 The `eppidtool <https://pypi.org/project/eppidtool>`_ python utility can be used
  39 to decode and display this information.
  40
  41 All information regarding the Dell ePPID was gathered using Dell support
  42 documentation and `this website <https://telcontar.net/KBK/Dell/date_codes>`_.
  43
  44 WMI interface description
  45 =========================
  46
  47 The WMI interface description can be decoded from the embedded binary MOF (bmof)
  48 data 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
  79 Each WMI method takes an ACPI buffer containing a 32-bit index as input argument,
  80 with the first 8 bit being used to specify the battery when using battery-related
  81 WMI methods. Other WMI methods may ignore this argument or interpret it
  82 differently. 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
  89 The format of the output should be thoroughly checked, since many methods can
  90 return malformed data in case of an error.
  91
  92 The data format of many battery-related methods seems to be based on the
  93 `Smart Battery Data Specification`, so unknown battery-related methods are
  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 mAh as an u16.
 100
 101 WMI method BatteryFullCharge()
 102 ------------------------------
 103
 104 Returns the full charge capacity of the battery in mAh as an u16.
 105
 106 WMI method BatteryManufactureName()
 107 -----------------------------------
 108
 109 Returns the manufacture name of the battery as an ASCII string.
 110
 111 WMI method BatteryManufactureDate()
 112 -----------------------------------
 113
 114 Returns the manufacture date of the battery as an u16.
 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 biased by 1980.
 120
 121 .. note::
 122    The data format needs to be verified on more machines.
 123
 124 WMI method BatterySerialNumber()
 125 --------------------------------
 126
 127 Returns the serial number of the battery as an u16.
 128
 129 WMI method BatteryChemistryValue()
 130 ----------------------------------
 131
 132 Returns the chemistry of the battery as an ASCII string.
 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 tenth degree kelvin as an u16.
 141
 142 WMI method BatteryCurrent()
 143 ---------------------------
 144
 145 Returns the current flow of the battery in mA as an s16.
 146 Negative values indicate discharging.
 147
 148 WMI method BatteryVoltage()
 149 ---------------------------
 150
 151 Returns the voltage flow of the battery in mV as an u16.
 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 as an u16.
 162
 163 WMI method BatteryCycleCount()
 164 ------------------------------
 165
 166 Returns the cycle count of the battery as an u16.
 167
 168 WMI method BatteryePPID()
 169 -------------------------
 170
 171 Returns the ePPID of the battery as an ASCII string.
 172
 173 WMI method BatteryeRawAnalyticsStart()
 174 --------------------------------------
 175
 176 Performs 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
 185 WMI method BatteryeRawAnalytics()
 186 ---------------------------------
 187
 188 Returns a buffer usually containing 12 blocks of analytics data.
 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 unknown.
 196
 197 WMI method BatteryDesignVoltage()
 198 ---------------------------------
 199
 200 Returns the design voltage of the battery in mV as an u16.
 201
 202 WMI method BatteryeRawAnalyticsABlock()
 203 ---------------------------------------
 204
 205 Returns a single block of analytics data, with the second byte
 206 of 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
 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, terminated
 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 entries, terminated
 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 byte is.
 243
 244 ACPI battery matching algorithm
 245 ===============================
 246
 247 The algorithm used to match ACPI batteries to indices is based on information
 248 which was found inside the logging messages of the OEM software.
 249
 250 Basically for each new ACPI battery, the serial numbers of the batteries behind
 251 indices 1 till 3 are compared with the serial number of the ACPI battery.
 252 Since the serial number of the ACPI battery can either be encoded as a normal
 253 integer or as a hexadecimal value, both cases need to be checked. The first
 254 index with a matching serial number is then selected.
 255
 256 A serial number of 0 indicates that the corresponding index is not associated
 257 with an actual battery, or that the associated battery is not present.
 258
 259 Some machines like the Dell Inspiron 3505 only support a single battery and thus
 260 ignore the battery index. Because of this the driver depends on the ACPI battery
 261 hook 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
 271 Reverse-Engineering the DDV WMI interface
 272 =========================================
 273
 274 1. Find a supported Dell notebook, usually made after ~2020.
 275 2. Dump the ACPI tables and search for the WMI device (usually called "ADDV").
 276 3. Decode the corresponding bmof data and look at the ASL code.
 277 4. 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).
 280 5. 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
 285 Alternatively:
 286
 287 1. Load the ``dell-wmi-ddv`` driver, use the ``force`` module param
 288    if necessary.
 289 2. Use the debugfs interface to access the raw fan/thermal sensor buffer data.
 290 3. Compare the data with the built-in UEFI diagnostics.
 291
 292 In case the DDV WMI interface version available on your Dell notebook is not
 293 supported or you are seeing unknown fan/thermal sensors, please submit a
 294 bugreport on `bugzilla <https://bugzilla.kernel.org>`_ so they can be added
 295 to the ``dell-wmi-ddv`` driver.
 296
 297 See Documentation/admin-guide/reporting-issues.rst for further information.