Dell DDV WMI interface driver (dell-wmi-ddv)

DDV interface 개요와 주의 사항

대략 2020년 이후 제조된 많은 Dell notebook은 battery 온도, ePPID, 진단 data, fan 및 thermal sensor data를 가져오는 WMI 기반 interface를 지원합니다.

Windows의 Dell Data Vault software가 이 interface를 사용하는 것으로 보여 `DDV`라는 이름이 붙었습니다. 현재 `dell-wmi-ddv` 드라이버는 interface version 2와 3을 지원하며 새 version도 쉽게 추가할 수 있게 설계되었습니다.

Dell은 이 interface를 내부용으로 간주해 vendor 문서를 제공하지 않습니다. 알려진 내용은 모두 시행착오로 얻은 것이므로 field와 동작 설명에는 이 한계가 적용됩니다.

.. SPDX-License-Identifier: GPL-2.0-or-later

============================================
Dell DDV WMI interface driver (dell-wmi-ddv)
============================================

Introduction
============

Many Dell notebooks made after ~2020 support a WMI-based interface for
retrieving various system data like battery temperature, ePPID, diagnostic data
and fan/thermal sensor data.

This interface is likely used by the `Dell Data Vault` software on Windows,
so it was called `DDV`. Currently the ``dell-wmi-ddv`` driver supports
version 2 and 3 of the interface, with support for new interface versions
easily added.

.. warning:: The interface is regarded as internal by Dell, so no vendor
             documentation is available. All knowledge was thus obtained by
             trial-and-error, please keep that in mind.

Dell ePPID 형식

Dell ePPID(electronic Piece Part Identification)는 battery를 포함한 Dell 장치의 부품을 고유하게 식별합니다. 형식은 `CC-PPPPPP-MMMMM-YMD-SSSS-FFF`와 비슷합니다.

`YMD`는 base 36으로 표현한 제조 연·월·일이며 Y는 연도의 마지막 자리입니다. 마지막 firmware version 또는 revision field는 선택 사항입니다. `eppidtool` Python utility로 이 정보를 해석해 표시할 수 있습니다.

Dell ePPID (electronic Piece Part Identification)
=================================================

The Dell ePPID is used to uniquely identify components in Dell machines,
including batteries. It has a form similar to `CC-PPPPPP-MMMMM-YMD-SSSS-FFF`
and contains the following information:

* Country code of origin (CC).
* Part number with the first character being a filling number (PPPPPP).
* Manufacture Identification (MMMMM).
* Manufacturing Year/Month/Date (YMD) in base 36, with Y being the last digit
  of the year.
* Manufacture Sequence Number (SSSS).
* Optional Firmware Version/Revision (FFF).

The `eppidtool <https://pypi.org/project/eppidtool>`_ python utility can be used
to decode and display this information.

All information regarding the Dell ePPID was gathered using Dell support
documentation and `this website <https://telcontar.net/KBK/Dell/date_codes>`_.

DDVWmiMethodFunction과 출력 형식

embedded binary MOF는 `bmfdec`로 해석할 수 있습니다. GUID `{8A42EA14-4F2A-FD45-6422-0087F7A7E608}`의 `DDVWmiMethodFunction`에는 battery 18종과 fan·thermal sensor 2종, 총 20개 method가 선언됩니다.

각 method는 32비트 index를 담은 ACPI buffer를 입력으로 받습니다. battery 관련 method에서는 처음 8비트가 battery를 지정합니다. 다른 method는 이 인수를 무시하거나 다른 방식으로 해석할 수 있습니다.

출력이 하나뿐이면 해당 type의 ACPI object를 반환하고, 출력이 여러 개이면 같은 순서로 담은 ACPI package를 반환합니다. 오류 때 malformed data를 반환하는 method가 많으므로 출력 형식을 철저히 검사해야 합니다.

여러 battery method의 data 형식은 Smart Battery Data Specification을 기반으로 한 것으로 보입니다. 따라서 알려지지 않은 battery method도 이 표준을 어느 정도 따를 가능성이 있습니다.

WMI interface description
=========================

The WMI interface description can be decoded from the embedded binary MOF (bmof)
data using the `bmfdec <https://github.com/pali/bmfdec>`_ utility:

