[PATCH] Documentation/hwmon: Document hwmon_notify_event()

[PATCH] Documentation/hwmon: Document hwmon_notify_event()

[Guenter Roeck]

The hwmon core provides hwmon_notify_event() for drivers to report events
such as alarm or fault conditions to userspace via sysfs notifications
and uevents, as well as to the thermal subsystem for temperature sensors.
However, this function is not documented in the hwmon kernel API guide.

Add the function prototype and description of hwmon_notify_event() to
Documentation/hwmon/hwmon-kernel-api.rst.

Cc: Kalesh AP <kalesh-anakkur.purayil@broadcom.com>
Fixes: 1597b374af222 ("hwmon: Add notification support")
Signed-off-by: Guenter Roeck <linux@roeck-us.net>
---
 Documentation/hwmon/hwmon-kernel-api.rst | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/hwmon/hwmon-kernel-api.rst b/Documentation/hwmon/hwmon-kernel-api.rst
index 9fcde32a140d..c3eb433a78f6 100644
--- a/Documentation/hwmon/hwmon-kernel-api.rst
+++ b/Documentation/hwmon/hwmon-kernel-api.rst
@@ -42,6 +42,9 @@ register/unregister functions::
 
   char *devm_hwmon_sanitize_name(struct device *dev, const char *name);
 
+  int hwmon_notify_event(struct device *dev, enum hwmon_sensor_types type,
+			 u32 attr, int channel);
+
   void hwmon_lock(struct device *dev);
   void hwmon_unlock(struct device *dev);
 
@@ -90,6 +93,18 @@ implemented in the driver, or debugfs functions, hwmon_lock() and hwmon_unlock()
 can be used to ensure that calls to those functions are serialized. Those
 functions also support guard() and scoped_guard() variants.
 
+Drivers can call hwmon_notify_event() to notify userspace and the thermal
+subsystem when a hardware monitoring event (such as an alarm or a fault
+condition) occurs or clears. The parameters are the hwmon device, the sensor
+type, the attribute identifier associated with the event (such as
+hwmon_temp_max_alarm or hwmon_fan_fault), and the sensor channel number.
+hwmon_notify_event() generates a sysfs event (calling sysfs_notify()) and a
+udev event with the attribute name passed in the NAME environment property
+(e.g., "NAME=temp1_max_alarm"). If the event is for a temperature sensor and
+the sensor is attached to a thermal zone, it also notifies the thermal
+subsystem to update the thermal zone. hwmon_notify_event() returns 0 on
+success or a negative error code on failure.
+
 Using devm_hwmon_device_register_with_info()
 --------------------------------------------
 
-- 
2.45.2

Re: [PATCH] Documentation/hwmon: Document hwmon_notify_event()

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:

Pre-existing issues:
- [High] The pec_store() function violates subsystem cleanup guidelines by mixing guard() lock acquisition with goto-based error handling, resulting in a Use-After-Free vulnerability.
--

--- Patch [1]: [PATCH] Documentation/hwmon: Document hwmon_notify_event() ---
commit 2b10b27f5fc8a96731a2e5192ecb3af70d5ee8cc
Author: Guenter Roeck <linux@roeck-us.net>

Documentation/hwmon: Document hwmon_notify_event()

Add the function prototype and description of hwmon_notify_event() to
the hwmon kernel API guide. This allows drivers to report events such as
alarms or faults to userspace.

> diff --git a/Documentation/hwmon/hwmon-kernel-api.rst b/Documentation/hwmon/hwmon-kernel-api.rst
> index 9fcde32a140df..c3eb433a78f61 100644
> --- a/Documentation/hwmon/hwmon-kernel-api.rst
> +++ b/Documentation/hwmon/hwmon-kernel-api.rst
> @@ -42,6 +42,9 @@ register/unregister functions::
>  
>    char *devm_hwmon_sanitize_name(struct device *dev, const char *name);
>  
> +  int hwmon_notify_event(struct device *dev, enum hwmon_sensor_types type,
> +			 u32 attr, int channel);
> +
>    void hwmon_lock(struct device *dev);
>    void hwmon_unlock(struct device *dev);
>  

[ ... ]

This is a pre-existing issue, but while reviewing the hwmon subsystem I noticed
a potential bug in drivers/hwmon/hwmon.c:

[Severity: High]
Can this sequence trigger a use-after-free?

Looking at pec_store() in drivers/hwmon/hwmon.c, we acquire a device reference
and lock, but mix it with a goto statement for error handling:

drivers/hwmon/hwmon.c:pec_store() {
        ...
        hdev = device_find_child(dev, NULL, hwmon_match_device);
        ...
        hwdev = to_hwmon_device(hdev);
        guard(mutex)(&hwdev->lock);
        if (hwdev->chip->ops->write) {
                err = hwdev->chip->ops->write(hdev, hwmon_chip, hwmon_chip_pec, 0, val);
                if (err && err != -EOPNOTSUPP)
                        goto put;
        }
        ...
put:
        put_device(hdev);

        return err;
}

If the put_device(hdev) call drops the last reference to the device (for
example, due to a concurrent device removal), it triggers hwmon_dev_release()
which frees the hwdev memory.

When the function returns, the guard scope exits and attempts to call
mutex_unlock() on the saved hwdev->lock pointer, dereferencing the freshly
freed memory.

Could this be converted to use scoped_guard() or avoid the goto statement to
ensure the lock is released before dropping the device reference?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260821045136.664480-1-linux@roeck-us.net?part=1

Re: [PATCH] Documentation/hwmon: Document hwmon_notify_event()

[Kalesh Anakkur Purayil]

[-- Attachment #1: Type: text/plain, Size: 768 bytes --]

On Fri, Aug 21, 2026 at 10:21 AM Guenter Roeck <linux@roeck-us.net> wrote:
>
> The hwmon core provides hwmon_notify_event() for drivers to report events
> such as alarm or fault conditions to userspace via sysfs notifications
> and uevents, as well as to the thermal subsystem for temperature sensors.
> However, this function is not documented in the hwmon kernel API guide.
>
> Add the function prototype and description of hwmon_notify_event() to
> Documentation/hwmon/hwmon-kernel-api.rst.
>
> Cc: Kalesh AP <kalesh-anakkur.purayil@broadcom.com>
> Fixes: 1597b374af222 ("hwmon: Add notification support")
> Signed-off-by: Guenter Roeck <linux@roeck-us.net>

Reviewed-by: Kalesh AP <kalesh-anakkur.purayil@broadcom.com>

-- 
Regards,
Kalesh AP

[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 5509 bytes --]