Documentation/devicetree/bindings/connector/usb-connector.yaml

# SPDX-License-Identifier: GPL-2.0-only
%YAML 1.2
---
$id: http://devicetree.org/schemas/connector/usb-connector.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: USB Connector

maintainers:
  - Rob Herring <robh@kernel.org>

description:
  A USB connector node represents a physical USB connector. It should be a child
  of a USB interface controller.

properties:
  compatible:
    enum:
      - usb-a-connector
      - usb-b-connector
      - usb-c-connector

  label:
    description: Symbolic name for the connector.

  type:
    description: Size of the connector, should be specified in case of
      non-fullsize 'usb-a-connector' or 'usb-b-connector' compatible
      connectors.
    allOf:
      - $ref: /schemas/types.yaml#definitions/string
    enum:
      - mini
      - micro

  self-powered:
    description: Set this property if the USB device has its own power source.
    type: boolean

  # The following are optional properties for "usb-b-connector".
  id-gpios:
    description: An input gpio for USB ID pin.
    maxItems: 1

  vbus-gpios:
    description: An input gpio for USB VBus pin, used to detect presence of
      VBUS 5V.
    maxItems: 1

  vbus-supply:
    description: A phandle to the regulator for USB VBUS if needed when host
      mode or dual role mode is supported.
      Particularly, if use an output GPIO to control a VBUS regulator, should
      model it as a regulator. See bindings/regulator/fixed-regulator.yaml

  # The following are optional properties for "usb-c-connector".
  power-role:
    description: Determines the power role that the Type C connector will
      support. "dual" refers to Dual Role Port (DRP).
    allOf:
      - $ref: /schemas/types.yaml#definitions/string
    enum:
      - source
      - sink
      - dual

  try-power-role:
    description: Preferred power role.
    allOf:
      - $ref: /schemas/types.yaml#definitions/string
    enum:
     - source
     - sink
     - dual

  data-role:
    description: Data role if Type C connector supports USB data. "dual" refers
      Dual Role Device (DRD).
    allOf:
      - $ref: /schemas/types.yaml#definitions/string
    enum:
      - host
      - device
      - dual

  # 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
    allOf:
      - $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
    allOf:
      - $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.

  ports:
    description: OF graph bindings (specified in bindings/graph.txt) that model
      any data bus to the connector unless the bus is between parent node and
      the connector. Since a single connector can have multiple data buses every
      bus has an assigned OF graph port number as described below.
    type: object
    properties:
      port@0:
        type: object
        description: High Speed (HS), present in all connectors.

      port@1:
        type: object
        description: Super Speed (SS), present in SS capable connectors.

      port@2:
        type: object
        description: Sideband Use (SBU), present in USB-C. This describes the
          alternate mode connection of which SBU is a part.

    required:
      - port@0

required:
  - compatible

examples:
  # Micro-USB connector with HS lines routed via controller (MUIC).
  - |+
    muic-max77843 {
      usb_con1: connector {
        compatible = "usb-b-connector";
        label = "micro-USB";
        type = "micro";
      };
    };

  # USB-C connector attached to CC controller (s2mm005), HS lines routed
  # to companion PMIC (max77865), SS lines to USB3 PHY and SBU to DisplayPort.
  # DisplayPort video lines are routed to the connector via SS mux in USB3 PHY.
  - |+
    ccic: s2mm005 {
      usb_con2: connector {
        compatible = "usb-c-connector";
        label = "USB-C";

        ports {
          #address-cells = <1>;
          #size-cells = <0>;

          port@0 {
            reg = <0>;
            usb_con_hs: endpoint {
              remote-endpoint = <&max77865_usbc_hs>;
            };
          };
          port@1 {
            reg = <1>;
            usb_con_ss: endpoint {
              remote-endpoint = <&usbdrd_phy_ss>;
            };
          };
          port@2 {
            reg = <2>;
            usb_con_sbu: endpoint {
              remote-endpoint = <&dp_aux>;
            };
          };
        };
      };
    };

  # USB-C connector attached to a typec port controller(ptn5110), which has
  # power delivery support and enables drp.
  - |+
    #include <dt-bindings/usb/pd.h>
    typec: ptn5110 {
      usb_con3: connector {
        compatible = "usb-c-connector";
        label = "USB-C";
        power-role = "dual";
        try-power-role = "sink";
        source-pdos = <PDO_FIXED(5000, 2000, PDO_FIXED_USB_COMM)>;
        sink-pdos = <PDO_FIXED(5000, 2000, PDO_FIXED_USB_COMM)
                     PDO_VAR(5000, 12000, 2000)>;
        op-sink-microwatt = <10000000>;
      };
    };