# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
# Copyright (c) 2020 MediaTek
%YAML 1.2
---
$id: http://devicetree.org/schemas/phy/mediatek,tphy.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: MediaTek T-PHY Controller

maintainers:
  - Chunfeng Yun <chunfeng.yun@mediatek.com>

description: |
  The T-PHY controller supports physical layer functionality for a number of
  controllers on MediaTek SoCs, includes USB2.0, USB3.0, PCIe and SATA.
 
  Layout differences of banks between T-PHY V1 (mt8173/mt2701) and
  T-PHY V2 (mt2712) / V3 (mt8195) when works on USB mode:
  -----------------------------------
  Version 1:
  port        offset    bank
  shared      0x0000    SPLLC
              0x0100    FMREG
  u2 port0    0x0800    U2PHY_COM
  u3 port0    0x0900    U3PHYD
              0x0a00    U3PHYD_BANK2
              0x0b00    U3PHYA
              0x0c00    U3PHYA_DA
  u2 port1    0x1000    U2PHY_COM
  u3 port1    0x1100    U3PHYD
              0x1200    U3PHYD_BANK2
              0x1300    U3PHYA
              0x1400    U3PHYA_DA
  u2 port2    0x1800    U2PHY_COM
              ...
 
  Version 2/3:
  port        offset    bank
  u2 port0    0x0000    MISC
              0x0100    FMREG
              0x0300    U2PHY_COM
  u3 port0    0x0700    SPLLC
              0x0800    CHIP
              0x0900    U3PHYD
              0x0a00    U3PHYD_BANK2
              0x0b00    U3PHYA
              0x0c00    U3PHYA_DA
  u2 port1    0x1000    MISC
              0x1100    FMREG
              0x1300    U2PHY_COM
  u3 port1    0x1700    SPLLC
              0x1800    CHIP
              0x1900    U3PHYD
              0x1a00    U3PHYD_BANK2
              0x1b00    U3PHYA
              0x1c00    U3PHYA_DA
  u2 port2    0x2000    MISC
              ...
 
  SPLLC shared by u3 ports and FMREG shared by u2 ports on V1 are put back
  into each port; a new bank MISC for u2 ports and CHIP for u3 ports are
  added on V2; the FMREG bank for slew rate calibration is not used anymore
  and reserved on V3;

properties:
  $nodename:
    pattern: "^t-phy(@[0-9a-f]+)?$"

  compatible:
    oneOf:
      - items:
          - enum:
              - mediatek,mt2701-tphy
              - mediatek,mt7623-tphy
              - mediatek,mt7622-tphy
              - mediatek,mt8516-tphy
          - const: mediatek,generic-tphy-v1
      - items:
          - enum:
              - mediatek,mt2712-tphy
              - mediatek,mt7629-tphy
              - mediatek,mt7986-tphy
              - mediatek,mt8183-tphy
              - mediatek,mt8186-tphy
              - mediatek,mt8192-tphy
              - mediatek,mt8365-tphy
          - const: mediatek,generic-tphy-v2
      - items:
          - enum:
              - mediatek,mt8188-tphy
              - mediatek,mt8195-tphy
          - const: mediatek,generic-tphy-v3
      - const: mediatek,mt2701-u3phy
        deprecated: true
      - const: mediatek,mt2712-u3phy
        deprecated: true
      - const: mediatek,mt8173-u3phy

  reg:
    description:
      Register shared by multiple ports, exclude port's private register.
      It is needed for T-PHY V1, such as mt2701 and mt8173, but not for
      T-PHY V2/V3, such as mt2712.
    maxItems: 1
 
  "#address-cells":
    enum: [1, 2]
 
  "#size-cells":
    enum: [1, 2]
 
  # Used with non-empty value if optional 'reg' is not provided.
  # The format of the value is an arbitrary number of triplets of
  # (child-bus-address, parent-bus-address, length).
  ranges: true

  mediatek,src-ref-clk-mhz:
    description:
      Frequency of reference clock for slew rate calibrate
    default: 26

  mediatek,src-coef:
    description:
      Coefficient for slew rate calibrate, depends on SoC process
    $ref: /schemas/types.yaml#/definitions/uint32
    default: 28
 
