On Mon, 17 Mar 2025 11:08:02 +0200
<marius.cristea@xxxxxxxxxxxxx> wrote:
> From: Marius Cristea <marius.cristea@xxxxxxxxxxxxx>
>
> This is the device tree schema for iio driver for Microchip PAC194X and
> PAC195X series of Power Monitors with Accumulator.
Wrapping of commit message is a little messy. Either just have one paragraph
or add some bland lines to make the paragraph breaks look more intentional.
> The PAC194X family supports 9V Full-Scale Range and the PAC195X supports
> 32V Full-Scale Range.
> There are two versions of the PAC194X/5X: the PAC194X/5X-1 devices are
> for high-side current sensing and the PAC194X/5X-2 devices are for
> low-side current sensing or floating VBUS applications.
> The PAC194X/5X-1 is named shortly PAC194X/5X.
>
> Signed-off-by: Marius Cristea <marius.cristea@xxxxxxxxxxxxx>
> ---
> .../bindings/iio/adc/microchip,pac1944.yaml | 195 ++++++++++++++++++
> 1 file changed, 195 insertions(+)
> create mode 100644 Documentation/devicetree/bindings/iio/adc/microchip,pac1944.yaml
>
> diff --git a/Documentation/devicetree/bindings/iio/adc/microchip,pac1944.yaml b/Documentation/devicetree/bindings/iio/adc/microchip,pac1944.yaml
> new file mode 100644
> index 000000000000..1997e889e3f6
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/adc/microchip,pac1944.yaml
> +
> + microchip,vbus-mode:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + In order to increase measurement resolution and keeping the same
> + number the of bits the device has a configurable VBUS full range
> + scale (FSR). The range should be set by hardware design and it should
> + not be changed during runtime. The bipolar capability for VBUS enables
> + accurate offset measurement and correction.
> + The VBUS could be configured into the following full scale range
> + <0> - VBUS has unipolar +32V to 0V FSR (default) for PAC195X
> + or +9V to 0V (default) for PAC194X
> + <1> - VBUS has bipolar +32V to -32V FSR for PAC195X
> + or +9V to -9V for PAC194X. The actual range is limited to
> + about -200 mV due to the impact of the ESD structures.
> + <2> - VBUS has bipolar +16V to -16V FSR for PAC195X
> + or +4.5V to -4.5V for PAC194X. The actual range is limited
> + to about -200 mV due to the impact of the ESD structures.
> + maximum: 2
There are examples in tree of multirange devices where we specify the pair
of negative and positive limits. That makes for easy to read DT by
avoiding the use of enums.
> +
> + microchip,vsense-mode:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + In order to decrease the power dissipation on the shunt resistor and
> + in the same time to increase measurement resolution by keeping the
> + same number the of bits the device has a configurable VSENSE full
> + range scale (FSR). The range should be set by hardware design and it
> + should not be changed during runtime.
> + The VSENSE could be configured into the following full scale range
> + <0> - VSENSE has unipolar +100 mV to 0V FSR (default)
> + <1> - VSENSE has bipolar +100 mV to -100 mV FSR
> + <2> - VSENSE has bipolar +50 mV to -50 mV FSR
> + maximum: 2
Similar to above. Consider allowing <0, 100>, <-100, 100>. <-50, 50>
I'm curious why you've documented them as positive to negative above.
> +
> + microchip,accumulation-mode:
> + $ref: /schemas/types.yaml#/definitions/uint32
> + description:
> + The Hardware Accumulator may be used to accumulate VPOWER, VSENSE or
> + VBUS values for any channel. By setting the accumulator for a channel
> + to accumulate the VPOWER values gives a measure of accumulated power
> + into a time period, which is equivalent to energy. Setting the
> + accumulator for a channel to accumulate VSENSE values gives a measure
> + of accumulated current, which is equivalent to charge. This allows the
> + accumulator to be used as a coulomb counter. For either VSENSE or
> + VBUS, many samples may be accumulated on chip and the result collected
> + by the host and divided by the accumulator counter count value to
> + yield an average value with a very long integration time to reduce
> + noise. This feature is also very useful for system calibration,
> + allowing many averages to be accumulated for fast averaging/noise
> + reduction.
> + This functionality needs to be setup once and must not be changed
> + during the runtime, just in case the user wants to measure the charge
> + or the energy consumed from board power up till the user has control
> + or during a reboot of the system.
This one feels like it really isn't a one time thing.
For a few somewhat similarly behaving things (step counts on pedometers for example)
we have explicit channel enabled attributes. Here you could just prevent
any other actions that would break the accumulation after the software has opted
in to enable a particular energy channel. If you need to fake a reset of similar
just check the counter and subtract it in software after a channel change.
> + The Hardware Accumulator could be configured to accumulate
> + VPOWER, VSENSE or VBUS
> + <0> - Accumulator accumulates VPOWER (default)
> + <1> - Accumulator accumulates VSENSE
> + <2> - Accumulator accumulates VBUS
> + maximum: 2
If we do keep it in here then have
default: 0 and don't specify it in the examples below.
Jonathan
