1. Patchew
  2. linux
  3. [PATCH v3 0/2] mutiple selectable capabilities in tcpm
  4. View patch

[PATCH v3 1/2] dt-bindings: connector: Add child nodes for multiple PD capabilities

Kyle Tso posted 2 patches 2 years, 2 months ago
There is a newer version of this series
[PATCH v3 1/2] dt-bindings: connector: Add child nodes for multiple PD capabilities
Posted by Kyle Tso 2 years, 2 months ago 
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.

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@google.com>
---
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:
+    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
+
+  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
+
+  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.
+
 allOf:
   - if:
       properties:
-- 
2.42.0.820.g83a721a137-goog
Re: [PATCH v3 1/2] dt-bindings: connector: Add child nodes for multiple PD capabilities
Posted by Rob Herring 2 years, 1 month ago 
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@google.com>
> ---
> 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

Patchew 2.1-devel-b67e4c2

© 2016 - 2025 Red Hat, Inc.