[PATCH 0/3] regulator: userspace-consumer: Add regulator event uevents

[PATCH 0/3] regulator: userspace-consumer: Add regulator event uevents

[Johann Neuhauser]

This series adds support for regulator event reporting via uevents to the
userspace-consumer regulator driver. The goal is to provide userspace with
a straightforward mechanism to monitor and respond to important regulator
events such as overcurrent conditions, voltage changes, and enable/disable
transitions.

Signed-off-by: Johann Neuhauser <jneuhauser@dh-electronics.com>
---
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Liam Girdwood <lgirdwood@gmail.com>
Cc: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Cc: Mark Brown <broonie@kernel.org>
---
Johann Neuhauser (3):
  regulator: userspace-consumer: Add uevent reporting for regulator
    events
  ABI: sysfs-platform: Document uevent ABI for reg-userspace-consumer
  docs: regulator: userspace-consumer: Add uevent-based regulator event
    reporting

 ...ysfs-platform-regulator-userspace-consumer | 23 +++++
 .../regulator/userspace-consumer.rst          | 92 +++++++++++++++++++
 drivers/regulator/userspace-consumer.c        | 74 ++++++++++++++-
 3 files changed, 188 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/ABI/testing/sysfs-platform-regulator-userspace-consumer
 create mode 100644 Documentation/driver-api/regulator/userspace-consumer.rst

-- 
2.39.5

[PATCH 1/3] regulator: userspace-consumer: Add uevent reporting for regulator events

[Johann Neuhauser]

Generate uevents when regulator events such as voltage changes, overcurrent,
or enable/disable transitions occur. A separate uevent is emitted for each
individual regulator event bit, allowing precise event handling in userspace
via udev rules.

The emitted uevent key `EVENT=` corresponds directly to the event types defined
in include/uapi/regulator/regulator.h.

This provides a flexible, user-friendly mechanism to monitor and handle
regulator events from userspace.

Signed-off-by: Johann Neuhauser <jneuhauser@dh-electronics.com>
---
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Liam Girdwood <lgirdwood@gmail.com>
Cc: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Cc: Mark Brown <broonie@kernel.org>
---
 drivers/regulator/userspace-consumer.c | 74 +++++++++++++++++++++++++-
 1 file changed, 73 insertions(+), 1 deletion(-)

diff --git a/drivers/regulator/userspace-consumer.c b/drivers/regulator/userspace-consumer.c
index 72bb5ffb49a8..01cf07d42682 100644
--- a/drivers/regulator/userspace-consumer.c
+++ b/drivers/regulator/userspace-consumer.c
@@ -11,6 +11,7 @@
  *   Author: Mark Brown <broonie@opensource.wolfsonmicro.com>
  */
 
+#include <linux/bitops.h>
 #include <linux/err.h>
 #include <linux/mutex.h>
 #include <linux/module.h>
