hwmon: add HP WMI Sensors driver

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

.. include:: <isonum.txt>

===========================

Linux HP WMI Sensors Driver

===========================

:Copyright: |copy| 2023 James Seo <james@equiv.tech>

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.

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`` 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 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)

=============================== =======================================

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.

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

   gl518sm

   gxp-fan-ctrl

   hih6130

   hp-wmi-sensors

   ibmaem

   ibm-cffps

   ibmpowernv

S:	Orphan

F:	drivers/platform/x86/hp/tc1100-wmi.c

HP WMI HARDWARE MONITOR DRIVER

M:	James Seo <james@equiv.tech>

L:	linux-hwmon@vger.kernel.org

S:	Maintained

F:	Documentation/hwmon/hp-wmi-sensors.rst

F:	drivers/hwmon/hp-wmi-sensors.c

HPET:	High Precision Event Timers driver

M:	Clemens Ladisch <clemens@ladisch.de>

S:	Maintained

	  This driver can also be built as a module. If so, the module

	  will be called asus_ec_sensors.

config SENSORS_HP_WMI

	tristate "HP WMI Sensors"

	depends on ACPI_WMI

	help

	  If you say yes here you get support for the ACPI hardware monitoring

	  interface found in HP (and some HP Compaq) business-class computers.

	  Available sensors vary between systems. Temperature and fan speed

	  sensors are the most common.

	  This driver can also be built as a module. If so, the module

	  will be called hp_wmi_sensors.

endif # ACPI

endif # HWMON

obj-$(CONFIG_SENSORS_ATK0110)	+= asus_atk0110.o

obj-$(CONFIG_SENSORS_ASUS_EC)	+= asus-ec-sensors.o

obj-$(CONFIG_SENSORS_ASUS_WMI)	+= asus_wmi_sensors.o

obj-$(CONFIG_SENSORS_HP_WMI)	+= hp-wmi-sensors.o

# Native drivers

# asb100, then w83781d go first, as they can override other drivers' addresses.