# Required child node:
patternProperties:
  "^(usb|pcie|sata)-phy@[0-9a-f]+$":
    type: object
    description:
      A sub-node is required for each port the controller provides.
      Address range information including the usual 'reg' property
      is used inside these nodes to describe the controller's topology.

    properties:
      reg:
        maxItems: 1

      clocks:
        minItems: 1
        items:
          - description: Reference clock, (HS is 48Mhz, SS/P is 24~27Mhz)
          - description: Reference clock of analog phy
        description:
          Uses both clocks if the clock of analog and digital phys are
          separated, otherwise uses "ref" clock only if needed.

      clock-names:
        minItems: 1
        items:
          - const: ref
          - const: da_ref
 
      "#phy-cells":
        const: 1
        description: |
          The cells contain the following arguments.
 
          - description: The PHY type
              enum:
                - PHY_TYPE_USB2
                - PHY_TYPE_USB3
                - PHY_TYPE_PCIE
                - PHY_TYPE_SATA
                - PHY_TYPE_SGMII

      nvmem-cells:
        items:
          - description: internal R efuse for U2 PHY or U3/PCIe PHY
          - description: rx_imp_sel efuse for U3/PCIe PHY
          - description: tx_imp_sel efuse for U3/PCIe PHY
        description: |
          Phandles to nvmem cell that contains the efuse data;
          Available only for U2 PHY or U3/PCIe PHY of version 2/3, these
          three items should be provided at the same time for U3/PCIe PHY,
          when use software to load efuse;
          If unspecified, will use hardware auto-load efuse.

      nvmem-cell-names:
        items:
          - const: intr
          - const: rx_imp
          - const: tx_imp
 
      # The following optional vendor properties are only for debug or HQA test
      mediatek,eye-src:
        description:
          The value of slew rate calibrate (U2 phy)
        $ref: /schemas/types.yaml#/definitions/uint32
        minimum: 1
        maximum: 7

      mediatek,eye-vrt:
        description:
          The selection of VRT reference voltage (U2 phy)
        $ref: /schemas/types.yaml#/definitions/uint32
        minimum: 1
        maximum: 7

      mediatek,eye-term:
        description:
          The selection of HS_TX TERM reference voltage (U2 phy)
        $ref: /schemas/types.yaml#/definitions/uint32
        minimum: 1
        maximum: 7

      mediatek,intr:
        description:
          The selection of internal resistor (U2 phy)
        $ref: /schemas/types.yaml#/definitions/uint32
        minimum: 1
        maximum: 31

      mediatek,discth:
        description:
          The selection of disconnect threshold (U2 phy)
        $ref: /schemas/types.yaml#/definitions/uint32
        minimum: 1
        maximum: 15

      mediatek,pre-emphasis:
        description:
          The level of pre-emphasis which used to widen the eye opening and
          boost eye swing, the unit step is about 4.16% increment; e.g. the
          level 1 means amplitude increases about 4.16%, the level 2 is about
          8.3% etc. (U2 phy)
        $ref: /schemas/types.yaml#/definitions/uint32
        minimum: 1
        maximum: 3

      mediatek,bc12:
        description:
          Specify the flag to enable BC1.2 if support it
        type: boolean

      mediatek,force-mode:
        description:
          The force mode is used to manually switch the shared phy mode between
          USB3 and PCIe, when USB3 phy type is selected by the consumer, and
          force-mode is set, will cause phy's power and pipe toggled and force
          phy as USB3 mode which switched from default PCIe mode. But perfer to
          use the property "mediatek,syscon-type" for newer SoCs that support it.
        type: boolean

      mediatek,syscon-type:
        $ref: /schemas/types.yaml#/definitions/phandle-array
        maxItems: 1
        description:
          A phandle to syscon used to access the register of type switch,
          the field should always be 3 cells long.
        items:
          items:
            - description:
                The first cell represents a phandle to syscon
            - description:
                The second cell represents the register offset
            - description:
                The third cell represents the index of config segment
              enum: [0, 1, 2, 3]

    required:
      - reg
      - "#phy-cells"

    additionalProperties: false

required:
  - compatible
  - "#address-cells"
  - "#size-cells"
  - ranges

additionalProperties: false

examples:
  - |
    #include <dt-bindings/clock/mt8173-clk.h>
    #include <dt-bindings/interrupt-controller/arm-gic.h>
    #include <dt-bindings/interrupt-controller/irq.h>
    #include <dt-bindings/phy/phy.h>
    usb@11271000 {
        compatible = "mediatek,mt8173-mtu3", "mediatek,mtu3";
        reg = <0x11271000 0x3000>, <0x11280700 0x0100>;
        reg-names = "mac", "ippc";
        phys = <&u2port0 PHY_TYPE_USB2>,
               <&u3port0 PHY_TYPE_USB3>,
               <&u2port1 PHY_TYPE_USB2>;
        interrupts = <GIC_SPI 115 IRQ_TYPE_LEVEL_LOW>;
        clocks = <&topckgen CLK_TOP_USB30_SEL>;
        clock-names = "sys_ck";
    };
 
    t-phy@11290000 {
        compatible = "mediatek,mt8173-u3phy";
        reg = <0x11290000 0x800>;
        #address-cells = <1>;
        #size-cells = <1>;
        ranges;
 
        u2port0: usb-phy@11290800 {
            reg = <0x11290800 0x100>;
            clocks = <&apmixedsys CLK_APMIXED_REF2USB_TX>, <&clk48m>;
            clock-names = "ref", "da_ref";
            #phy-cells = <1>;
        };
 
        u3port0: usb-phy@11290900 {
            reg = <0x11290900 0x700>;
            clocks = <&clk26m>;
            clock-names = "ref";
            #phy-cells = <1>;
        };
 
        u2port1: usb-phy@11291000 {
            reg = <0x11291000 0x100>;
            #phy-cells = <1>;
        };
    };

...