@@ -29,6 +30,9 @@ struct userspace_consumer_data {
 
 	int num_supplies;
 	struct regulator_bulk_data *supplies;
+
+	struct kobject *kobj;
+	struct notifier_block nb;
 };
 
 static ssize_t name_show(struct device *dev,
@@ -115,12 +119,68 @@ static const struct attribute_group attr_group = {
 	.is_visible =  attr_visible,
 };
 
+/*
+ * This should probably be placed elsewhere in the regulator framework...
+ */
+static const char *regulator_event_str(unsigned long event)
+{
+	switch (event) {
+	case REGULATOR_EVENT_ABORT_DISABLE:
+		return "ABORT_DISABLE";
+	case REGULATOR_EVENT_ABORT_VOLTAGE_CHANGE:
+		return "ABORT_VOLTAGE_CHANGE";
+	case REGULATOR_EVENT_DISABLE:
+		return "DISABLE";
+	case REGULATOR_EVENT_ENABLE:
+		return "ENABLE";
+	case REGULATOR_EVENT_FAIL:
+		return "FAIL";
+	case REGULATOR_EVENT_FORCE_DISABLE:
+		return "FORCE_DISABLE";
+	case REGULATOR_EVENT_OVER_CURRENT:
+		return "OVER_CURRENT";
+	case REGULATOR_EVENT_OVER_TEMP:
+		return "OVER_TEMP";
+	case REGULATOR_EVENT_PRE_DISABLE:
+		return "PRE_DISABLE";
+	case REGULATOR_EVENT_PRE_VOLTAGE_CHANGE:
+		return "PRE_VOLTAGE_CHANGE";
+	case REGULATOR_EVENT_REGULATION_OUT:
+		return "REGULATION_OUT";
+	case REGULATOR_EVENT_UNDER_VOLTAGE:
+		return "UNDER_VOLTAGE";
+	case REGULATOR_EVENT_VOLTAGE_CHANGE:
+		return "VOLTAGE_CHANGE";
+	default:
+		return NULL;
+	}
+}
+
+static int regulator_userspace_notify(struct notifier_block *nb, unsigned long event, void *unused)
+{
+	struct userspace_consumer_data *drvdata = container_of(nb, struct userspace_consumer_data, nb);
+	char env_buf[128];
+	char *envp[] = { "NAME=event", env_buf, NULL };
+	unsigned int bit;
+
+	for_each_set_bit(bit, &event, BITS_PER_TYPE(event)) {
+		const char *event_str = regulator_event_str(BIT(bit));
+
+		if (event_str && event_str[0] != '\0') {
+			scnprintf(env_buf, sizeof(env_buf), "EVENT=%s", event_str);
+			kobject_uevent_env(drvdata->kobj, KOBJ_CHANGE, envp);
+		}
+	}
+
+	return NOTIFY_OK;
+}
+
 static int regulator_userspace_consumer_probe(struct platform_device *pdev)
 {
 	struct regulator_userspace_consumer_data tmpdata;
 	struct regulator_userspace_consumer_data *pdata;
 	struct userspace_consumer_data *drvdata;
-	int ret;
+	int i, ret;
 
 	pdata = dev_get_platdata(&pdev->dev);
 	if (!pdata) {
@@ -153,6 +213,7 @@ static int regulator_userspace_consumer_probe(struct platform_device *pdev)
 	drvdata->num_supplies = pdata->num_supplies;
 	drvdata->supplies = pdata->supplies;
 	drvdata->no_autoswitch = pdata->no_autoswitch;
+	drvdata->kobj = &pdev->dev.kobj;
 
 	mutex_init(&drvdata->lock);
 
@@ -184,6 +245,13 @@ static int regulator_userspace_consumer_probe(struct platform_device *pdev)
 	}
 	drvdata->enabled = !!ret;
 
+	drvdata->nb.notifier_call = regulator_userspace_notify;
+	for (i = 0; i < drvdata->num_supplies; i++) {
+		ret = devm_regulator_register_notifier(drvdata->supplies[i].consumer, &drvdata->nb);
+		if (ret)
+			goto err_enable;
+	}
+
 	return 0;
 
 err_enable:
@@ -195,6 +263,10 @@ static int regulator_userspace_consumer_probe(struct platform_device *pdev)
 static void regulator_userspace_consumer_remove(struct platform_device *pdev)
 {
 	struct userspace_consumer_data *data = platform_get_drvdata(pdev);
+	int i;
+
+	for (i = 0; i < data->num_supplies; i++)
+		devm_regulator_unregister_notifier(data->supplies[i].consumer, &data->nb);
 
 	sysfs_remove_group(&pdev->dev.kobj, &attr_group);
 
-- 
2.39.5

[PATCH 2/3] ABI: sysfs-platform: Document uevent ABI for reg-userspace-consumer

[Johann Neuhauser]

Document the new uevent-based ABI provided by the userspace-consumer
regulator driver. These uevents expose regulator events such as OVER_CURRENT,
ENABLE, DISABLE, UNDER_VOLTAGE, and others to userspace.

Clearly describe the ABI entries and possible event values to ensure stable
and predictable userspace integration.

Signed-off-by: Johann Neuhauser <jneuhauser@dh-electronics.com>
---
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Liam Girdwood <lgirdwood@gmail.com>
Cc: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Cc: Mark Brown <broonie@kernel.org>
---
 ...ysfs-platform-regulator-userspace-consumer | 23 +++++++++++++++++++
 1 file changed, 23 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-platform-regulator-userspace-consumer

diff --git a/Documentation/ABI/testing/sysfs-platform-regulator-userspace-consumer b/Documentation/ABI/testing/sysfs-platform-regulator-userspace-consumer
new file mode 100644
index 000000000000..2d518afb0d32
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-platform-regulator-userspace-consumer
@@ -0,0 +1,23 @@
+What:		/devices/platform/<device>/uevent EVENT=
+Date:		April 2025
+Contact:	Johann Neuhauser <jneuhauser@dh-electronics.com>
+Description:
+		Reports regulator events via uevents for platform devices
+		controlled by the userspace-consumer regulator driver.
+		
+		Possible EVENT= values:
+		 - ABORT_DISABLE
+		 - ABORT_VOLTAGE_CHANGE
+		 - DISABLE
+		 - ENABLE
+		 - FAIL
+		 - FORCE_DISABLE
+		 - OVER_CURRENT
+		 - OVER_TEMP
+		 - PRE_DISABLE
+		 - PRE_VOLTAGE_CHANGE
+		 - REGULATION_OUT
+		 - UNDER_VOLTAGE
+		 - VOLTAGE_CHANGE
+
+Userspace can monitor these events using udev and respond accordingly.
-- 
2.39.5

[PATCH 3/3] docs: regulator: userspace-consumer: Add uevent-based regulator event reporting

[Johann Neuhauser]

Add detailed documentation for the new uevent-based event reporting
introduced in the regulator userspace-consumer driver.

This documentation explains:
- The new supported regulator events exposed via uevents.
- Methods to monitor these events from userspace using `udevadm`.
- Practical examples for creating udev rules and scripts.

Signed-off-by: Johann Neuhauser <jneuhauser@dh-electronics.com>
---
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Liam Girdwood <lgirdwood@gmail.com>
Cc: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Cc: Mark Brown <broonie@kernel.org>
---
 .../regulator/userspace-consumer.rst          | 92 +++++++++++++++++++
 1 file changed, 92 insertions(+)
 create mode 100644 Documentation/driver-api/regulator/userspace-consumer.rst

diff --git a/Documentation/driver-api/regulator/userspace-consumer.rst b/Documentation/driver-api/regulator/userspace-consumer.rst
new file mode 100644
index 000000000000..308873fd20cb
--- /dev/null
+++ b/Documentation/driver-api/regulator/userspace-consumer.rst
@@ -0,0 +1,92 @@
+============================
+Regulator Userspace Consumer
+============================
+
+This document describes the Userspace Consumer Regulator Driver
+(`drivers/regulator/userspace-consumer.c`) and its userspace interface.
+
+Introduction
+------------
+
+The Userspace Consumer Regulator provides userspace with direct control
+and monitoring of regulator outputs. It now supports reporting regulator
+events directly via uevents, enabling userspace to handle events such as
+overcurrent, voltage changes, enabling/disabling regulators, and more.
+
+Supported Events
+----------------
+
+The driver emits uevents corresponding to the regulator events defined in
+``include/uapi/regulator/regulator.h``.
+
+Currently supported regulator event uevents are:
+
+- ``EVENT=ABORT_DISABLE``
+- ``EVENT=ABORT_VOLTAGE_CHANGE``
+- ``EVENT=DISABLE``
+- ``EVENT=ENABLE``
+- ``EVENT=FAIL``
+- ``EVENT=FORCE_DISABLE``
+- ``EVENT=OVER_CURRENT``
+- ``EVENT=OVER_TEMP``
+- ``EVENT=PRE_DISABLE``
+- ``EVENT=PRE_VOLTAGE_CHANGE``
+- ``EVENT=REGULATION_OUT``
+- ``EVENT=UNDER_VOLTAGE``
+- ``EVENT=VOLTAGE_CHANGE``
+
+Monitoring Events from Userspace
+--------------------------------
+
+Userspace applications can monitor these regulator uevents using ``udevadm``:
+
+.. code-block:: bash
+
+   udevadm monitor -pku
+
+Example output:
+
+.. code-block::
+
+    KERNEL[152.717414] change   /devices/platform/output-usb3 (platform)
+    ACTION=change
+    DEVPATH=/devices/platform/output-usb3
+    SUBSYSTEM=platform
+    NAME=event
+    EVENT=OVER_CURRENT
+    DRIVER=reg-userspace-consumer
+
+Handling Events with Udev Rules
+-------------------------------
+
+Userspace can react to these events by creating udev rules. For example,
+to trigger a script on an OVER_CURRENT event:
+
+.. code-block:: udev
+
+    # /etc/udev/rules.d/99-regulator-events.rules
+    ACTION=="change", SUBSYSTEM=="platform", DRIVER="reg-userspace-consumer", ENV{EVENT}=="OVER_CURRENT", RUN+="/usr/local/bin/handle-regulator-event.sh"
+
+A sample handler script:
+
+.. code-block:: bash
+
+    #!/bin/sh
+    logger "Handle regulator ${EVENT} on ${DEVPATH}"
+    # Add additional handling logic here
+    case "${EVENT}" in
+    OVER_CURRENT)
+      echo disabled > /sys"${DEVPATH}"/state
+    esac
+
+API Stability
+-------------
+
+This interface is considered stable. New regulator events may be added
+in the future, with corresponding documentation updates.
+
+References
+----------
+
+- Kernel Header File: ``include/uapi/regulator/regulator.h``
+- Driver Source: ``drivers/regulator/userspace-consumer.c``
-- 
2.39.5

Re: [PATCH 0/3] regulator: userspace-consumer: Add regulator event uevents

[Mark Brown]

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

On Fri, Apr 04, 2025 at 03:40:06PM +0200, Johann Neuhauser wrote:
> This series adds support for regulator event reporting via uevents to the
> userspace-consumer regulator driver. The goal is to provide userspace with
> a straightforward mechanism to monitor and respond to important regulator
> events such as overcurrent conditions, voltage changes, and enable/disable
> transitions.

This sounds like you're trying to use userspace-consumer in production
rather than as a test bodge...   what's the actual use case here?

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

RE: [PATCH 0/3] regulator: userspace-consumer: Add regulator event uevents

[Johann Neuhauser]

From: Mark Brown <broonie@kernel.org>
Sent: Friday, April 4, 2025 7:03 PM
>
>On Fri, Apr 04, 2025 at 03:40:06PM +0200, Johann Neuhauser wrote:
>> This series adds support for regulator event reporting via uevents to the
>> userspace-consumer regulator driver. The goal is to provide userspace with
>> a straightforward mechanism to monitor and respond to important regulator
>> events such as overcurrent conditions, voltage changes, and enable/disable
>> transitions.
>
>This sounds like you're trying to use userspace-consumer in production
>rather than as a test bodge...   what's the actual use case here?

Hi Mark,

Thank you for your feedback and question.

We have a hardware setup where the USB-A port is directly connected (D+/D-
lines) to the SoC, while its VBUS line is driven by an external I²C-based PMIC.
If a connected USB device attempts to draw more than approximately 800mA,
the PMIC detects an overcurrent condition, automatically disables the output,
and communicates an overcurrent event via the regulator framework.

Currently, the generic USB HCD drivers lack a built-in mechanism for handling
or recovering from such regulator-related events, particularly for reporting or
re-enabling regulator outputs after an OC condition occurs. The DA8xx OHCI
driver is one exception, as it indeed provides such functionality, but
integrating similar support into the generic USB HCD drivers seemed unlikely to
be accepted upstream.

I came across the userspace-consumer driver and believed it could help manage
this specific scenario. With this driver, I was able to manually toggle the
regulator off and back on, successfully clearing the error state. However, the
driver lacked proper event reporting, making it difficult to identify when the
regulator had entered an error state. Therefore, I proposed adding regulator
event reporting to enable userspace to detect these regulator events via udev
rules and subsequently restore regular USB power operation.

While I was aware that using the userspace-consumer driver might be seen as
somewhat of a workaround for special cases, I did not fully consider that it
was intended primarily as a temporary testing solution and perhaps not suitable
for this kind of production usage. I'd be grateful for any suggestions or advice you
might have on the appropriate approach or alternative solutions you could
recommend for upstream integration.

Thanks for again your input and guidance!

Best regards,
Johann

Re: [PATCH 0/3] regulator: userspace-consumer: Add regulator event uevents

[Mark Brown]

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

On Mon, Apr 07, 2025 at 02:17:10PM +0000, Johann Neuhauser wrote:
> From: Mark Brown <broonie@kernel.org>
> >On Fri, Apr 04, 2025 at 03:40:06PM +0200, Johann Neuhauser wrote:

> >> This series adds support for regulator event reporting via uevents to the
> >> userspace-consumer regulator driver. The goal is to provide userspace with
> >> a straightforward mechanism to monitor and respond to important regulator
> >> events such as overcurrent conditions, voltage changes, and enable/disable
> >> transitions.

> >This sounds like you're trying to use userspace-consumer in production
> >rather than as a test bodge...   what's the actual use case here?

> We have a hardware setup where the USB-A port is directly connected (D+/D-
> lines) to the SoC, while its VBUS line is driven by an external I²C-based PMIC.
> If a connected USB device attempts to draw more than approximately 800mA,
> the PMIC detects an overcurrent condition, automatically disables the output,
> and communicates an overcurrent event via the regulator framework.

You absolutely should not be using the userspace consumer for this.

> Currently, the generic USB HCD drivers lack a built-in mechanism for handling
> or recovering from such regulator-related events, particularly for reporting or
> re-enabling regulator outputs after an OC condition occurs. The DA8xx OHCI
> driver is one exception, as it indeed provides such functionality, but
> integrating similar support into the generic USB HCD drivers seemed unlikely to
> be accepted upstream.

Why not?  This seems like a perfectly reasonable thing to want to do, if
only as far as generating notifications to userspace.

> While I was aware that using the userspace-consumer driver might be seen as
> somewhat of a workaround for special cases, I did not fully consider that it
> was intended primarily as a temporary testing solution and perhaps not suitable
> for this kind of production usage. I'd be grateful for any suggestions or advice you
> might have on the appropriate approach or alternative solutions you could
> recommend for upstream integration.

I'd expect the consumer driver to be listening for events and offering
some sort of handling and/or interface for this that's joined up with
whatever the consumer is doing.  That basically means that your initial
thought above sounds about right to me.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]