[1/5] dt-bindings: connector: add fixed-batteries property

From: Amit Sunil Dhamne <amitsd@google.com>

Add a new "fixed-batteries" DT property to connector class. This
property is populated with nodes associated with battery type power
supplies powering the USB PD connector. This is needed by the Type-C
Port Manager (TCPM) to query psy properties which are used to feed
Battery_Status & Battery_Capacity AMS.

Signed-off-by: Amit Sunil Dhamne <amitsd@google.com>
---
 Documentation/devicetree/bindings/connector/usb-connector.yaml | 8 ++++++++
 Documentation/devicetree/bindings/usb/maxim,max33359.yaml      | 1 +
 2 files changed, 9 insertions(+)

On Wed, Mar 12, 2025 at 04:42:01PM -0700, Amit Sunil Dhamne wrote:
> Add a new "fixed-batteries" DT property to connector class. This
> property is populated with nodes associated with battery type power
> supplies powering the USB PD connector. This is needed by the Type-C
> Port Manager (TCPM) to query psy properties which are used to feed

What is "psy" in terms of bindings?

> Battery_Status & Battery_Capacity AMS.
> 
> Signed-off-by: Amit Sunil Dhamne <amitsd@google.com>
> ---
>  Documentation/devicetree/bindings/connector/usb-connector.yaml | 8 ++++++++
>  Documentation/devicetree/bindings/usb/maxim,max33359.yaml      | 1 +
>  2 files changed, 9 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/connector/usb-connector.yaml b/Documentation/devicetree/bindings/connector/usb-connector.yaml
> index 11e40d225b9f3a0d0aeea7bf764f1c00a719d615..5e15bc060f5a2cfce842f83de738f1e8bae3ce2d 100644
> --- a/Documentation/devicetree/bindings/connector/usb-connector.yaml
> +++ b/Documentation/devicetree/bindings/connector/usb-connector.yaml
> @@ -300,6 +300,14 @@ properties:
>      $ref: /schemas/types.yaml#/definitions/uint8-array
>      maxItems: 4
>  
> +  fixed-batteries:
> +    description: Contains references to nodes associated with battery type power
> +      supplies powering the USB PD device. These batteries are fixed type and

What is a "battery type power supply"? If you just link here batteries,
then we have type for it - monitored-battery - but I doubt connector has
direct connection to the battery.

If you mean chargers, the OF graph is already there for this and no need
for this patch.

> +      not hot swappable.
> +    minItems: 1
> +    maxItems: 4
> +    $ref: /schemas/types.yaml#/definitions/phandle-array
> +
>  dependencies:
>    sink-vdos-v1: [ sink-vdos ]
>    sink-vdos: [ sink-vdos-v1 ]
> diff --git a/Documentation/devicetree/bindings/usb/maxim,max33359.yaml b/Documentation/devicetree/bindings/usb/maxim,max33359.yaml
> index 3de4dc40b79192b60443421b557bd2fb18683bf7..66c99f0131f074f1c08e31d7481f555647e3b2f8 100644
> --- a/Documentation/devicetree/bindings/usb/maxim,max33359.yaml
> +++ b/Documentation/devicetree/bindings/usb/maxim,max33359.yaml
> @@ -75,6 +75,7 @@ examples:
>                                         PDO_FIXED(9000, 2000, 0)>;
>                  sink-bc12-completion-time-ms = <500>;
>                  pd-revision = /bits/ 8 <0x03 0x01 0x01 0x08>;
> +                fixed-batteries = <&batt1 &batt2>;

Two phandles, so two <>.

Best regards,
Krzysztof

Hi Krzysztof,

