Linux HP WMI Sensors Driver

HP WMI sensor driver 개요

GPL-2.0-or-later인 Linux HP WMI Sensors Driver의 저작권은 2023 James Seo에게 있습니다.

Hewlett-Packard 및 일부 HP Compaq business-class computer는 Windows Management Instrumentation(WMI)을 통해 hardware monitoring 정보를 보고합니다. 이 드라이버는 해당 정보를 Linux hwmon subsystem에 노출하여 `sensors` 같은 userspace utility가 숫자 sensor reading을 수집할 수 있게 합니다.

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

.. include:: <isonum.txt>

===========================
Linux HP WMI Sensors Driver
===========================

:Copyright: |copy| 2023 James Seo <[email protected]>

Description
===========

Hewlett-Packard (and some HP Compaq) business-class computers report hardware
monitoring information via Windows Management Instrumentation (WMI).
This driver exposes that information to the Linux hwmon subsystem, allowing
userspace utilities like ``sensors`` to gather numeric sensor readings.

HP WMI sysfs attribute 표

Driver load 때 system의 sensor를 발견하고 필요한 attribute만 `/sys/class/hwmon/hwmon[X]`에 만듭니다. `[X]` 번호는 다른 system component에 따라 달라집니다.

Current는 `curr[X]_input`에서 mA로 읽고 `curr[X]_label`에서 label을 읽습니다. Fan은 `fan[X]_input` RPM, label, fault, alarm을 제공합니다. Voltage는 `in[X]_input` mV와 label을 제공합니다. Temperature는 `temp[X]_input` millidegree Celsius, label, fault, alarm을 제공합니다. `intrusion[X]_alarm`은 chassis intrusion indicator로 읽기·쓰기 가능합니다.

sysfs interface
===============

When the driver is loaded, it discovers the sensors available on the
system and creates the following sysfs attributes as necessary within
``/sys/class/hwmon/hwmon[X]``:

(``[X]`` is some number that depends on other system components.)

======================= ======= ===================================
Name                    Perm    Description
======================= ======= ===================================
``curr[X]_input``       RO      Current in milliamperes (mA).
``curr[X]_label``       RO      Current sensor label.
``fan[X]_input``        RO      Fan speed in RPM.
``fan[X]_label``        RO      Fan sensor label.
``fan[X]_fault``        RO      Fan sensor fault indicator.
``fan[X]_alarm``        RO      Fan sensor alarm indicator.
``in[X]_input``         RO      Voltage in millivolts (mV).
``in[X]_label``         RO      Voltage sensor label.
``temp[X]_input``       RO      Temperature in millidegrees Celsius
                                (m\ |deg|\ C).
``temp[X]_label``       RO      Temperature sensor label.
``temp[X]_fault``       RO      Temperature sensor fault indicator.
``temp[X]_alarm``       RO      Temperature sensor alarm indicator.
``intrusion[X]_alarm``  RW      Chassis intrusion alarm indicator.
======================= ======= ===================================

Fault·alarm 의미와 reset

Sensor의 `fault` attribute가 0 대신 1이면 동작 중 문제가 발생해 측정값을 신뢰하면 안 됩니다. Sensor가 이후 회복하면 다시 0을 반환합니다.

`alarm=1`의 의미는 type에 따라 다릅니다. Fan은 회전 중 stall 또는 disconnect, temperature는 system별 critical threshold 도달, intrusion은 chassis가 열린 상태를 뜻합니다.

Alarm attribute에서 1을 읽으면 스스로 reset되어 이후 read는 0을 반환합니다. 예외로 `intrusion[X]_alarm`은 0을 직접 써야만 reset됩니다.

``fault`` attributes
  Reading ``1`` instead of ``0`` as the ``fault`` attribute for a sensor
  indicates that it has encountered some issue during operation such that
  measurements from it should not be trusted. If a sensor with the fault
  condition recovers later, reading this attribute will return ``0`` again.

``alarm`` attributes
  Reading ``1`` instead of ``0`` as the ``alarm`` attribute for a sensor
  indicates that one of the following has occurred, depending on its type:

  - ``fan``: The fan has stalled or has been disconnected while running.
  - ``temp``: The sensor reading has reached a critical threshold.
    The exact threshold is system-dependent.
  - ``intrusion``: The system's chassis has been opened.

  After ``1`` is read from an ``alarm`` attribute, the attribute resets itself
  and returns ``0`` on subsequent reads. As an exception, an
  ``intrusion[X]_alarm`` can only be manually reset by writing ``0`` to it.

Debugfs 전체 sensor object

Debugfs interface는 예고 없이 바뀔 수 있으며 kernel이 `CONFIG_DEBUG_FS`로 build된 경우에만 사용할 수 있습니다.

표준 hwmon sysfs는 driver 초기화 시 연결된 일반 type sensor만 노출합니다. WMI에는 이 조건을 충족하지 않는 다른 sensor와 alarm용 system-dependent platform events object가 있을 수 있으므로 debugfs는 사용 가능한 모든 HP WMI sensor와 platform event를 읽기 전용으로 제공합니다.

