[PATCH v2 0/2] misc: Add power-efuse driver

[PATCH v2 0/2] misc: Add power-efuse driver

[Zev Weiss]

Hello,

This is a second revision of the v1 patch series posted previously
[2].

Changes since v1:
 - dropped pmbus/lm25066 patches, submitted separately via hwmon tree [Guenter]
 - fixed indentation in power-efuse.yaml [Rob's bot]
 - added more detailed description in power-efuse.yaml [Rob]
 - added sysfs ABI documentation [Greg]
 - replaced manual struct attribute_group and sysfs_create_group()
   with ATTRIBUTE_GROUPS() and driver.dev_groups [Greg]

A lightly edited version of the previous cover letter follows.


This patch series is another incarnation of some previous efforts [0]
at enabling userspace access to the OPERATION state (and now status
flags) of PMBus devices, specifically with respect to efuses
protecting general-purpose power outputs.  This functionality is an
important component enabling a port of OpenBMC to the Delta AHE-50DC
Open19 power shelf [1].

The first patch adds dt-bindings, and the second adds the
implementation of the power-efuse driver.  The driver is fairly
simple; it merely provides a sysfs interface to enable, disable, and
retrieve error flags from an underlying regulator (which in the
expected usage will most likely be a PMBus device).

There is one aspect of its usage of the regulator API I'm a bit
uncertain about, however: this driver seems like a case where an
exclusive 'get' of the regulator (i.e. devm_regulator_get_exclusive()
instead of devm_regulator_get() in efuse_probe()) would be
appropriate, since in the intended usage no other device should be
using an efuse's regulator.  With an exclusive get though, the
regulator's use_count and the consumer's enable_count don't balance
out properly to allow the enable/disable operations to work properly
(the former ending up one more than the latter, leading to
enable_count underflows on attempts to disable the regulator).  So at
least for now it's using a non-exclusive get -- I'd be happy to hear
any pointers on a way to allow an exclusive get to work here, though.


Thanks,
Zev

[0] https://lore.kernel.org/openbmc/YGLepYLvtlO6Ikzs@hatter.bewilderbeest.net/
[1] https://www.open19.org/marketplace/delta-16kw-power-shelf/
[2] https://lore.kernel.org/openbmc/20220217104444.7695-1-zev@bewilderbeest.net/

Zev Weiss (2):
  dt-bindings: Add power-efuse binding
  misc: Add power-efuse driver

 .../ABI/testing/sysfs-driver-power-efuse      |  32 +++
 .../devicetree/bindings/misc/power-efuse.yaml |  49 ++++
 MAINTAINERS                                   |   5 +
 drivers/misc/Kconfig                          |  15 ++
 drivers/misc/Makefile                         |   1 +
 drivers/misc/power-efuse.c                    | 212 ++++++++++++++++++
 6 files changed, 314 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-driver-power-efuse
 create mode 100644 Documentation/devicetree/bindings/misc/power-efuse.yaml
 create mode 100644 drivers/misc/power-efuse.c

-- 
2.35.1

[PATCH v2 1/2] dt-bindings: Add power-efuse binding

[Zev Weiss]

This can be used to describe a power output supplied by a regulator
device that the system controls.

Signed-off-by: Zev Weiss <zev@bewilderbeest.net>
---
 .../devicetree/bindings/misc/power-efuse.yaml | 49 +++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/misc/power-efuse.yaml

diff --git a/Documentation/devicetree/bindings/misc/power-efuse.yaml b/Documentation/devicetree/bindings/misc/power-efuse.yaml
new file mode 100644
index 000000000000..5f8f0b21af0e
--- /dev/null
+++ b/Documentation/devicetree/bindings/misc/power-efuse.yaml
@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/misc/power-efuse.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Generic power efuse device
+
+maintainers:
+  - Zev Weiss <zev@bewilderbeest.net>
+
+description: |
+  This binding describes a physical power output supplied by a
+  regulator providing efuse functionality (manual on/off control, and
+  auto-shutoff if current, voltage, or thermal limits are exceeded).
+
+  These may be found on systems such as "smart" network PDUs, and
+  typically supply power to devices entirely separate from the system
+  described by the device-tree by way of an external connector such as
+  an Open19 power cable:
+
+  https://www.open19.org/marketplace/coolpower-cable-assembly-8ru/
+
+properties:
+  compatible:
+    const: power-efuse
+
+  vout-supply:
+    description:
+      phandle to the regulator providing power for the efuse
+
+  error-flags-cache-ttl-ms:
+    description:
+      The number of milliseconds the vout-supply regulator's error
+      flags should be cached before re-fetching them.
+
+required:
+  - compatible
+  - vout-supply
+
+additionalProperties: false
+
+examples:
+  - |
+    efuse {
+        compatible = "power-efuse";
+        vout-supply = <&efuse_reg>;
+        error-flags-cache-ttl-ms = <500>;
+    };
-- 
2.35.1

Re: [PATCH v2 1/2] dt-bindings: Add power-efuse binding

[Rob Herring]

On Mon, Mar 07, 2022 at 05:18:09PM -0800, Zev Weiss wrote:
> This can be used to describe a power output supplied by a regulator
> device that the system controls.
> 
> Signed-off-by: Zev Weiss <zev@bewilderbeest.net>
> ---
>  .../devicetree/bindings/misc/power-efuse.yaml | 49 +++++++++++++++++++
>  1 file changed, 49 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/misc/power-efuse.yaml
> 
> diff --git a/Documentation/devicetree/bindings/misc/power-efuse.yaml b/Documentation/devicetree/bindings/misc/power-efuse.yaml
> new file mode 100644
> index 000000000000..5f8f0b21af0e
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/misc/power-efuse.yaml
> @@ -0,0 +1,49 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/misc/power-efuse.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Generic power efuse device
> +
> +maintainers:
> +  - Zev Weiss <zev@bewilderbeest.net>
> +
> +description: |
> +  This binding describes a physical power output supplied by a
> +  regulator providing efuse functionality (manual on/off control, and
> +  auto-shutoff if current, voltage, or thermal limits are exceeded).
> +
> +  These may be found on systems such as "smart" network PDUs, and
> +  typically supply power to devices entirely separate from the system
> +  described by the device-tree by way of an external connector such as
> +  an Open19 power cable:
> +
> +  https://www.open19.org/marketplace/coolpower-cable-assembly-8ru/

Not really a helpful link...

I still don't understand what the h/w looks like here. At least I now 
understand we're talking a fuse on power rail, not efuses in an SoC 
used as OTP bits or feature disables.

> +
> +properties:
> +  compatible:
> +    const: power-efuse
> +
> +  vout-supply:
> +    description:
> +      phandle to the regulator providing power for the efuse

Vout is a supply to the efuse and not the rail being fused? 

Sorry, I know nothing about how an efuse is implemented so you are going 
to have to explain or draw it.

> +
> +  error-flags-cache-ttl-ms:
> +    description:
> +      The number of milliseconds the vout-supply regulator's error
> +      flags should be cached before re-fetching them.

How does one fetch/read? the error flags?

> +
> +required:
> +  - compatible
> +  - vout-supply
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    efuse {
> +        compatible = "power-efuse";
> +        vout-supply = <&efuse_reg>;
> +        error-flags-cache-ttl-ms = <500>;
> +    };
> -- 
> 2.35.1
> 
> 

Re: [PATCH v2 1/2] dt-bindings: Add power-efuse binding

[Zev Weiss]

On Fri, Mar 11, 2022 at 07:24:41AM PST, Rob Herring wrote:
>On Mon, Mar 07, 2022 at 05:18:09PM -0800, Zev Weiss wrote:
>> This can be used to describe a power output supplied by a regulator
>> device that the system controls.
>>
>> Signed-off-by: Zev Weiss <zev@bewilderbeest.net>
>> ---
>>  .../devicetree/bindings/misc/power-efuse.yaml | 49 +++++++++++++++++++
>>  1 file changed, 49 insertions(+)
>>  create mode 100644 Documentation/devicetree/bindings/misc/power-efuse.yaml
>>
>> diff --git a/Documentation/devicetree/bindings/misc/power-efuse.yaml b/Documentation/devicetree/bindings/misc/power-efuse.yaml
>> new file mode 100644
>> index 000000000000..5f8f0b21af0e
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/misc/power-efuse.yaml
>> @@ -0,0 +1,49 @@
>> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/misc/power-efuse.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Generic power efuse device
>> +
>> +maintainers:
>> +  - Zev Weiss <zev@bewilderbeest.net>
>> +
>> +description: |
>> +  This binding describes a physical power output supplied by a
>> +  regulator providing efuse functionality (manual on/off control, and
>> +  auto-shutoff if current, voltage, or thermal limits are exceeded).
>> +
>> +  These may be found on systems such as "smart" network PDUs, and
>> +  typically supply power to devices entirely separate from the system
>> +  described by the device-tree by way of an external connector such as
>> +  an Open19 power cable:
>> +
>> +  https://www.open19.org/marketplace/coolpower-cable-assembly-8ru/
>
>Not really a helpful link...
>
>I still don't understand what the h/w looks like here. At least I now
>understand we're talking a fuse on power rail, not efuses in an SoC
>used as OTP bits or feature disables.
>

The systems this would actually be used for would be things like these:
  - https://www.open19.org/marketplace/delta-16kw-power-shelf/
  - https://www.open19.org/marketplace/inspur-open19-power-shelf-ob19200l1/

The rightmost pictures on those pages show the four black connectors 
where the cable assembly linked in the patch plugs in, each of which 
provides the outputs from 12 such efuses, on 12 pairs of ground and 
+12VDC pins.  (There are also two more single outputs off to the side.)

It essentially just amounts to an external power output supplied by a 
regulator, with the regulator providing an on/off switch, overcurrent 
protection, etc.

And yes, the ambiguity of the "efuse" terminology is unfortunate (the 
"power-" prefix was an attempt to clarify it slightly).  That's the term 
used in the documentation for the hardware and hence is what I've called 
it here, but I'd be open to using a different name if that would help.

>> +
>> +properties:
>> +  compatible:
>> +    const: power-efuse
>> +
>> +  vout-supply:
>> +    description:
>> +      phandle to the regulator providing power for the efuse
>
>Vout is a supply to the efuse and not the rail being fused?

Yeah, that was a fairly muddled description -- it's really the latter.  
Perhaps:

   phandle to the regulator providing power for the output rail
   controlled by the efuse

?

>
>Sorry, I know nothing about how an efuse is implemented so you are going
>to have to explain or draw it.
>
>> +
>> +  error-flags-cache-ttl-ms:
>> +    description:
>> +      The number of milliseconds the vout-supply regulator's error
>> +      flags should be cached before re-fetching them.
>
>How does one fetch/read? the error flags?
>

In the specific case I'm dealing with, via PMBus STATUS_* commands, 
though I was aiming to keep this more generic so it could potentially be 
used to describe non-PMBus arrangements (in the Linux case, via whatever 
mechanism the implementation of the regulator's .get_error_flags() 
function uses).

>> +
>> +required:
>> +  - compatible
>> +  - vout-supply
>> +
>> +additionalProperties: false
>> +
>> +examples:
>> +  - |
>> +    efuse {
>> +        compatible = "power-efuse";
>> +        vout-supply = <&efuse_reg>;
>> +        error-flags-cache-ttl-ms = <500>;
>> +    };
>> --
>> 2.35.1
>>
>>

Re: [PATCH v2 1/2] dt-bindings: Add power-efuse binding

[Rob Herring]

On Fri, Mar 11, 2022 at 01:48:22PM -0800, Zev Weiss wrote:
> On Fri, Mar 11, 2022 at 07:24:41AM PST, Rob Herring wrote:
> > On Mon, Mar 07, 2022 at 05:18:09PM -0800, Zev Weiss wrote:
> > > This can be used to describe a power output supplied by a regulator
> > > device that the system controls.
> > > 
> > > Signed-off-by: Zev Weiss <zev@bewilderbeest.net>
> > > ---
> > >  .../devicetree/bindings/misc/power-efuse.yaml | 49 +++++++++++++++++++
> > >  1 file changed, 49 insertions(+)
> > >  create mode 100644 Documentation/devicetree/bindings/misc/power-efuse.yaml
> > > 
> > > diff --git a/Documentation/devicetree/bindings/misc/power-efuse.yaml b/Documentation/devicetree/bindings/misc/power-efuse.yaml
> > > new file mode 100644
> > > index 000000000000..5f8f0b21af0e
> > > --- /dev/null
> > > +++ b/Documentation/devicetree/bindings/misc/power-efuse.yaml
> > > @@ -0,0 +1,49 @@
> > > +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> > > +%YAML 1.2
> > > +---
> > > +$id: http://devicetree.org/schemas/misc/power-efuse.yaml#
> > > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > > +
> > > +title: Generic power efuse device
> > > +
> > > +maintainers:
> > > +  - Zev Weiss <zev@bewilderbeest.net>
> > > +
> > > +description: |
> > > +  This binding describes a physical power output supplied by a
> > > +  regulator providing efuse functionality (manual on/off control, and
> > > +  auto-shutoff if current, voltage, or thermal limits are exceeded).
> > > +
> > > +  These may be found on systems such as "smart" network PDUs, and
> > > +  typically supply power to devices entirely separate from the system
> > > +  described by the device-tree by way of an external connector such as
> > > +  an Open19 power cable:
> > > +
> > > +  https://www.open19.org/marketplace/coolpower-cable-assembly-8ru/
> > 
> > Not really a helpful link...
> > 
> > I still don't understand what the h/w looks like here. At least I now
> > understand we're talking a fuse on power rail, not efuses in an SoC
> > used as OTP bits or feature disables.
> > 
> 
> The systems this would actually be used for would be things like these:
>  - https://www.open19.org/marketplace/delta-16kw-power-shelf/
>  - https://www.open19.org/marketplace/inspur-open19-power-shelf-ob19200l1/

Those still don't help show me what the h/w looks like. High level 
schematics is what I'm looking for.


> The rightmost pictures on those pages show the four black connectors where
> the cable assembly linked in the patch plugs in, each of which provides the
> outputs from 12 such efuses, on 12 pairs of ground and +12VDC pins.  (There
> are also two more single outputs off to the side.)
> 
> It essentially just amounts to an external power output supplied by a
> regulator, with the regulator providing an on/off switch, overcurrent
> protection, etc.
> 
> And yes, the ambiguity of the "efuse" terminology is unfortunate (the
> "power-" prefix was an attempt to clarify it slightly).  That's the term
> used in the documentation for the hardware and hence is what I've called it
> here, but I'd be open to using a different name if that would help.
> 
> > > +
> > > +properties:
> > > +  compatible:
> > > +    const: power-efuse
> > > +
> > > +  vout-supply:
> > > +    description:
> > > +      phandle to the regulator providing power for the efuse
> > 
> > Vout is a supply to the efuse and not the rail being fused?
> 
> Yeah, that was a fairly muddled description -- it's really the latter.
> Perhaps:
> 
>   phandle to the regulator providing power for the output rail
>   controlled by the efuse
> 
> ?
> 
> > 
> > Sorry, I know nothing about how an efuse is implemented so you are going
> > to have to explain or draw it.
> > 
> > > +
> > > +  error-flags-cache-ttl-ms:
> > > +    description:
> > > +      The number of milliseconds the vout-supply regulator's error
> > > +      flags should be cached before re-fetching them.
> > 
> > How does one fetch/read? the error flags?
> > 
> 
> In the specific case I'm dealing with, via PMBus STATUS_* commands, though I
> was aiming to keep this more generic so it could potentially be used to
> describe non-PMBus arrangements (in the Linux case, via whatever mechanism
> the implementation of the regulator's .get_error_flags() function uses).

PMBus is I2C (subset). What device(s) is on the PMBus?

Here's what I've got for connections so far:

Vout(regulator)-->|efuse|-->12V

Host-->PMbus--->????

Rob

Re: [PATCH v2 1/2] dt-bindings: Add power-efuse binding

[Zev Weiss]

On Fri, Mar 11, 2022 at 04:08:47PM PST, Rob Herring wrote:
>On Fri, Mar 11, 2022 at 01:48:22PM -0800, Zev Weiss wrote:
>> On Fri, Mar 11, 2022 at 07:24:41AM PST, Rob Herring wrote:
>> > On Mon, Mar 07, 2022 at 05:18:09PM -0800, Zev Weiss wrote:
>> > > This can be used to describe a power output supplied by a regulator
>> > > device that the system controls.
>> > >
>> > > Signed-off-by: Zev Weiss <zev@bewilderbeest.net>
>> > > ---
>> > >  .../devicetree/bindings/misc/power-efuse.yaml | 49 +++++++++++++++++++
>> > >  1 file changed, 49 insertions(+)
>> > >  create mode 100644 Documentation/devicetree/bindings/misc/power-efuse.yaml
>> > >
>> > > diff --git a/Documentation/devicetree/bindings/misc/power-efuse.yaml b/Documentation/devicetree/bindings/misc/power-efuse.yaml
>> > > new file mode 100644
>> > > index 000000000000..5f8f0b21af0e
>> > > --- /dev/null
>> > > +++ b/Documentation/devicetree/bindings/misc/power-efuse.yaml
>> > > @@ -0,0 +1,49 @@
>> > > +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
>> > > +%YAML 1.2
>> > > +---
>> > > +$id: http://devicetree.org/schemas/misc/power-efuse.yaml#
>> > > +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> > > +
>> > > +title: Generic power efuse device
>> > > +
>> > > +maintainers:
>> > > +  - Zev Weiss <zev@bewilderbeest.net>
>> > > +
>> > > +description: |
>> > > +  This binding describes a physical power output supplied by a
>> > > +  regulator providing efuse functionality (manual on/off control, and
>> > > +  auto-shutoff if current, voltage, or thermal limits are exceeded).
>> > > +
>> > > +  These may be found on systems such as "smart" network PDUs, and
>> > > +  typically supply power to devices entirely separate from the system
>> > > +  described by the device-tree by way of an external connector such as
>> > > +  an Open19 power cable:
>> > > +
>> > > +  https://www.open19.org/marketplace/coolpower-cable-assembly-8ru/
>> >
>> > Not really a helpful link...
>> >
>> > I still don't understand what the h/w looks like here. At least I now
>> > understand we're talking a fuse on power rail, not efuses in an SoC
>> > used as OTP bits or feature disables.
>> >
>>
>> The systems this would actually be used for would be things like these:
>>  - https://www.open19.org/marketplace/delta-16kw-power-shelf/
>>  - https://www.open19.org/marketplace/inspur-open19-power-shelf-ob19200l1/
>
>Those still don't help show me what the h/w looks like. High level
>schematics is what I'm looking for.
>
>
>> The rightmost pictures on those pages show the four black connectors where
>> the cable assembly linked in the patch plugs in, each of which provides the
>> outputs from 12 such efuses, on 12 pairs of ground and +12VDC pins.  (There
>> are also two more single outputs off to the side.)
>>
>> It essentially just amounts to an external power output supplied by a
>> regulator, with the regulator providing an on/off switch, overcurrent
>> protection, etc.
>>
>> And yes, the ambiguity of the "efuse" terminology is unfortunate (the
>> "power-" prefix was an attempt to clarify it slightly).  That's the term
>> used in the documentation for the hardware and hence is what I've called it
>> here, but I'd be open to using a different name if that would help.
>>
>> > > +
>> > > +properties:
>> > > +  compatible:
>> > > +    const: power-efuse
>> > > +
>> > > +  vout-supply:
>> > > +    description:
>> > > +      phandle to the regulator providing power for the efuse
>> >
>> > Vout is a supply to the efuse and not the rail being fused?
>>
>> Yeah, that was a fairly muddled description -- it's really the latter.
>> Perhaps:
>>
>>   phandle to the regulator providing power for the output rail
>>   controlled by the efuse
>>
>> ?
>>
>> >
>> > Sorry, I know nothing about how an efuse is implemented so you are going
>> > to have to explain or draw it.
>> >
>> > > +
>> > > +  error-flags-cache-ttl-ms:
>> > > +    description:
>> > > +      The number of milliseconds the vout-supply regulator's error
>> > > +      flags should be cached before re-fetching them.
>> >
>> > How does one fetch/read? the error flags?
>> >
>>
>> In the specific case I'm dealing with, via PMBus STATUS_* commands, though I
>> was aiming to keep this more generic so it could potentially be used to
>> describe non-PMBus arrangements (in the Linux case, via whatever mechanism
>> the implementation of the regulator's .get_error_flags() function uses).
>
>PMBus is I2C (subset). What device(s) is on the PMBus?
>
>Here's what I've got for connections so far:
>
>Vout(regulator)-->|efuse|-->12V
>
>Host-->PMbus--->????
>

On the hardware I'm currently working with (the Delta unit linked 
above), the PMBus device is a TI LM25066 with various other components 
(MOSFET, thermal diode, sense resistor, etc.) in the surrounding 
circuitry.  My understanding is that "efuse" as used by the manufacturer 
refers to the combined circuit, including the LM25066.

Is that a sufficient "high level schematic", or is there additional 
information you're looking for?  I do have access to a detailed 
schematic of the circuit, but unfortunately I don't think I'm at liberty 
to share it.

(I don't know exactly what the Inspur unit uses because I haven't dealt 
with that one first-hand, but I'd guess it's probably broadly similar.)


Thanks,
Zev