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