[PATCH] dt-bindings: power: supply: battery: allow longer ocv-capacity tables

[PATCH] dt-bindings: power: supply: battery: allow longer ocv-capacity tables

[Ryan Brue]

ocv-capacity-table-N has been capped at 100 points since battery.txt was
converted to YAML, where the limit arrived without a stated reason.

The MT6397 fuel gauge is characterised per temperature by a table the
Amazon Fire HD 10 (2017) vendor device tree carries with 126 points, of
which 122 are expressible here - the remainder are greater than 100%
discharged, so the binding excludes those points. Boards carrying this
PMIC fuel gauge would need more than 100 points to describe the pack with
the generic property. Raise the cap to 128.

Assisted-by: LLM
Signed-off-by: Ryan Brue <ryanbrue.dev@gmail.com>
---
No kernel change goes with this. power_supply_get_battery_info() sizes each
ocv-capacity-table-N from the property itself -- it reads the length with
fwnode_property_count_u32() and devm_kcalloc()s that many entries -- so
maxItems in the binding is the only cap on points per table.
POWER_SUPPLY_OCV_TEMP_MAX bounds the number of tables, not their length.

The consumer that wants this is an MT6397 PMIC fuel gauge not yet posted;
its pack is characterised at 126 points per temperature in the vendor's
kernel (Amazon Fire OS, based on Linux 3.18), with 122 of those points
being expressible with the generic property (the rest are greater than
100%).
---
 Documentation/devicetree/bindings/power/supply/battery.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/power/supply/battery.yaml b/Documentation/devicetree/bindings/power/supply/battery.yaml
index 8ebf05d9497c..a6d4822f591c 100644
--- a/Documentation/devicetree/bindings/power/supply/battery.yaml
+++ b/Documentation/devicetree/bindings/power/supply/battery.yaml
@@ -154,7 +154,7 @@ patternProperties:
       of the battery and corresponding battery capacity percent, which is used
       to look up battery capacity according to current OCV value. And the open
       circuit voltage unit is microvolt.
-    maxItems: 100
+    maxItems: 128
     items:
       items:
         - description: open circuit voltage (OCV) in microvolts

---
base-commit: fd73f4a6659897191fa0d40695fe370925dd3780
change-id: 20260917-rbrue-suez-upstreaming-battery-ocv-table-128-9ba83f9313bb

Best regards,
--  
Ryan Brue <ryanbrue.dev@gmail.com>

Re: [PATCH] dt-bindings: power: supply: battery: allow longer ocv-capacity tables

[Henrik Grimler]

Hi Ryan,

On Fri, Sep 18, 2026 at 12:36:31AM -0500, Ryan Brue wrote:
> ocv-capacity-table-N has been capped at 100 points since battery.txt was
> converted to YAML, where the limit arrived without a stated reason.
> 
> The MT6397 fuel gauge is characterised per temperature by a table the
> Amazon Fire HD 10 (2017) vendor device tree carries with 126 points, of
> which 122 are expressible here - the remainder are greater than 100%
> discharged, so the binding excludes those points. Boards carrying this
> PMIC fuel gauge would need more than 100 points to describe the pack with
> the generic property. Raise the cap to 128.
> 
> Assisted-by: LLM
> Signed-off-by: Ryan Brue <ryanbrue.dev@gmail.com>
> ---
> No kernel change goes with this. power_supply_get_battery_info() sizes each
> ocv-capacity-table-N from the property itself -- it reads the length with
> fwnode_property_count_u32() and devm_kcalloc()s that many entries -- so
> maxItems in the binding is the only cap on points per table.
> POWER_SUPPLY_OCV_TEMP_MAX bounds the number of tables, not their length.
> 
> The consumer that wants this is an MT6397 PMIC fuel gauge not yet posted;
> its pack is characterised at 126 points per temperature in the vendor's
> kernel (Amazon Fire OS, based on Linux 3.18), with 122 of those points
> being expressible with the generic property (the rest are greater than
> 100%).

Allowing for points > 100 % could make sense, but why would you need
122 points up to 100 %? If the vendor kernel has several values at for
example 20 %, then a better solution is probably to take the average
of them.

I think only reason to have multiple values for the same percentage
would be if hysterersis (see for example this open-access article [1]
for discussion about hysteresis) is taken into account, i.e. having
one table for charge direction, and one table for discharge direction,
but I don't think any driver uses multiple tables to handle something
like that.

[1] https://doi.org/10.1038/s41598-019-51474-5

Best regards,
Henrik Grimler