::

 [WMI, Dynamic, Provider("WmiProv"), Locale("MS\\0x409"), Description("WMI Function"), guid("{8A42EA14-4F2A-FD45-6422-0087F7A7E608}")]
 class DDVWmiMethodFunction {
   [key, read] string InstanceName;
   [read] boolean Active;

   [WmiMethodId(1), Implemented, read, write, Description("Return Battery Design Capacity.")] void BatteryDesignCapacity([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(2), Implemented, read, write, Description("Return Battery Full Charge Capacity.")] void BatteryFullChargeCapacity([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(3), Implemented, read, write, Description("Return Battery Manufacture Name.")] void BatteryManufactureName([in] uint32 arg2, [out] string argr);
   [WmiMethodId(4), Implemented, read, write, Description("Return Battery Manufacture Date.")] void BatteryManufactureDate([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(5), Implemented, read, write, Description("Return Battery Serial Number.")] void BatterySerialNumber([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(6), Implemented, read, write, Description("Return Battery Chemistry Value.")] void BatteryChemistryValue([in] uint32 arg2, [out] string argr);
   [WmiMethodId(7), Implemented, read, write, Description("Return Battery Temperature.")] void BatteryTemperature([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(8), Implemented, read, write, Description("Return Battery Current.")] void BatteryCurrent([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(9), Implemented, read, write, Description("Return Battery Voltage.")] void BatteryVoltage([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(10), Implemented, read, write, Description("Return Battery Manufacture Access(MA code).")] void BatteryManufactureAceess([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(11), Implemented, read, write, Description("Return Battery Relative State-Of-Charge.")] void BatteryRelativeStateOfCharge([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(12), Implemented, read, write, Description("Return Battery Cycle Count")] void BatteryCycleCount([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(13), Implemented, read, write, Description("Return Battery ePPID")] void BatteryePPID([in] uint32 arg2, [out] string argr);
   [WmiMethodId(14), Implemented, read, write, Description("Return Battery Raw Analytics Start")] void BatteryeRawAnalyticsStart([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(15), Implemented, read, write, Description("Return Battery Raw Analytics")] void BatteryeRawAnalytics([in] uint32 arg2, [out] uint32 RawSize, [out, WmiSizeIs("RawSize") : ToInstance] uint8 RawData[]);
   [WmiMethodId(16), Implemented, read, write, Description("Return Battery Design Voltage.")] void BatteryDesignVoltage([in] uint32 arg2, [out] uint32 argr);
   [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[]);
   [WmiMethodId(18), Implemented, read, write, Description("Return Version.")] void ReturnVersion([in] uint32 arg2, [out] uint32 argr);
   [WmiMethodId(32), Implemented, read, write, Description("Return Fan Sensor Information")] void FanSensorInformation([in] uint32 arg2, [out] uint32 RawSize, [out, WmiSizeIs("RawSize") : ToInstance] uint8 RawData[]);
   [WmiMethodId(34), Implemented, read, write, Description("Return Thermal Sensor Information")] void ThermalSensorInformation([in] uint32 arg2, [out] uint32 RawSize, [out, WmiSizeIs("RawSize") : ToInstance] uint8 RawData[]);
 };

Each WMI method takes an ACPI buffer containing a 32-bit index as input argument,
with the first 8 bit being used to specify the battery when using battery-related
WMI methods. Other WMI methods may ignore this argument or interpret it
differently. The WMI method output format varies:

* if the function has only a single output, then an ACPI object
  of the corresponding type is returned
* if the function has multiple outputs, when an ACPI package
  containing the outputs in the same order is returned

The format of the output should be thoroughly checked, since many methods can
return malformed data in case of an error.

The data format of many battery-related methods seems to be based on the
`Smart Battery Data Specification`, so unknown battery-related methods are
likely to follow this standard in some way.

기본 battery 정보 method

설계 용량과 완전 충전 용량은 `u16` mAh, 제조사 이름과 chemistry는 ASCII 문자열, serial number는 `u16`으로 반환됩니다. 알려진 chemistry 값 `Li-I`는 Li-Ion을 뜻합니다.

제조일은 `u16` bit field입니다. bit 0~4는 일, bit 5~8은 월, bit 9~15는 1980을 bias로 한 연도입니다.

WMI method GetBatteryDesignCapacity()
-------------------------------------

Returns the design capacity of the battery in mAh as an u16.

WMI method BatteryFullCharge()
------------------------------

Returns the full charge capacity of the battery in mAh as an u16.

WMI method BatteryManufactureName()
-----------------------------------

Returns the manufacture name of the battery as an ASCII string.

WMI method BatteryManufactureDate()
-----------------------------------

Returns the manufacture date of the battery as an u16.
The date is encoded in the following manner:

- bits 0 to 4 contain the manufacture day.
- bits 5 to 8 contain the manufacture month.
- bits 9 to 15 contain the manufacture year biased by 1980.

WMI method BatterySerialNumber()
--------------------------------

Returns the serial number of the battery as an u16.

WMI method BatteryChemistryValue()
----------------------------------

Returns the chemistry of the battery as an ASCII string.
Known values are:

- "Li-I" for Li-Ion

온도·전류·전압과 health code

`BatteryTemperature`는 0.1 kelvin 단위 `u16`, `BatteryCurrent`는 mA 단위 `s16`, `BatteryVoltage`는 mV 단위 `u16`을 반환합니다. 전류가 음수이면 방전 중임을 뜻합니다.

`BatteryManufactureAccess`는 battery health를 `u16`으로 반환합니다. 세 번째 nibble은 일반 failure mode, 네 번째 nibble은 구체적인 failure code입니다. mode `0x9`는 permanent failure, `0xa`는 overheat, `0xb`는 overcurrent이며 다른 mode는 정상으로 간주합니다.

permanent failure일 때 failure code의 마지막 두 bit는 무시해야 합니다. 원문의 각 mode별 유효 code는 아래와 같습니다.

WMI method BatteryTemperature()
-------------------------------

Returns the temperature of the battery in tenth degree kelvin as an u16.

WMI method BatteryCurrent()
---------------------------

Returns the current flow of the battery in mA as an s16.
Negative values indicate discharging.

WMI method BatteryVoltage()
---------------------------

Returns the voltage flow of the battery in mV as an u16.

WMI method BatteryManufactureAccess()
-------------------------------------

Returns the health status of the battery as a u16.
The health status encoded in the following manner:

 - the third nibble contains the general failure mode
 - the fourth nibble contains the specific failure code

Valid failure modes are:

 - permanent failure (``0x9``)
 - overheat failure (``0xa``)
 - overcurrent failure (``0xb``)

All other failure modes are to be considered normal.

The following failure codes are valid for a permanent failure:

 - fuse blown (``0x0``)
 - cell imbalance (``0x1``)
 - overvoltage (``0x2``)
 - fet failure (``0x3``)

The last two bits of the failure code are to be ignored when the battery
signals a permanent failure.

The following failure codes a valid for a overheat failure:

 - overheat at start of charging (``0x5``)
 - overheat during charging (``0x7``)
 - overheat during discharging (``0x8``)

The following failure codes are valid for a overcurrent failure:

 - overcurrent during charging (``0x6``)
 - overcurrent during discharging (``0xb``)

충전 상태·cycle·battery ePPID

`BatteryRelativeStateOfCharge`는 battery 용량을 백분율 `u16`으로, `BatteryCycleCount`는 cycle 횟수를 `u16`으로 반환합니다. `BatteryePPID`는 battery ePPID를 ASCII 문자열로 반환합니다.

WMI method BatteryRelativeStateOfCharge()
-----------------------------------------

Returns the capacity of the battery in percent as an u16.

WMI method BatteryCycleCount()
------------------------------

Returns the cycle count of the battery as an u16.

WMI method BatteryePPID()
-------------------------

Returns the ePPID of the battery as an ASCII string.

battery raw analytics

`BatteryeRawAnalyticsStart`는 battery 분석을 수행하고 status를 반환합니다. `0x0`은 성공, `0x1`은 interface 미지원, `0xfffffffe`는 오류 또는 timeout입니다. 이 method의 구체적인 의미는 아직 대부분 알려지지 않았습니다.

`BatteryeRawAnalytics`는 보통 analytics data 12개 block이 든 buffer를 반환합니다. 각 block은 0부터 시작하는 `u8` block number와 의미를 알 수 없는 31바이트로 구성됩니다. 이 data의 의미도 아직 대부분 알려지지 않았습니다.

WMI method BatteryeRawAnalyticsStart()
--------------------------------------

Performs an analysis of the battery and returns a status code:

- ``0x0``: Success
- ``0x1``: Interface not supported
- ``0xfffffffe``: Error/Timeout

.. note::
   The meaning of this method is still largely unknown.

WMI method BatteryeRawAnalytics()
---------------------------------

Returns a buffer usually containing 12 blocks of analytics data.
Those blocks contain:

- a block number starting with 0 (u8)
- 31 bytes of unknown data

.. note::
   The meaning of this method is still largely unknown.

설계 전압·단일 analytics block·version

`BatteryDesignVoltage`는 설계 전압을 `u16` mV로 반환합니다. `BatteryeRawAnalyticsABlock`은 index의 두 번째 byte를 block number로 사용해 analytics data block 하나를 반환하며 WMI interface version 3부터 지원됩니다. block의 의미는 아직 대부분 알려지지 않았습니다.

`ReturnVersion`은 WMI interface version을 `u32`로 반환합니다.

WMI method BatteryDesignVoltage()
---------------------------------

Returns the design voltage of the battery in mV as an u16.

WMI method BatteryeRawAnalyticsABlock()
---------------------------------------

Returns a single block of analytics data, with the second byte
of the index being used for selecting the block number.

*Supported since WMI interface version 3!*

.. note::
   The meaning of this method is still largely unknown.

WMI method ReturnVersion()
--------------------------

Returns the WMI interface version as an u32.

fan·thermal sensor buffer

`FanSensorInformation`은 `0xff` 한 byte로 끝나는 fan sensor entry buffer를 반환합니다. 각 entry는 `u8` fan type과 little-endian `u16` RPM으로 구성됩니다.

`ThermalSensorInformation`도 `0xff`로 끝나는 entry buffer를 반환합니다. 각 entry는 `u8` thermal type, 현재·최소·최대 온도 `s8` 세 개, 의미가 알려지지 않은 `u8` 하나로 구성됩니다. 마지막 byte의 의미는 아직 조사 과제입니다.

WMI method FanSensorInformation()
---------------------------------

Returns a buffer containing fan sensor entries, terminated
with a single ``0xff``.
Those entries contain:

- fan type (u8)
- fan speed in RPM (little endian u16)

WMI method ThermalSensorInformation()
-------------------------------------

Returns a buffer containing thermal sensor entries, terminated
with a single ``0xff``.
Those entries contain:

- thermal type (u8)
- current temperature (s8)
- min. temperature (s8)
- max. temperature (s8)
- unknown field (u8)

.. note::
   TODO: Find out what the meaning of the last byte is.

ACPI battery index 매칭

ACPI battery를 DDV index에 연결하는 algorithm은 OEM software log 메시지에서 발견한 정보를 바탕으로 합니다.

새 ACPI battery마다 DDV index 1~3의 serial number를 ACPI battery serial과 비교합니다. ACPI serial은 일반 정수 또는 16진수로 encode될 수 있으므로 두 경우를 모두 검사하고, 처음 일치하는 index를 선택합니다.

serial number 0은 해당 index가 실제 battery와 연결되지 않았거나 연결된 battery가 없는 상태를 뜻합니다. Dell Inspiron 3505처럼 battery 하나만 지원해 index를 무시하는 장치도 있어 드라이버는 ACPI battery hook으로 battery를 발견합니다.

ACPI battery matching algorithm
===============================

The algorithm used to match ACPI batteries to indices is based on information
which was found inside the logging messages of the OEM software.

Basically for each new ACPI battery, the serial numbers of the batteries behind
indices 1 till 3 are compared with the serial number of the ACPI battery.
Since the serial number of the ACPI battery can either be encoded as a normal
integer or as a hexadecimal value, both cases need to be checked. The first
index with a matching serial number is then selected.

A serial number of 0 indicates that the corresponding index is not associated
with an actual battery, or that the associated battery is not present.

Some machines like the Dell Inspiron 3505 only support a single battery and thus
ignore the battery index. Because of this the driver depends on the ACPI battery
hook mechanism to discover batteries.

DDV WMI reverse engineering 절차

지원 Dell notebook에서 ACPI table을 dump하고 보통 `ADDV`라는 WMI 장치를 찾은 뒤, bmof를 decode하고 ASL code를 조사합니다. battery method는 `_BIX`나 `_BIF` 같은 다른 ACPI method의 control flow와 비교해 의미를 추론할 수 있습니다.

fan·thermal method는 내장 UEFI 진단의 sensor type과 값을 비교합니다. 일부 장치는 warm reset 때 static ACPI field를 다시 초기화하지 않으므로 field를 덮어써 다른 sensor type 값을 시험할 수도 있습니다.

대안으로 `dell-wmi-ddv` 드라이버를 필요하면 `force` module parameter와 함께 load하고 debugfs에서 raw fan·thermal buffer를 읽어 UEFI 진단과 비교할 수 있습니다.

지원되지 않는 DDV WMI version 또는 알려지지 않은 fan·thermal sensor를 발견하면 kernel bugzilla에 bug report를 제출해 드라이버에 추가할 수 있습니다. 자세한 보고 절차는 `Documentation/admin-guide/reporting-issues.rst`를 참고합니다.

Reverse-Engineering the DDV WMI interface
=========================================

1. Find a supported Dell notebook, usually made after ~2020.
2. Dump the ACPI tables and search for the WMI device (usually called "ADDV").
3. Decode the corresponding bmof data and look at the ASL code.
4. Try to deduce the meaning of a certain WMI method by comparing the control
   flow with other ACPI methods (_BIX or _BIF for battery related methods
   for example).
5. Use the built-in UEFI diagnostics to view sensor types/values for fan/thermal
   related methods (sometimes overwriting static ACPI data fields can be used
   to test different sensor type values, since on some machines this data is
   not reinitialized upon a warm reset).

Alternatively:

1. Load the ``dell-wmi-ddv`` driver, use the ``force`` module param
   if necessary.
2. Use the debugfs interface to access the raw fan/thermal sensor buffer data.
3. Compare the data with the built-in UEFI diagnostics.

In case the DDV WMI interface version available on your Dell notebook is not
supported or you are seeing unknown fan/thermal sensors, please submit a
bugreport on `bugzilla <https://bugzilla.kernel.org>`_ so they can be added
to the ``dell-wmi-ddv`` driver.

See Documentation/admin-guide/reporting-issues.rst for further information.