On 3/13/25 1:48 AM, Krzysztof Kozlowski wrote:
> On Wed, Mar 12, 2025 at 04:42:01PM -0700, Amit Sunil Dhamne wrote:
>> Add a new "fixed-batteries" DT property to connector class. This
>> property is populated with nodes associated with battery type power
>> supplies powering the USB PD connector. This is needed by the Type-C
>> Port Manager (TCPM) to query psy properties which are used to feed
> What is "psy" in terms of bindings?
In terms of bindings this should be a phandle to a device that 
owns/manages the battery (whose driver will eventually call 
devm_power_supply_register to register the battery). This could be a 
fuel-guage ("sprd,sc2731-fgu", say), charger ("ti,bq24190") or a 
platform device ("cw2015") containing "monitored-battery" property to 
manage the simple battery.
>> Battery_Status & Battery_Capacity AMS.
>>
>> Signed-off-by: Amit Sunil Dhamne <amitsd@google.com>
>> ---
>>   Documentation/devicetree/bindings/connector/usb-connector.yaml | 8 ++++++++
>>   Documentation/devicetree/bindings/usb/maxim,max33359.yaml      | 1 +
>>   2 files changed, 9 insertions(+)
>>
>> diff --git a/Documentation/devicetree/bindings/connector/usb-connector.yaml b/Documentation/devicetree/bindings/connector/usb-connector.yaml
>> index 11e40d225b9f3a0d0aeea7bf764f1c00a719d615..5e15bc060f5a2cfce842f83de738f1e8bae3ce2d 100644
>> --- a/Documentation/devicetree/bindings/connector/usb-connector.yaml
>> +++ b/Documentation/devicetree/bindings/connector/usb-connector.yaml
>> @@ -300,6 +300,14 @@ properties:
>>       $ref: /schemas/types.yaml#/definitions/uint8-array
>>       maxItems: 4
>>   
>> +  fixed-batteries:
>> +    description: Contains references to nodes associated with battery type power
>> +      supplies powering the USB PD device. These batteries are fixed type and
> What is a "battery type power supply"? If you just link here batteries,
> then we have type for it - monitored-battery - but I doubt connector has
> direct connection to the battery.
Regarding "nodes associated with battery type power supplies", I meant 
something like a fuel guage or a charger OR platform device with 
"monitored-battery" that will manage the battery lifecycle. If I use 
monitored-battery for this, I will be restricted to only querying 1 
simple battery. Also, I don't mean PD connector device to be a fuel 
guage or charger that manages a specific battery. It should just be able 
to query any FG/Chg for the battery status to relay that info to the 
connector's port partner.

The intent of the patchset & this change is for the USB Type C protocol 
manager module (that consumes these bindings) to be able to get info 
(such as State of charge, design capacity, etc) from drivers that manage 
the battery/batteries in the system. In order for such info to propagate 
I need to hook up the references of these battery manager devices (fuel 
guages, etc.) to connector.

I have addressed the connector <-> battery question in the cover letter.


> If you mean chargers, the OF graph is already there for this and no need
> for this patch.

No I don't mean just chargers in this case. Also, I didn't follow you on 
the OF graph. Please can you explain further?


>
>> +      not hot swappable.
>> +    minItems: 1
>> +    maxItems: 4
>> +    $ref: /schemas/types.yaml#/definitions/phandle-array
>> +
>>   dependencies:
>>     sink-vdos-v1: [ sink-vdos ]
>>     sink-vdos: [ sink-vdos-v1 ]
>> diff --git a/Documentation/devicetree/bindings/usb/maxim,max33359.yaml b/Documentation/devicetree/bindings/usb/maxim,max33359.yaml
>> index 3de4dc40b79192b60443421b557bd2fb18683bf7..66c99f0131f074f1c08e31d7481f555647e3b2f8 100644
>> --- a/Documentation/devicetree/bindings/usb/maxim,max33359.yaml
>> +++ b/Documentation/devicetree/bindings/usb/maxim,max33359.yaml
>> @@ -75,6 +75,7 @@ examples:
>>                                          PDO_FIXED(9000, 2000, 0)>;
>>                   sink-bc12-completion-time-ms = <500>;
>>                   pd-revision = /bits/ 8 <0x03 0x01 0x01 0x08>;
>> +                fixed-batteries = <&batt1 &batt2>;
> Two phandles, so two <>.

Ack. Will fix it in the next revision.

Thanks,

Amit

> Best regards,
> Krzysztof
>