> ---
>  Documentation/devicetree/bindings/power/supply/battery.yaml | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/devicetree/bindings/power/supply/battery.yaml b/Documentation/devicetree/bindings/power/supply/battery.yaml
> index 8ebf05d9497c..a6d4822f591c 100644
> --- a/Documentation/devicetree/bindings/power/supply/battery.yaml
> +++ b/Documentation/devicetree/bindings/power/supply/battery.yaml
> @@ -154,7 +154,7 @@ patternProperties:
>        of the battery and corresponding battery capacity percent, which is used
>        to look up battery capacity according to current OCV value. And the open
>        circuit voltage unit is microvolt.
> -    maxItems: 100
> +    maxItems: 128
>      items:
>        items:
>          - description: open circuit voltage (OCV) in microvolts
> 
> ---
> base-commit: fd73f4a6659897191fa0d40695fe370925dd3780
> change-id: 20260917-rbrue-suez-upstreaming-battery-ocv-table-128-9ba83f9313bb
> 
> Best regards,
> --  
> Ryan Brue <ryanbrue.dev@gmail.com>
> 

Re: [PATCH] dt-bindings: power: supply: battery: allow longer ocv-capacity tables

[Ryan Brue]

On 9/18/26 3:29 AM, Henrik Grimler wrote:
> Hi Ryan,
>
> On Fri, Sep 18, 2026 at 12:36:31AM -0500, Ryan Brue wrote:
>> ocv-capacity-table-N has been capped at 100 points since battery.txt was
>> converted to YAML, where the limit arrived without a stated reason.
>>
>> The MT6397 fuel gauge is characterised per temperature by a table the
>> Amazon Fire HD 10 (2017) vendor device tree carries with 126 points, of
>> which 122 are expressible here - the remainder are greater than 100%
>> discharged, so the binding excludes those points. Boards carrying this
>> PMIC fuel gauge would need more than 100 points to describe the pack with
>> the generic property. Raise the cap to 128.
>>
>> Assisted-by: LLM
>> Signed-off-by: Ryan Brue <ryanbrue.dev@gmail.com>
>> ---
>> No kernel change goes with this. power_supply_get_battery_info() sizes each
>> ocv-capacity-table-N from the property itself -- it reads the length with
>> fwnode_property_count_u32() and devm_kcalloc()s that many entries -- so
>> maxItems in the binding is the only cap on points per table.
>> POWER_SUPPLY_OCV_TEMP_MAX bounds the number of tables, not their length.
>>
>> The consumer that wants this is an MT6397 PMIC fuel gauge not yet posted;
>> its pack is characterised at 126 points per temperature in the vendor's
>> kernel (Amazon Fire OS, based on Linux 3.18), with 122 of those points
>> being expressible with the generic property (the rest are greater than
>> 100%).
> Allowing for points > 100 % could make sense, but why would you need
> 122 points up to 100 %? If the vendor kernel has several values at for
> example 20 %, then a better solution is probably to take the average
> of them.
>
> I think only reason to have multiple values for the same percentage
> would be if hysterersis (see for example this open-access article [1]
> for discussion about hysteresis) is taken into account, i.e. having
> one table for charge direction, and one table for discharge direction,
> but I don't think any driver uses multiple tables to handle something
> like that.
>
> [1] https://doi.org/10.1038/s41598-019-51474-5
>
> Best regards,
> Henrik Grimler
Hi Henrik,
Yeah, you're right. To be honest, I didn't think about that, and should 
have.

On why there's so many points: the vendor's table isn't indexed by 
percentage at all. A row is a fixed 54 mAh step of charge - 
step_of_qmax, which the meter converts to mAh directly - and the 
percentage column is just that rounded, round(i * 54 * 100 / Qmax), 
which fits every row of all five tables exactly. At 0.85% per row about 
one in six repeats, so the duplicates carry nothing. I should also 
correct the figures I sent: 126/122 is a different cell in the same 
vendor file. This unit's tables are 120 points and none of the points 
are above 100% in this one.

I don't need to model the vendor one to one. I measured what dropping 
resolution costs, and decimating to 100 points changes the capacity I 
report by at most 1% - so it fits the binding as it stands, and the 
justification I sent doesn't hold.

The only thing I can see still being worth raising is 101 rather than 
128. Capacity percent is capped at 100, and 0..100 inclusive is 101 
values, so if I'm not mistaken no board can express 1% granularity today 
if they have points at both 0 and 100. I'm not sure that's worth a patch 
on its own, so I'm fine dropping this, or doing a v2 allowing 101 values.

Best regards,
Ryan Brue