1.. SPDX-License-Identifier: GPL-2.0-or-later 2 3.. include:: <isonum.txt> 4 5=========================== 6Linux HP WMI Sensors Driver 7=========================== 8 9:Copyright: |copy| 2023 James Seo <james@equiv.tech> 10 11Description 12=========== 13 14Hewlett-Packard (and some HP Compaq) business-class computers report hardware 15monitoring information via Windows Management Instrumentation (WMI). 16This driver exposes that information to the Linux hwmon subsystem, allowing 17userspace utilities like ``sensors`` to gather numeric sensor readings. 18 19sysfs interface 20=============== 21 22When the driver is loaded, it discovers the sensors available on the 23system 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======================= ======= =================================== 29Name 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 66debugfs 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 73The standard hwmon interface in sysfs exposes sensors of several common types 74that are connected as of driver initialization. However, there are usually 75other sensors in WMI that do not meet these criteria. In addition, a number of 76system-dependent "platform events objects" used for ``alarm`` attributes may 77be present. A debugfs interface is therefore provided for read-only access to 78all available HP WMI sensors and platform events objects. 79 80``/sys/kernel/debug/hp-wmi-sensors-[X]/sensor`` 81contains one numbered entry per sensor with the following attributes: 82 83=============================== ======================================= 84Name 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 99If platform events objects are available, 100``/sys/kernel/debug/hp-wmi-sensors-[X]/platform_events`` 101contains one numbered entry per object with the following attributes: 102 103=============================== ==================== 104Name 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 115These represent the properties of the underlying ``HPBIOS_BIOSNumericSensor`` 116and ``HPBIOS_PlatformEvents`` WMI objects, which vary between systems. 117See [#]_ for more details and Managed Object Format (MOF) definitions. 118 119Known 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 135References 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 141