Skip to contentSkip to conversation

Documentation/hwmon: Document hwmon_notify_event()

PATCH In review Guenter Roeck 3 participants 3 messages Aug 21

Subsystems (2)
lore
Share & tools
lore

Guenter Roeck

author maintainer
#0 lore raw

PATCH 1/1 Documentation/hwmon: Document hwmon_notify_event()

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 <[email protected]>
Fixes 1597b374af222 ("hwmon: Add notification support")
---
 Documentation/hwmon/hwmon-kernel-api.rst | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
Documentation/hwmon/hwmon-kernel-api.rst +15 -0
index 9fcde32a140d..c3eb433a78f6 100644
@@ -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()
 --------------------------------------------
 
Signature · 1 line
2.45.2
#1 lore raw
Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:

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

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.

Quoted 5 lines
Documentation/hwmon/hwmon-kernel-api.rst +0 -0
index 9fcde32a140df..c3eb433a78f61 100644

Documentation/hwmon/hwmon-kernel-api.rst register/unregister functions:: · line 50

Quoted 9 lines
Documentation/hwmon/hwmon-kernel-api.rst +3 -0
@@ -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?

Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=1
Reviewed-by on v1 1/1
#2 lore raw
In reply to Guenter Roeck
Quoted 6 lines · 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.

Quoted 6 lines

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

Cc Kalesh AP <[email protected]>
Fixes 1597b374af222 ("hwmon: Add notification support")
Signature · 2 lines
Regards,
Kalesh AP