|
| 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 < [email protected]> |
| 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 |
0 commit comments