[PATCH v3 0/7] regulator: add under-voltage support

[PATCH v3 0/7] regulator: add under-voltage support

[Oleksij Rempel]

This series add under-voltage and emergency shutdown for system critical
regulators

changes v3:
- add system-critical-regulator property
- add regulator-uv-survival-time-ms property
- implement default policy for system critical uv events

changes v2:
- drop event forwarding support
- use emergency shutdown directly instead of generating under-voltage
  error event.
- fix devicetree patch
- drop interrupt-names support


Oleksij Rempel (7):
  regulator: dt-bindings: Add system-critical-regulator property
  regulator: Handle system-critical under-voltage events
  regulator: dt-bindings: fixed-regulator: Add under-voltage interrupt
    support
  regulator: dt-bindings: whitelist system-critical-regulator property
    for fixed-regulator
  regulator: fixed: add support for under-voltage IRQ
  regulator: dt-bindings: Add regulator-uv-survival-time-ms property
  regulator: Implement uv_survival_time for handling under-voltage
    events

 .../bindings/regulator/fixed-regulator.yaml   |  7 +++
 .../bindings/regulator/regulator.yaml         | 12 +++++
 drivers/regulator/core.c                      |  6 +++
 drivers/regulator/fixed.c                     | 50 +++++++++++++++++++
 drivers/regulator/of_regulator.c              |  8 +++
 include/linux/regulator/machine.h             | 12 +++++
 6 files changed, 95 insertions(+)

-- 
2.39.2

[PATCH v3 1/7] regulator: dt-bindings: Add system-critical-regulator property

[Oleksij Rempel]

Introduce a new Device Tree property 'system-critical-regulator' for
marking a regulator as crucial for system stability or functionality.
This helps in distinguishing regulators that are vital for system
operations and may require special handling in under-voltage scenarios.

Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
---
 Documentation/devicetree/bindings/regulator/regulator.yaml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/devicetree/bindings/regulator/regulator.yaml b/Documentation/devicetree/bindings/regulator/regulator.yaml
index 9daf0fc2465f..5b8d55f7c43b 100644
--- a/Documentation/devicetree/bindings/regulator/regulator.yaml
+++ b/Documentation/devicetree/bindings/regulator/regulator.yaml
@@ -114,6 +114,11 @@ properties:
     description: Enable pull down resistor when the regulator is disabled.
     type: boolean
 
+  system-critical-regulator:
+    description: Set if the regulator is critical to system stability or
+      functionality.
+    type: boolean
+
   regulator-over-current-protection:
     description: Enable over current protection.
     type: boolean
-- 
2.39.2

[PATCH v3 2/7] regulator: Handle system-critical under-voltage events

[Oleksij Rempel]

Introduce handling for system-critical regulators during under-voltage
events.
A new field 'system_critical' in regulation_constraints is added to mark
regulators critical to system stability or functionality. During an
under-voltage event, if the regulator is marked as system-critical, an
emergency hardware protection shutdown is triggered to prevent potential
system damage or malfunction.

Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
---
 drivers/regulator/core.c          | 6 ++++++
 drivers/regulator/of_regulator.c  | 2 ++
 include/linux/regulator/machine.h | 6 ++++++
 3 files changed, 14 insertions(+)

diff --git a/drivers/regulator/core.c b/drivers/regulator/core.c
index d8e1caaf207e..903c384f25e3 100644
--- a/drivers/regulator/core.c
+++ b/drivers/regulator/core.c
@@ -19,6 +19,7 @@
 #include <linux/delay.h>
 #include <linux/gpio/consumer.h>
 #include <linux/of.h>
+#include <linux/reboot.h>
 #include <linux/regmap.h>
 #include <linux/regulator/of_regulator.h>
 #include <linux/regulator/consumer.h>
