[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>

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 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 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