[v1,1/3] regulator: dt-bindings: fixed-regulator: Add under-voltage interrupt support

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>

On Tue, Oct 10, 2023 at 10:59:06AM +0200, Oleksij Rempel wrote:
> Add handler to forward under-voltage events.
> On systems for more or less complicated regulator chains we need to
> forward under-voltage events to actual driver which need to react on
> them.

It isn't clear to me why this would be implemented in one specific
driver, nor why this would be done unconditionally.  Could you provide
some information on the problem you're trying to solve here?  This feels
like something that should be a core feature.

> +static int reg_fixed_regulator_notifier(struct notifier_block *nb,
> +					unsigned long event, void *data)
> +{
> +	struct fixed_voltage_data *priv =
> +		container_of(nb, struct fixed_voltage_data, nb);
> +	struct regulator_dev *rdev = priv->dev;
> +
> +	if (event != REGULATOR_EVENT_UNDER_VOLTAGE_WARN &&
> +	    event != REGULATOR_EVENT_UNDER_VOLTAGE)
> +		return NOTIFY_OK;
> +
> +	regulator_notifier_call_chain(rdev, event, NULL);

This would be better written as a switch statement for extensibility,
and it's not clear why the filtering?

On Tue, Oct 10, 2023 at 10:59:04AM +0200, Oleksij Rempel wrote:
> 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.

This doesn't apply against current code, please check and resend.

Hi,

On Tue, Oct 10, 2023 at 01:19:36PM +0100, Mark Brown wrote:
> On Tue, Oct 10, 2023 at 10:59:06AM +0200, Oleksij Rempel wrote:
> > Add handler to forward under-voltage events.
> > On systems for more or less complicated regulator chains we need to
> > forward under-voltage events to actual driver which need to react on
> > them.
> 
> It isn't clear to me why this would be implemented in one specific
> driver, nor why this would be done unconditionally.  Could you provide
> some information on the problem you're trying to solve here?

The hardware I am working with has an under-voltage sensor on the 24V
supply regulator and some backup capacitors to run SoC for 100ms. I want
to forward under-voltage events across a chain of different regulators
to a designated consumer. For instance, to the mmc driver, enabling it
to initiate shutdown before power loss occurs.  Additionally, a bit can
be set in the volatile memory of a scratch pad in an RTC clock to record
sudden power loss, which can be checked on the next system start.

> This feels like something that should be a core feature.

Agreed. I am relatively new to the regulator framework and am uncertain
about the optimal location for registering the event forwarding. Could
you advise on this?

> > +static int reg_fixed_regulator_notifier(struct notifier_block *nb,
> > +					unsigned long event, void *data)
> > +{
> > +	struct fixed_voltage_data *priv =
> > +		container_of(nb, struct fixed_voltage_data, nb);
> > +	struct regulator_dev *rdev = priv->dev;
> > +
> > +	if (event != REGULATOR_EVENT_UNDER_VOLTAGE_WARN &&
> > +	    event != REGULATOR_EVENT_UNDER_VOLTAGE)
> > +		return NOTIFY_OK;
> > +
> > +	regulator_notifier_call_chain(rdev, event, NULL);
> 
> This would be better written as a switch statement for extensibility,

ack.

> and it's not clear why the filtering?

I started with a conservative approach because I'm not sure about the
possible effects of forwarding all events. If forwarding all events is a
good idea, I can do it.

Regards,
Oleksij

On Tue, Oct 10, 2023 at 02:55:31PM +0200, Oleksij Rempel wrote:
> Hi,
> 
> On Tue, Oct 10, 2023 at 01:19:36PM +0100, Mark Brown wrote:
> > On Tue, Oct 10, 2023 at 10:59:06AM +0200, Oleksij Rempel wrote:
> > > Add handler to forward under-voltage events.
> > > On systems for more or less complicated regulator chains we need to
> > > forward under-voltage events to actual driver which need to react on
> > > them.
> > 
> > It isn't clear to me why this would be implemented in one specific
> > driver, nor why this would be done unconditionally.  Could you provide
> > some information on the problem you're trying to solve here?
> 
> The hardware I am working with has an under-voltage sensor on the 24V
> supply regulator and some backup capacitors to run SoC for 100ms. I want
> to forward under-voltage events across a chain of different regulators
> to a designated consumer. For instance, to the mmc driver, enabling it
> to initiate shutdown before power loss occurs.  Additionally, a bit can
> be set in the volatile memory of a scratch pad in an RTC clock to record
> sudden power loss, which can be checked on the next system start.

The bit picture of my HW may potentially be even more advanced:
- some regulator chain paths are disabled by the HW. With other words
  under-voltage event is converted to fail or disable. There is nothing
  what software can do, but it will be good to reflect it on the SW
  side for diagnostic.
- some paths can be disabled by software to get some more milliseconds
  of life and complete emergency shutdown task.

On Tue, Oct 10, 2023 at 02:55:31PM +0200, Oleksij Rempel wrote:

> The hardware I am working with has an under-voltage sensor on the 24V
> supply regulator and some backup capacitors to run SoC for 100ms. I want
> to forward under-voltage events across a chain of different regulators
> to a designated consumer. For instance, to the mmc driver, enabling it
> to initiate shutdown before power loss occurs.  Additionally, a bit can
> be set in the volatile memory of a scratch pad in an RTC clock to record
> sudden power loss, which can be checked on the next system start.

So it sounds like the underlying need is to flag the notifications from
one of the regulators as being system wide and then take action based on
those notifications somewhere basically disconnected?  That does seem
like a good use case.

The MMC doesn't specifically care that it is handling a regulator
notification, it more wants to know that the system is dying and doesn't
really care how we figured that out so if we can hook it into a system
level notificaiton it'd be happy and would also be able to handle other
critical faults.  I would have thought that we should have some
mechanisms for this already for RAS type stuff but I'm drawing a blank
on what it actually is if there is an existing abstraction.  It could
potentially go through userspace though there's latency concerns there
which might not be ideal, there should at least be some policy for
userspace.

For the regulator itself we probably want a way to identify regulators
as being system critical so they start notifying.  It would be tempting
to just do that by default but that would likely cause some issues for
example with regulators for things like SD cards which are more likely
to get hardware problems that don't comprimise the entire system.  We
could do that with DT, either a property or some sort of runtime
consumer, but it might be better to have a control in sysfs that
userspace can turn on?  OTOH the ability do something about this depends
on specific hardware design...

I've copied in Sebastian since this sounds like the sort of thing that
power supplies might have some kind of handling for, or at least if we
need to add something we should make it so that the power supplies can
be joined up to it.  I do see temperature and capacity alerts in the
sysfs ABI for power supplies, but nothing for voltage.

I've also coped in Naresh and Zev who've been discussing something
vaugely similar with userspace notifications for the userspace consumer
- it's not the same thing given that you don't specifically need
userspace to be involved here but it feels like it might have something
of a similar shape, or at least there might be some shared interest.

On Tue, Oct 10, 2023 at 10:59:04AM +0200, Oleksij Rempel wrote:
> 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>
> 
> diff --git a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml
> index ac0281b1cceb..0f8760ed2fb1 100644
> --- a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml
> +++ b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml
> @@ -100,6 +100,14 @@ properties:
>    vin-supply:
>      description: Input supply phandle.
> 
> +  interrupts:
> +    maxItems: 1
> +    description:
> +      Under-voltage interrupt
> +
> +  interrupt-names:
> +    const: under-voltage

No need for a name. If there's ever a 2nd, it should be a specific 
binding, not fixed-regulator.

> +
>  required:
>    - compatible
>    - regulator-name
> ---
>  .../devicetree/bindings/regulator/fixed-regulator.yaml    | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml
> index ac0281b1cceb..0f8760ed2fb1 100644
> --- a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml
> +++ b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml

I think you've got some problems with your setup...

> @@ -100,6 +100,14 @@ properties:
>    vin-supply:
>      description: Input supply phandle.
>  
> +  interrupts:
> +    maxItems: 1
> +    description:
> +      Under-voltage interrupt
> +
> +  interrupt-names:
> +    const: under-voltage
> +
>  required:
>    - compatible
>    - regulator-name
> -- 
> 2.39.2
>

On Tue, Oct 10, 2023 at 06:19:59PM +0100, Mark Brown wrote:
> On Tue, Oct 10, 2023 at 02:55:31PM +0200, Oleksij Rempel wrote:
> 
> > The hardware I am working with has an under-voltage sensor on the 24V
> > supply regulator and some backup capacitors to run SoC for 100ms. I want
> > to forward under-voltage events across a chain of different regulators
> > to a designated consumer. For instance, to the mmc driver, enabling it
> > to initiate shutdown before power loss occurs.  Additionally, a bit can
> > be set in the volatile memory of a scratch pad in an RTC clock to record
> > sudden power loss, which can be checked on the next system start.
> 
> So it sounds like the underlying need is to flag the notifications from
> one of the regulators as being system wide and then take action based on
> those notifications somewhere basically disconnected?  That does seem
> like a good use case.
> 
> The MMC doesn't specifically care that it is handling a regulator
> notification, it more wants to know that the system is dying and doesn't
> really care how we figured that out so if we can hook it into a system
> level notificaiton it'd be happy and would also be able to handle other
> critical faults.  I would have thought that we should have some
> mechanisms for this already for RAS type stuff but I'm drawing a blank
> on what it actually is if there is an existing abstraction.  It could
> potentially go through userspace though there's latency concerns there
> which might not be ideal, there should at least be some policy for
> userspace.

The project I'm working prefers reducing user space daemons to configure and
enforce RAS policies due to time and financial budget constraints. The customer
is inclined to invest only in essential infrastructure.

Configuration through the device tree and kernel defaults is preferable.
For instance, having a default kernel governor that doesn’t require user
space configuration aligns with the project’s objectives.

While a proper UAPI might not be implemented in the first run, the
design will allow for it to be added and extended by other projects in
the future.

> For the regulator itself we probably want a way to identify regulators
> as being system critical so they start notifying.  It would be tempting
> to just do that by default but that would likely cause some issues for
> example with regulators for things like SD cards which are more likely
> to get hardware problems that don't comprimise the entire system.  We
> could do that with DT, either a property or some sort of runtime
> consumer, but it might be better to have a control in sysfs that
> userspace can turn on?  OTOH the ability do something about this depends
> on specific hardware design...
> 
> I've copied in Sebastian since this sounds like the sort of thing that
> power supplies might have some kind of handling for, or at least if we
> need to add something we should make it so that the power supplies can
> be joined up to it.  I do see temperature and capacity alerts in the
> sysfs ABI for power supplies, but nothing for voltage.

Thank you for pointing towards the power supply framework. Given the hardware
design of my project, I can envision mapping the following states and
properties within this framework:

1. States:
   - POWER_SUPPLY_STATUS_FULL: When the capacitor is fully charged.
   - POWER_SUPPLY_STATUS_DISCHARGING: Triggered when an under-voltage event is
                                      detected.

2. Technology:
   - POWER_SUPPLY_TECHNOLOGY_CAPACITOR

3. Capacity Level:
   - Post under-voltage detection, the system would immediately transition to
     POWER_SUPPLY_CAPACITY_LEVEL_CRITICAL state.

4. Properties:
   - POWER_SUPPLY_PROP_TIME_TO_EMPTY_NOW: 100ms, representing the time until
                                          complete power loss.
   - POWER_SUPPLY_TYPE_MAINS: Under normal operation.
   - POWER_SUPPLY_TYPE_BATTERY: Triggered when under-voltage is detected.

Considering the above mapping, my initial step would be to create a simple
regulator coupled (if regulator is still needed in this casr) with a Device
Tree (DT) based power supply driver.  This setup would align with the existing
power supply framework, with a notable extension being the system-wide
notification for emergency shutdown upon under-voltage detection.

> I've also coped in Naresh and Zev who've been discussing something
> vaugely similar with userspace notifications for the userspace consumer
> - it's not the same thing given that you don't specifically need
> userspace to be involved here but it feels like it might have something
> of a similar shape, or at least there might be some shared interest.

Regards,
Oleksij

On Wed, Oct 11, 2023 at 09:59:31AM +0200, Oleksij Rempel wrote:

> Configuration through the device tree and kernel defaults is preferable.
> For instance, having a default kernel governor that doesn’t require user
> space configuration aligns with the project’s objectives.

That's policy though...

> 
> > For the regulator itself we probably want a way to identify regulators
> > as being system critical so they start notifying.  It would be tempting
> > to just do that by default but that would likely cause some issues for
> > example with regulators for things like SD cards which are more likely
> > to get hardware problems that don't comprimise the entire system.  We
> > could do that with DT, either a property or some sort of runtime
> > consumer, but it might be better to have a control in sysfs that
> > userspace can turn on?  OTOH the ability do something about this depends
> > on specific hardware design...
> > 
> > I've copied in Sebastian since this sounds like the sort of thing that
> > power supplies might have some kind of handling for, or at least if we
> > need to add something we should make it so that the power supplies can
> > be joined up to it.  I do see temperature and capacity alerts in the
> > sysfs ABI for power supplies, but nothing for voltage.
> 
> Thank you for pointing towards the power supply framework. Given the hardware
> design of my project, I can envision mapping the following states and
> properties within this framework:

There's also hw_failure_emergency_poweroff() which looks like exactly
what you're trying to trigger here.

> Considering the above mapping, my initial step would be to create a simple
> regulator coupled (if regulator is still needed in this casr) with a Device
> Tree (DT) based power supply driver.  This setup would align with the existing
> power supply framework, with a notable extension being the system-wide
> notification for emergency shutdown upon under-voltage detection.

It sounds like this is actually a regulator regardless of if it also
appears via some other API.

On Wed, Oct 11, 2023 at 12:38:19PM +0100, Mark Brown wrote:
> On Wed, Oct 11, 2023 at 09:59:31AM +0200, Oleksij Rempel wrote:
> 
> > Configuration through the device tree and kernel defaults is preferable.
> > For instance, having a default kernel governor that doesn’t require user
> > space configuration aligns with the project’s objectives.
> 
> That's policy though...
> 
> > 
> > > For the regulator itself we probably want a way to identify regulators
> > > as being system critical so they start notifying.  It would be tempting

Can the "criticality" could be determined by the severity (ERROR vs WARNING)?

> > > to just do that by default but that would likely cause some issues for
> > > example with regulators for things like SD cards which are more likely
> > > to get hardware problems that don't comprimise the entire system.  We

"comprimise the entire system" sounds (to my ears) exactly the
difference between WARNING and ERROR notifications.

> > > could do that with DT, either a property or some sort of runtime
> > > consumer, but it might be better to have a control in sysfs that
> > > userspace can turn on?  OTOH the ability do something about this depends
> > > on specific hardware design...
> > > 
> > > I've copied in Sebastian since this sounds like the sort of thing that
> > > power supplies might have some kind of handling for, or at least if we
> > > need to add something we should make it so that the power supplies can
> > > be joined up to it.  I do see temperature and capacity alerts in the
> > > sysfs ABI for power supplies, but nothing for voltage.
> > 
> > Thank you for pointing towards the power supply framework. Given the hardware
> > design of my project, I can envision mapping the following states and
> > properties within this framework:
> 
> There's also hw_failure_emergency_poweroff() which looks like exactly
> what you're trying to trigger here.

There is already a path from regulator notification handling to the
hw_failure_emergency_poweroff() - although only when handling the IRQs
fail and this failure is marked as fatal.

> > Considering the above mapping, my initial step would be to create a simple
> > regulator coupled (if regulator is still needed in this casr) with a Device
> > Tree (DT) based power supply driver.  This setup would align with the existing
> > power supply framework, with a notable extension being the system-wide
> > notification for emergency shutdown upon under-voltage detection.
> 
> It sounds like this is actually a regulator regardless of if it also
> appears via some other API.

I wonder if it would make sense to add a 'protector' in regulator core.
The 'protector' could register to listen the notifications from those
regulators which have some
'regulator-fatal-notifications = <list of notifications>;' -property
defined in device-tree.

In my eyes the device-tree is correct place for this information
because whether an "anomaly" in regulator output compromises the system
is a property of hardware.

Yours,
	-- Matti

On Thu, Oct 12, 2023 at 10:08:40AM +0300, Matti Vaittinen wrote:

> In my eyes the device-tree is correct place for this information
> because whether an "anomaly" in regulator output compromises the system
> is a property of hardware.

Yes, it's mainly the handling that has a policy element.

Hi,

On Wed, Oct 11, 2023 at 09:59:31AM +0200, Oleksij Rempel wrote:
> On Tue, Oct 10, 2023 at 06:19:59PM +0100, Mark Brown wrote:
> > On Tue, Oct 10, 2023 at 02:55:31PM +0200, Oleksij Rempel wrote:
> > > The hardware I am working with has an under-voltage sensor on the 24V
> > > supply regulator and some backup capacitors to run SoC for 100ms. I want
> > > to forward under-voltage events across a chain of different regulators
> > > to a designated consumer. For instance, to the mmc driver, enabling it
> > > to initiate shutdown before power loss occurs.  Additionally, a bit can
> > > be set in the volatile memory of a scratch pad in an RTC clock to record
> > > sudden power loss, which can be checked on the next system start.
> > 
> > So it sounds like the underlying need is to flag the notifications from
> > one of the regulators as being system wide and then take action based on
> > those notifications somewhere basically disconnected?  That does seem
> > like a good use case.
> > 
> > The MMC doesn't specifically care that it is handling a regulator
> > notification, it more wants to know that the system is dying and doesn't
> > really care how we figured that out so if we can hook it into a system
> > level notificaiton it'd be happy and would also be able to handle other
> > critical faults.  I would have thought that we should have some
> > mechanisms for this already for RAS type stuff but I'm drawing a blank
> > on what it actually is if there is an existing abstraction.  It could
> > potentially go through userspace though there's latency concerns there
> > which might not be ideal, there should at least be some policy for
> > userspace.
> 
> The project I'm working prefers reducing user space daemons to configure and
> enforce RAS policies due to time and financial budget constraints. The customer
> is inclined to invest only in essential infrastructure.
> 
> Configuration through the device tree and kernel defaults is preferable.
> For instance, having a default kernel governor that doesn’t require user
> space configuration aligns with the project’s objectives.
> 
> While a proper UAPI might not be implemented in the first run, the
> design will allow for it to be added and extended by other projects in
> the future.
> 
> > For the regulator itself we probably want a way to identify regulators
> > as being system critical so they start notifying.  It would be tempting
> > to just do that by default but that would likely cause some issues for
> > example with regulators for things like SD cards which are more likely
> > to get hardware problems that don't comprimise the entire system.  We
> > could do that with DT, either a property or some sort of runtime
> > consumer, but it might be better to have a control in sysfs that
> > userspace can turn on?  OTOH the ability do something about this depends
> > on specific hardware design...
> > 
> > I've copied in Sebastian since this sounds like the sort of thing that
> > power supplies might have some kind of handling for, or at least if we
> > need to add something we should make it so that the power supplies can
> > be joined up to it.  I do see temperature and capacity alerts in the
> > sysfs ABI for power supplies, but nothing for voltage.
> 
> Thank you for pointing towards the power supply framework. Given the hardware
> design of my project, I can envision mapping the following states and
> properties within this framework:
> 
> 1. States:
>    - POWER_SUPPLY_STATUS_FULL: When the capacitor is fully charged.
>    - POWER_SUPPLY_STATUS_DISCHARGING: Triggered when an under-voltage event is
>                                       detected.
> 
> 2. Technology:
>    - POWER_SUPPLY_TECHNOLOGY_CAPACITOR
> 
> 3. Capacity Level:
>    - Post under-voltage detection, the system would immediately transition to
>      POWER_SUPPLY_CAPACITY_LEVEL_CRITICAL state.
> 
> 4. Properties:
>    - POWER_SUPPLY_PROP_TIME_TO_EMPTY_NOW: 100ms, representing the time until
>                                           complete power loss.
>    - POWER_SUPPLY_TYPE_MAINS: Under normal operation.
>    - POWER_SUPPLY_TYPE_BATTERY: Triggered when under-voltage is detected.

I don't know if power-supply is the best fit for this, but if you
continue on this path:

POWER_SUPPLY_TYPE is supposed to be fixed. You either have a battery
or a charger. If you want to go the power-supply way, you need two
devices: One POWER_SUPPLY_TYPE_MAINS for the regulator charging the
capacitor and one POWER_SUPPLY_TYPE_BATTERY for the capacitor. The
MAINS device is important to keep power_supply_is_system_supplied()
working as expected.

Note, that there is no generic solution how to handle critical
battery events in the power-supply framework at the moment. On
Laptops userspace handles early poweroff based on the information
supplied by the kernel. Right now there is one phone battery driver
doing 'orderly_poweroff(true)' on critical battery state. That's
about it.

Greetings,

-- Sebastian

On Tue, 10 Oct 2023 10:59:04 +0200, Oleksij Rempel wrote:
> 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>
> 
> diff --git a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml
> index ac0281b1cceb..0f8760ed2fb1 100644
> --- a/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml
> +++ b/Documentation/devicetree/bindings/regulator/fixed-regulator.yaml
> @@ -100,6 +100,14 @@ properties:
>    vin-supply:
>      description: Input supply phandle.
> 
> [...]

Applied to

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

Thanks!

[1/3] regulator: dt-bindings: fixed-regulator: Add under-voltage interrupt support
      commit: 0ab1dc9c657f30434ca55a3dcc87e624af0b2116
[2/3] 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