@@ -5073,6 +5074,11 @@ EXPORT_SYMBOL_GPL(regulator_bulk_free);
 int regulator_notifier_call_chain(struct regulator_dev *rdev,
 				  unsigned long event, void *data)
 {
+	if (rdev->constraints->system_critical &&
+	    event == REGULATOR_EVENT_UNDER_VOLTAGE)
+		hw_protection_shutdown("System critical voltage drop detected",
+				       REGULATOR_DEF_EMERG_SHUTDWN_TMO);
+
 	_notifier_call_chain(rdev, event, data);
 	return NOTIFY_DONE;
 
diff --git a/drivers/regulator/of_regulator.c b/drivers/regulator/of_regulator.c
index 1b65e5e4e40f..3bdd6f1919a4 100644
--- a/drivers/regulator/of_regulator.c
+++ b/drivers/regulator/of_regulator.c
@@ -131,6 +131,8 @@ static int of_get_regulation_constraints(struct device *dev,
 		constraints->valid_ops_mask |= REGULATOR_CHANGE_STATUS;
 
 	constraints->pull_down = of_property_read_bool(np, "regulator-pull-down");
+	constraints->system_critical = of_property_read_bool(np,
+						"system-critical-regulator");
 
 	if (of_property_read_bool(np, "regulator-allow-bypass"))
 		constraints->valid_ops_mask |= REGULATOR_CHANGE_BYPASS;
diff --git a/include/linux/regulator/machine.h b/include/linux/regulator/machine.h
index 621b7f4a3639..7332ee36e9d6 100644
--- a/include/linux/regulator/machine.h
+++ b/include/linux/regulator/machine.h
@@ -49,6 +49,9 @@ struct regulator;
 #define DISABLE_IN_SUSPEND	1
 #define ENABLE_IN_SUSPEND	2
 
+/* Default time in millisecond to wait for emergency shutdown */
+#define REGULATOR_DEF_EMERG_SHUTDWN_TMO	10
+
 /* Regulator active discharge flags */
 enum regulator_active_discharge {
 	REGULATOR_ACTIVE_DISCHARGE_DEFAULT,
@@ -127,6 +130,8 @@ struct notification_limit {
  * @ramp_disable: Disable ramp delay when initialising or when setting voltage.
  * @soft_start: Enable soft start so that voltage ramps slowly.
  * @pull_down: Enable pull down when regulator is disabled.
+ * @system_critical: Set if the regulator is critical to system stability or
+ *                   functionality.
  * @over_current_protection: Auto disable on over current event.
  *
  * @over_current_detection: Configure over current limits.
@@ -214,6 +219,7 @@ struct regulation_constraints {
 	unsigned ramp_disable:1; /* disable ramp delay */
 	unsigned soft_start:1;	/* ramp voltage slowly */
 	unsigned pull_down:1;	/* pull down resistor when regulator off */
+	unsigned system_critical:1;	/* critical to system stability */
 	unsigned over_current_protection:1; /* auto disable on over current */
 	unsigned over_current_detection:1; /* notify on over current */
 	unsigned over_voltage_detection:1; /* notify on over voltage */
-- 
2.39.2

[PATCH v3 3/7] regulator: dt-bindings: fixed-regulator: Add under-voltage interrupt support

[Oleksij Rempel]

Add under-voltage interrupt support. This can be used with simple
regulators having no other way to communicate an under-voltage event
except as by toggling some GPIO line.

Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
---
 .../devicetree/bindings/regulator/fixed-regulator.yaml       | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml
index ac0281b1cceb..ce7751b9129c 100644
--- a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml
+++ b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml
@@ -100,6 +100,11 @@ properties:
   vin-supply:
     description: Input supply phandle.
 
+  interrupts:
+    maxItems: 1
+    description:
+      Interrupt signaling a critical under-voltage event.
+
 required:
   - compatible
   - regulator-name
-- 
2.39.2

[PATCH v3 4/7] regulator: dt-bindings: whitelist system-critical-regulator property for fixed-regulator

[Oleksij Rempel]

Allow fixed-regulator to be marked as system-critical by whitelisting
the 'system-critical-regulator' property.

This property indicating that the fixed-regulator is critical to system
stability or functionality, aligning with the recent changes in the
regulator core handling of under-voltage events for system-critical
regulators.

Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
---
 .../devicetree/bindings/regulator/fixed-regulator.yaml          | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml
index ce7751b9129c..9ff9abf2691a 100644
--- a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml
+++ b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml
@@ -105,6 +105,8 @@ properties:
     description:
       Interrupt signaling a critical under-voltage event.
 
+  system-critical-regulator: true
+
 required:
   - compatible
   - regulator-name
-- 
2.39.2

[PATCH v3 5/7] regulator: fixed: add support for under-voltage IRQ

[Oleksij Rempel]

Add interrupt support for under-voltage notification. This functionality
can be used on systems capable to detect under-voltage state and having
enough capacity to let the SoC do some emergency preparation.

This change enforce default policy to shutdown system as soon as
interrupt is triggered.

Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
---
 drivers/regulator/fixed.c | 50 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/drivers/regulator/fixed.c b/drivers/regulator/fixed.c
index 55130efae9b8..cb93e5cdcfa9 100644
--- a/drivers/regulator/fixed.c
+++ b/drivers/regulator/fixed.c
@@ -20,6 +20,7 @@
 #include <linux/platform_device.h>
 #include <linux/pm_domain.h>
 #include <linux/pm_opp.h>
+#include <linux/reboot.h>
 #include <linux/regulator/driver.h>
 #include <linux/regulator/fixed.h>
 #include <linux/gpio/consumer.h>
@@ -29,6 +30,8 @@
 #include <linux/regulator/machine.h>
 #include <linux/clk.h>
 
+/* Default time in millisecond to wait for emergency shutdown */
+#define FV_DEF_EMERG_SHUTDWN_TMO	10
 
 struct fixed_voltage_data {
 	struct regulator_desc desc;
@@ -105,6 +108,49 @@ static int reg_is_enabled(struct regulator_dev *rdev)
 	return priv->enable_counter > 0;
 }
 
+static irqreturn_t reg_fixed_under_voltage_irq_handler(int irq, void *data)
+{
+	struct fixed_voltage_data *priv = data;
+	struct regulator_dev *rdev = priv->dev;
+
+	regulator_notifier_call_chain(rdev, REGULATOR_EVENT_UNDER_VOLTAGE,
+				      NULL);
+
+	return IRQ_HANDLED;
+}
+
+/**
+ * reg_fixed_get_irqs - Get and register the optional IRQ for fixed voltage
+ *                      regulator.
+ * @dev: Pointer to the device structure.
+ * @priv: Pointer to fixed_voltage_data structure containing private data.
+ *
+ * This function tries to get the IRQ from the device firmware node.
+ * If it's an optional IRQ and not found, it returns 0.
+ * Otherwise, it attempts to request the threaded IRQ.
+ *
+ * Return: 0 on success, or error code on failure.
+ */
+static int reg_fixed_get_irqs(struct device *dev,
+			      struct fixed_voltage_data *priv)
+{
+	int ret;
+
+	ret = fwnode_irq_get(dev_fwnode(dev), 0);
+	/* This is optional IRQ. If not found we will get -EINVAL */
+	if (ret == -EINVAL)
+		return 0;
+	if (ret < 0)
+		return dev_err_probe(dev, ret, "Failed to get IRQ\n");
+
+	ret = devm_request_threaded_irq(dev, ret, NULL,
+					reg_fixed_under_voltage_irq_handler,
+					IRQF_ONESHOT, "under-voltage", priv);
+	if (ret)
+		return dev_err_probe(dev, ret, "Failed to request IRQ\n");
+
+	return 0;
+}
 
 /**
  * of_get_fixed_voltage_config - extract fixed_voltage_config structure info
@@ -294,6 +340,10 @@ static int reg_fixed_voltage_probe(struct platform_device *pdev)
 	dev_dbg(&pdev->dev, "%s supplying %duV\n", drvdata->desc.name,
 		drvdata->desc.fixed_uV);
 
+	ret = reg_fixed_get_irqs(dev, drvdata);
+	if (ret)
+		return ret;
+
 	return 0;
 }
 
-- 
2.39.2

[PATCH v3 6/7] regulator: dt-bindings: Add regulator-uv-survival-time-ms property

[Oleksij Rempel]

Introduce a new Device Tree property 'regulator-uv-survival-time-ms' to
specify the survival time post a critical under-voltage event. This
property defines the time in milliseconds the system can operate before
the on-board capacitors fail, providing a window for necessary actions
or preparations to be taken before power loss, aligning with the
under-voltage event handling mechanism.

Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
---
 Documentation/devicetree/bindings/regulator/regulator.yaml | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/devicetree/bindings/regulator/regulator.yaml b/Documentation/devicetree/bindings/regulator/regulator.yaml
index 5b8d55f7c43b..85b8c51f8ede 100644
--- a/Documentation/devicetree/bindings/regulator/regulator.yaml
+++ b/Documentation/devicetree/bindings/regulator/regulator.yaml
@@ -186,6 +186,13 @@ properties:
       be enabled but limit setting can be omitted. Limit is given as microvolt
       offset from voltage set to regulator.
 
+  regulator-uv-survival-time-ms:
+    description: Specifies the time (in milliseconds) the system can continue
+      to operate after a critical under-voltage event has been triggered,
+      before the on-board capacitors fail. This time essentially represents the
+      duration the system has to take any necessary actions or preparations
+      before power loss.
+
   regulator-temp-protection-kelvin:
     description: Set over temperature protection limit. This is a limit where
       hardware performs emergency shutdown. Zero can be passed to disable
-- 
2.39.2

[PATCH v3 7/7] regulator: Implement uv_survival_time for handling under-voltage events

[Oleksij Rempel]

Add 'uv_survival_time' field to regulation_constraints for specifying
survival time post critical under-voltage event. Update the regulator
notifier call chain and Device Tree property parsing to use this new
field, allowing a configurable timeout before emergency shutdown.

Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
---
 drivers/regulator/core.c          | 2 +-
 drivers/regulator/of_regulator.c  | 6 ++++++
 include/linux/regulator/machine.h | 6 ++++++
 3 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/drivers/regulator/core.c b/drivers/regulator/core.c
index 903c384f25e3..bb864969fc79 100644
--- a/drivers/regulator/core.c
+++ b/drivers/regulator/core.c
@@ -5077,7 +5077,7 @@ int regulator_notifier_call_chain(struct regulator_dev *rdev,
 	if (rdev->constraints->system_critical &&
 	    event == REGULATOR_EVENT_UNDER_VOLTAGE)
 		hw_protection_shutdown("System critical voltage drop detected",
-				       REGULATOR_DEF_EMERG_SHUTDWN_TMO);
+				       rdev->constraints->uv_survival_time);
 
 	_notifier_call_chain(rdev, event, data);
 	return NOTIFY_DONE;
diff --git a/drivers/regulator/of_regulator.c b/drivers/regulator/of_regulator.c
index 3bdd6f1919a4..6463b455ebc5 100644
--- a/drivers/regulator/of_regulator.c
+++ b/drivers/regulator/of_regulator.c
@@ -175,6 +175,12 @@ static int of_get_regulation_constraints(struct device *dev,
 	if (!ret)
 		constraints->enable_time = pval;
 
+	ret = of_property_read_u32(np, "regulator-uv-survival-time-ms", &pval);
+	if (!ret)
+		constraints->uv_survival_time = pval;
+	else
+		constraints->uv_survival_time = REGULATOR_DEF_EMERG_SHUTDWN_TMO;
+
 	constraints->soft_start = of_property_read_bool(np,
 					"regulator-soft-start");
 	ret = of_property_read_u32(np, "regulator-active-discharge", &pval);
diff --git a/include/linux/regulator/machine.h b/include/linux/regulator/machine.h
index 7332ee36e9d6..daddec83d887 100644
--- a/include/linux/regulator/machine.h
+++ b/include/linux/regulator/machine.h
@@ -158,6 +158,11 @@ struct notification_limit {
  *		      regulator_active_discharge values are used for
  *		      initialisation.
  * @enable_time: Turn-on time of the rails (unit: microseconds)
+ * @uv_survival_time: Survival time post a critical under-voltage event. Time
+ *                    the system can operate before the on-board capacitors
+ *                    fail, providing a window for necessary actions or
+ *                    preparations to be taken before power loss.
+ *                    (unit: microseconds)
  */
 struct regulation_constraints {
 
@@ -209,6 +214,7 @@ struct regulation_constraints {
 	unsigned int settling_time_up;
 	unsigned int settling_time_down;
 	unsigned int enable_time;
+	unsigned int uv_survival_time;
 
 	unsigned int active_discharge;
 
-- 
2.39.2

Re: [PATCH v3 4/7] regulator: dt-bindings: whitelist system-critical-regulator property for fixed-regulator

[Mark Brown]

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

On Wed, Oct 25, 2023 at 10:46:11AM +0200, Oleksij Rempel wrote:
> Allow fixed-regulator to be marked as system-critical by whitelisting
> the 'system-critical-regulator' property.
> 
> This property indicating that the fixed-regulator is critical to system
> stability or functionality, aligning with the recent changes in the
> regulator core handling of under-voltage events for system-critical
> regulators.

Why would this need to be something we explicitly enable for a given
regulator?  Surely this is a property of the creativity of hardware
engineers rather than the regulator itself.

Also please avoid the use of the outdated terms whitelist and blacklist,
pass and block lists are often a good alternative.

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

Re: [PATCH v3 2/7] regulator: Handle system-critical under-voltage events

[Mark Brown]

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

On Wed, Oct 25, 2023 at 10:46:09AM +0200, Oleksij Rempel wrote:

> +	if (rdev->constraints->system_critical &&
> +	    event == REGULATOR_EVENT_UNDER_VOLTAGE)
> +		hw_protection_shutdown("System critical voltage drop detected",
> +				       REGULATOR_DEF_EMERG_SHUTDWN_TMO);
> +

This should probably be a switch statement for the event and also handle
REGULATOR_EVENT_FAIL, possibly other errors this would also be
appropriate handling but it's less immediately obvious and we can
always extend later.

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

Re: (subset) [PATCH v3 0/7] regulator: add under-voltage support

[Mark Brown]

On Wed, 25 Oct 2023 10:46:07 +0200, Oleksij Rempel wrote:
> This series add under-voltage and emergency shutdown for system critical
> regulators
> 
> changes v3:
> - add system-critical-regulator property
> - add regulator-uv-survival-time-ms property
> - implement default policy for system critical uv events
> 
> [...]

Applied to

   https://git.kernel.org/pub/scm/linux/kernel/git/broonie/regulator.git for-next

Thanks!

[3/7] regulator: dt-bindings: fixed-regulator: Add under-voltage interrupt support
      commit: 0ab1dc9c657f30434ca55a3dcc87e624af0b2116
[5/7] regulator: fixed: add support for under-voltage IRQ
      commit: ecb6f1f456144e9ade5a492192287decbeef4cfe

All being well this means that it will be integrated into the linux-next
tree (usually sometime in the next 24 hours) and sent to Linus during
the next merge window (or sooner if it is a bug fix), however if
problems are discovered then the patch may be dropped or reverted.

You may get further e-mails resulting from automated or manual testing
and review of the tree, please engage with people reporting problems and
send followup patches addressing any issues that are reported if needed.

If any updates are required or you are submitting further changes they
should be sent as incremental updates against current git, existing
patches will not be replaced.

Please add any relevant lists and maintainers to the CCs when replying
to this mail.

Thanks,
Mark

Re: [PATCH v3 4/7] regulator: dt-bindings: whitelist system-critical-regulator property for fixed-regulator

[Oleksij Rempel]

On Wed, Oct 25, 2023 at 01:41:45PM +0100, Mark Brown wrote:
> On Wed, Oct 25, 2023 at 10:46:11AM +0200, Oleksij Rempel wrote:
> > Allow fixed-regulator to be marked as system-critical by whitelisting
> > the 'system-critical-regulator' property.
> > 
> > This property indicating that the fixed-regulator is critical to system
> > stability or functionality, aligning with the recent changes in the
> > regulator core handling of under-voltage events for system-critical
> > regulators.
> 
> Why would this need to be something we explicitly enable for a given
> regulator?  Surely this is a property of the creativity of hardware
> engineers rather than the regulator itself.

:)

> Also please avoid the use of the outdated terms whitelist and blacklist,
> pass and block lists are often a good alternative.

ack

-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

Re: [PATCH v3 6/7] regulator: dt-bindings: Add regulator-uv-survival-time-ms property

[Rob Herring]

On Wed, 25 Oct 2023 10:46:13 +0200, Oleksij Rempel wrote:
> Introduce a new Device Tree property 'regulator-uv-survival-time-ms' to
> specify the survival time post a critical under-voltage event. This
> property defines the time in milliseconds the system can operate before
> the on-board capacitors fail, providing a window for necessary actions
> or preparations to be taken before power loss, aligning with the
> under-voltage event handling mechanism.
> 
> Signed-off-by: Oleksij Rempel <o.rempel@pengutronix.de>
> ---
>  Documentation/devicetree/bindings/regulator/regulator.yaml | 7 +++++++
>  1 file changed, 7 insertions(+)
> 

Acked-by: Rob Herring <robh@kernel.org>