Documentation/hwmon/hp-wmi-sensors.rst

   1 .. SPDX-License-Identifier: GPL-2.0-or-later
   2
   3 .. include:: <isonum.txt>
   4
   5 ===========================
   6 Linux HP WMI Sensors Driver
   7 ===========================
   8
   9 :Copyright: |copy| 2023 James Seo <james@equiv.tech>
  10
  11 Description
  12 ===========
  13
  14 Hewlett-Packard (and some HP Compaq) business-class computers report hardware
  15 monitoring information via Windows Management Instrumentation (WMI).
  16 This driver exposes that information to the Linux hwmon subsystem, allowing
  17 userspace utilities like ``sensors`` to gather numeric sensor readings.
  18
  19 sysfs interface
  20 ===============
  21
  22 When the driver is loaded, it discovers the sensors available on the
  23 system and creates the following sysfs attributes as necessary within
  24 ``/sys/class/hwmon/hwmon[X]``:
  25
  26 (``[X]`` is some number that depends on other system components.)
  27
  28 ======================= ======= ===================================
  29 Name                    Perm    Description
  30 ======================= ======= ===================================
  31 ``curr[X]_input``       RO      Current in milliamperes (mA).
  32 ``curr[X]_label``       RO      Current sensor label.
  33 ``fan[X]_input``        RO      Fan speed in RPM.
  34 ``fan[X]_label``        RO      Fan sensor label.
  35 ``fan[X]_fault``        RO      Fan sensor fault indicator.
  36 ``fan[X]_alarm``        RO      Fan sensor alarm indicator.
  37 ``in[X]_input``         RO      Voltage in millivolts (mV).
  38 ``in[X]_label``         RO      Voltage sensor label.
  39 ``temp[X]_input``       RO      Temperature in millidegrees Celsius
  40                                 (m\ |deg|\ C).
  41 ``temp[X]_label``       RO      Temperature sensor label.
  42 ``temp[X]_fault``       RO      Temperature sensor fault indicator.
  43 ``temp[X]_alarm``       RO      Temperature sensor alarm indicator.
  44 ``intrusion[X]_alarm``  RW      Chassis intrusion alarm indicator.
  45 ======================= ======= ===================================
  46
  47 ``fault`` attributes
  48   Reading ``1`` instead of ``0`` as the ``fault`` attribute for a sensor
  49   indicates that it has encountered some issue during operation such that
  50   measurements from it should not be trusted. If a sensor with the fault
  51   condition recovers later, reading this attribute will return ``0`` again.
  52
  53 ``alarm`` attributes
  54   Reading ``1`` instead of ``0`` as the ``alarm`` attribute for a sensor
  55   indicates that one of the following has occurred, depending on its type:
  56
  57   - ``fan``: The fan has stalled or has been disconnected while running.
  58   - ``temp``: The sensor reading has reached a critical threshold.
  59     The exact threshold is system-dependent.
  60   - ``intrusion``: The system's chassis has been opened.
  61
  62   After ``1`` is read from an ``alarm`` attribute, the attribute resets itself
  63   and returns ``0`` on subsequent reads. As an exception, an
  64   ``intrusion[X]_alarm`` can only be manually reset by writing ``0`` to it.
  65
  66 debugfs interface
  67 =================
  68
  69 .. warning:: The debugfs interface is subject to change without notice
  70              and is only available when the kernel is compiled with
  71              ``CONFIG_DEBUG_FS`` defined.
  72
  73 The standard hwmon interface in sysfs exposes sensors of several common types
  74 that are connected as of driver initialization. However, there are usually
  75 other sensors in WMI that do not meet these criteria. In addition, a number of
  76 system-dependent "platform events objects" used for ``alarm`` attributes may
  77 be present. A debugfs interface is therefore provided for read-only access to
  78 all available HP WMI sensors and platform events objects.
  79
  80 ``/sys/kernel/debug/hp-wmi-sensors-[X]/sensor``
  81 contains one numbered entry per sensor with the following attributes:
  82
  83 =============================== =======================================
  84 Name                            Example
  85 =============================== =======================================
  86 ``name``                        ``CPU0 Fan``
  87 ``description``                 ``Reports CPU0 fan speed``
  88 ``sensor_type``                 ``12``
  89 ``other_sensor_type``           (an empty string)
  90 ``operational_status``          ``2``
  91 ``possible_states``             ``Normal,Caution,Critical,Not Present``
  92 ``current_state``               ``Normal``
  93 ``base_units``                  ``19``
  94 ``unit_modifier``               ``0``
  95 ``current_reading``             ``1008``
  96 ``rate_units``                  ``0`` (only exists on some systems)
  97 =============================== =======================================
  98
  99 If platform events objects are available,
 100 ``/sys/kernel/debug/hp-wmi-sensors-[X]/platform_events``
 101 contains one numbered entry per object with the following attributes:
 102
 103 =============================== ====================
 104 Name                            Example
 105 =============================== ====================
 106 ``name``                        ``CPU0 Fan Stall``
 107 ``description``                 ``CPU0 Fan Speed``
 108 ``source_namespace``            ``root\wmi``
 109 ``source_class``                ``HPBIOS_BIOSEvent``
 110 ``category``                    ``3``
 111 ``possible_severity``           ``25``
 112 ``possible_status``             ``5``
 113 =============================== ====================
 114
 115 These represent the properties of the underlying ``HPBIOS_BIOSNumericSensor``
 116 and ``HPBIOS_PlatformEvents`` WMI objects, which vary between systems.
 117 See [#]_ for more details and Managed Object Format (MOF) definitions.
 118
 119 Known issues and limitations
 120 ============================
 121
 122 - If the existing hp-wmi driver for non-business-class HP systems is already
 123   loaded, ``alarm`` attributes will be unavailable even on systems that
 124   support them. This is because the same WMI event GUID used by this driver
 125   for ``alarm`` attributes is used on those systems for e.g. laptop hotkeys.
 126 - Dubious sensor hardware and inconsistent BIOS WMI implementations have been
 127   observed to cause inaccurate readings and peculiar behavior, such as alarms
 128   failing to occur or occurring only once per boot.
 129 - Only temperature, fan speed, and intrusion sensor types have been seen in
 130   the wild so far. Support for voltage and current sensors is therefore
 131   provisional.
 132 - Although HP WMI sensors may claim to be of any type, any oddball sensor
 133   types unknown to hwmon will not be supported.
 134
 135 References
 136 ==========
 137
 138 .. [#] Hewlett-Packard Development Company, L.P.,
 139        "HP Client Management Interface Technical White Paper", 2005. [Online].
 140        Available: https://h20331.www2.hp.com/hpsub/downloads/cmi_whitepaper.pdf