`/sys/kernel/debug/hp-wmi-sensors-[X]/sensor`에는 sensor마다 번호 entry가 있고 `name`, `description`, `sensor_type`, `other_sensor_type`, `operational_status`, `possible_states`, `current_state`, `base_units`, `unit_modifier`, `current_reading`, 일부 system의 `rate_units`가 있습니다.

debugfs interface
=================

.. warning:: The debugfs interface is subject to change without notice
             and is only available when the kernel is compiled with
             ``CONFIG_DEBUG_FS`` defined.

The standard hwmon interface in sysfs exposes sensors of several common types
that are connected as of driver initialization. However, there are usually
other sensors in WMI that do not meet these criteria. In addition, a number of
system-dependent "platform events objects" used for ``alarm`` attributes may
be present. A debugfs interface is therefore provided for read-only access to
all available HP WMI sensors and platform events objects.

``/sys/kernel/debug/hp-wmi-sensors-[X]/sensor``
contains one numbered entry per sensor with the following attributes:

=============================== =======================================
Name                            Example
=============================== =======================================
``name``                        ``CPU0 Fan``
``description``                 ``Reports CPU0 fan speed``
``sensor_type``                 ``12``
``other_sensor_type``           (an empty string)
``operational_status``          ``2``
``possible_states``             ``Normal,Caution,Critical,Not Present``
``current_state``               ``Normal``
``base_units``                  ``19``
``unit_modifier``               ``0``
``current_reading``             ``1008``
``rate_units``                  ``0`` (only exists on some systems)
=============================== =======================================

Debugfs platform event object

Platform events object가 있으면 `/sys/kernel/debug/hp-wmi-sensors-[X]/platform_events`에 object마다 번호 entry가 생성됩니다. 각 entry는 `name`, `description`, `source_namespace`, `source_class`, `category`, `possible_severity`, `possible_status`를 제공합니다.

예시는 `CPU0 Fan Stall`, `CPU0 Fan Speed`, namespace `root\wmi`, class `HPBIOS_BIOSEvent`, category 3, possible severity 25, possible status 5입니다.

이 값들은 system마다 달라지는 underlying `HPBIOS_BIOSNumericSensor`와 `HPBIOS_PlatformEvents` WMI object의 property입니다. 자세한 내용과 Managed Object Format(MOF) 정의는 참조 문서를 확인해야 합니다.

If platform events objects are available,
``/sys/kernel/debug/hp-wmi-sensors-[X]/platform_events``
contains one numbered entry per object with the following attributes:

=============================== ====================
Name                            Example
=============================== ====================
``name``                        ``CPU0 Fan Stall``
``description``                 ``CPU0 Fan Speed``
``source_namespace``            ``root\wmi``
``source_class``                ``HPBIOS_BIOSEvent``
``category``                    ``3``
``possible_severity``           ``25``
``possible_status``             ``5``
=============================== ====================

These represent the properties of the underlying ``HPBIOS_BIOSNumericSensor``
and ``HPBIOS_PlatformEvents`` WMI objects, which vary between systems.
See [#]_ for more details and Managed Object Format (MOF) definitions.

알려진 제한과 참고 문서

Non-business-class HP용 기존 `hp-wmi` driver가 이미 load되어 있으면 지원 system에서도 alarm attribute를 사용할 수 없습니다. 두 driver가 같은 WMI event GUID를 사용하며 다른 system에서는 laptop hotkey 등에 쓰이기 때문입니다.

의심스러운 sensor hardware와 일관되지 않은 BIOS WMI 구현은 부정확한 reading, alarm 미발생, boot당 한 번만 발생하는 alarm 같은 이상 동작을 일으킬 수 있습니다.

실제 관찰된 type은 temperature, fan speed, intrusion뿐이어서 voltage와 current 지원은 잠정적입니다. HP WMI sensor가 어떤 type을 주장할 수 있더라도 hwmon이 모르는 특수 sensor type은 지원하지 않습니다.

참고 자료는 Hewlett-Packard Development Company의 2005년 `HP Client Management Interface Technical White Paper`이며 원문 URL에서 제공합니다.

Known issues and limitations
============================

- If the existing hp-wmi driver for non-business-class HP systems is already
  loaded, ``alarm`` attributes will be unavailable even on systems that
  support them. This is because the same WMI event GUID used by this driver
  for ``alarm`` attributes is used on those systems for e.g. laptop hotkeys.
- Dubious sensor hardware and inconsistent BIOS WMI implementations have been
  observed to cause inaccurate readings and peculiar behavior, such as alarms
  failing to occur or occurring only once per boot.
- Only temperature, fan speed, and intrusion sensor types have been seen in
  the wild so far. Support for voltage and current sensors is therefore
  provisional.
- Although HP WMI sensors may claim to be of any type, any oddball sensor
  types unknown to hwmon will not be supported.

References
==========

.. [#] Hewlett-Packard Development Company, L.P.,
       "HP Client Management Interface Technical White Paper", 2005. [Online].
       Available: https://h20331.www2.hp.com/hpsub/downloads/cmi_whitepaper.pdf