[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@xxxxxxxxxxxxxxxxxx>
---
Cc: Jonathan Corbet <corbet@xxxxxxx>
Cc: Liam Girdwood <lgirdwood@xxxxxxxxx>
Cc: linux-doc@xxxxxxxxxxxxxxx
Cc: linux-kernel@xxxxxxxxxxxxxxx
Cc: Mark Brown <broonie@xxxxxxxxxx>
---
 .../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