On Tue, Oct 31, 2023 at 01:13:47AM +0800, Kyle Tso wrote:
> Commit 662a60102c12 ("usb: typec: Separate USB Power Delivery from USB
> Type-C") allows userspace to configure the PD of a port by selecting
> different set of predefined PD capabilities. Define the PD capability
> sets in DT for better configurability in device modules.
What Linux userspace does is irrelevant to bindings. Explain this in
terms of the h/w having multiple capabilities. I'm still not clear how
this is tied to the h/w rather than just multiple configurations within
the limits of what the h/w can support.
>
> Define a child node "capabilities" to contain multiple USB Power
> Delivery capabilities.
>
> Define a child node with pattern (e.g. caps-0, caps-1) under
> "capabilities". Each node contains PDO data of a selectable Power
> Delivery capability.
>
> Also define common properties for source-pdos, sink-pdos, and
> op-sink-microwatt that can be referenced.
>
> Signed-off-by: Kyle Tso <kyletso@xxxxxxxxxx>
> ---
> v2 -> v3
> - Updated the commit message
> - Remain unchanged for the comments about the property/node refactor
>
> .../bindings/connector/usb-connector.yaml | 80 +++++++++++++------
> 1 file changed, 57 insertions(+), 23 deletions(-)
>
> diff --git a/Documentation/devicetree/bindings/connector/usb-connector.yaml b/Documentation/devicetree/bindings/connector/usb-connector.yaml
> index 7c8a3e8430d3..d7ece063cb2c 100644
> --- a/Documentation/devicetree/bindings/connector/usb-connector.yaml
> +++ b/Documentation/devicetree/bindings/connector/usb-connector.yaml
> @@ -120,28 +120,10 @@ properties:
> # The following are optional properties for "usb-c-connector" with power
> # delivery support.
> source-pdos:
> - description: An array of u32 with each entry providing supported power
> - source data object(PDO), the detailed bit definitions of PDO can be found
> - in "Universal Serial Bus Power Delivery Specification" chapter 6.4.1.2
> - Source_Capabilities Message, the order of each entry(PDO) should follow
> - the PD spec chapter 6.4.1. Required for power source and power dual role.
> - User can specify the source PDO array via PDO_FIXED/BATT/VAR/PPS_APDO()
> - defined in dt-bindings/usb/pd.h.
> - minItems: 1
> - maxItems: 7
> - $ref: /schemas/types.yaml#/definitions/uint32-array
> + $ref: "#/$defs/source-pdos"
>
> sink-pdos:
> - description: An array of u32 with each entry providing supported power sink
> - data object(PDO), the detailed bit definitions of PDO can be found in
> - "Universal Serial Bus Power Delivery Specification" chapter 6.4.1.3
> - Sink Capabilities Message, the order of each entry(PDO) should follow the
> - PD spec chapter 6.4.1. Required for power sink and power dual role. User
> - can specify the sink PDO array via PDO_FIXED/BATT/VAR/PPS_APDO() defined
> - in dt-bindings/usb/pd.h.
> - minItems: 1
> - maxItems: 7
> - $ref: /schemas/types.yaml#/definitions/uint32-array
> + $ref: "#/$defs/sink-pdos"
>
> sink-vdos:
> description: An array of u32 with each entry, a Vendor Defined Message Object (VDO),
> @@ -167,9 +149,7 @@ properties:
> $ref: /schemas/types.yaml#/definitions/uint32-array
>
> op-sink-microwatt:
> - description: Sink required operating power in microwatt, if source can't
> - offer the power, Capability Mismatch is set. Required for power sink and
> - power dual role.
> + $ref: "#/$defs/op-sink-microwatt"
>
> port:
> $ref: /schemas/graph.yaml#/properties/port
> @@ -231,6 +211,30 @@ properties:
> SNK_READY for non-pd link.
> type: boolean
>
> + capabilities:
> + description: A child node to contain all the selectable USB Power Delivery capabilities.
> + type: object
> +
> + patternProperties:
> + "^caps-[0-9]+$":
> + description: Child nodes under "capabilities" node. Each node contains a selectable USB
> + Power Delivery capability.
> + type: object
> +
> + properties:
> + source-pdos:
> + $ref: "#/$defs/source-pdos"
> +
> + sink-pdos:
> + $ref: "#/$defs/sink-pdos"
> +
> + op-sink-microwatt:
> + $ref: "#/$defs/op-sink-microwatt"
> +
> + additionalProperties: false
> +
> + additionalProperties: false
> +
> dependencies:
> sink-vdos-v1: [ sink-vdos ]
> sink-vdos: [ sink-vdos-v1 ]
> @@ -238,6 +242,36 @@ dependencies:
> required:
> - compatible
>
> +$defs:
> + source-pdos:
Rather than a bunch a $refs to per property definitions, define the
collection of properties and then reference that collection:
$defs:
capabilities:
type: object
properties:
source-pdos: ...
And then at the node level, make the reference:
"^caps-[0-9]+$":
$ref: "#/$defs/capabilities"
unevaluatedProperties: false
Rob