On 15/03/2025 01:56, Amit Sunil Dhamne wrote:
> Hi Krzysztof,
> 
> On 3/13/25 1:48 AM, Krzysztof Kozlowski wrote:
>> On Wed, Mar 12, 2025 at 04:42:01PM -0700, Amit Sunil Dhamne wrote:
>>> Add a new "fixed-batteries" DT property to connector class. This
>>> property is populated with nodes associated with battery type power
>>> supplies powering the USB PD connector. This is needed by the Type-C
>>> Port Manager (TCPM) to query psy properties which are used to feed
>> What is "psy" in terms of bindings?
> In terms of bindings this should be a phandle to a device that 
> owns/manages the battery (whose driver will eventually call 
> devm_power_supply_register to register the battery). This could be a 

So a charger? Please rephrain from putting Linux names into the bindings
description.

> fuel-guage ("sprd,sc2731-fgu", say), charger ("ti,bq24190") or a 
> platform device ("cw2015") containing "monitored-battery" property to 
> manage the simple battery.


>>> Battery_Status & Battery_Capacity AMS.
>>>
>>> Signed-off-by: Amit Sunil Dhamne <amitsd@google.com>
>>> ---
>>>   Documentation/devicetree/bindings/connector/usb-connector.yaml | 8 ++++++++
>>>   Documentation/devicetree/bindings/usb/maxim,max33359.yaml      | 1 +
>>>   2 files changed, 9 insertions(+)
>>>
>>> diff --git a/Documentation/devicetree/bindings/connector/usb-connector.yaml b/Documentation/devicetree/bindings/connector/usb-connector.yaml
>>> index 11e40d225b9f3a0d0aeea7bf764f1c00a719d615..5e15bc060f5a2cfce842f83de738f1e8bae3ce2d 100644
>>> --- a/Documentation/devicetree/bindings/connector/usb-connector.yaml
>>> +++ b/Documentation/devicetree/bindings/connector/usb-connector.yaml
>>> @@ -300,6 +300,14 @@ properties:
>>>       $ref: /schemas/types.yaml#/definitions/uint8-array
>>>       maxItems: 4
>>>   
>>> +  fixed-batteries:
>>> +    description: Contains references to nodes associated with battery type power
>>> +      supplies powering the USB PD device. These batteries are fixed type and
>> What is a "battery type power supply"? If you just link here batteries,
>> then we have type for it - monitored-battery - but I doubt connector has
>> direct connection to the battery.
> Regarding "nodes associated with battery type power supplies", I meant 
> something like a fuel guage or a charger OR platform device with 
> "monitored-battery" that will manage the battery lifecycle. If I use 
> monitored-battery for this, I will be restricted to only querying 1 
> simple battery. Also, I don't mean PD connector device to be a fuel 
> guage or charger that manages a specific battery. It should just be able 
> to query any FG/Chg for the battery status to relay that info to the 
> connector's port partner.
> 
> The intent of the patchset & this change is for the USB Type C protocol 
> manager module (that consumes these bindings) to be able to get info 

The intent should be rather to accurately describe hardware and maybe
that's the problem - you focus how to bend it for your drivers.


Best regards,
Krzysztof

On 15/03/2025 01:56, Amit Sunil Dhamne wrote:
> The intent of the patchset & this change is for the USB Type C protocol 
> manager module (that consumes these bindings) to be able to get info 
> (such as State of charge, design capacity, etc) from drivers that manage 
> the battery/batteries in the system. In order for such info to propagate 
> I need to hook up the references of these battery manager devices (fuel 
> guages, etc.) to connector.
> 
> I have addressed the connector <-> battery question in the cover letter.
> 
> 
>> If you mean chargers, the OF graph is already there for this and no need
>> for this patch.
> 
> No I don't mean just chargers in this case. Also, I didn't follow you on 
> the OF graph. Please can you explain further?
> 
You are duplicating existing bindings and existing practice of
describing the actual connections via OF graph. And the binding already
has the OF graph. What to explain more? Please open the binding and look
at the ports. Maybe they are incomplete? Look how other USB and USB
Type-C connections are represented.

Best regards,
Krzysztof