[v4,2/2] dt-bindings: usb: dwc3: Add Realtek DHC RTD SoC DWC3 USB

Document the DWC3 USB bindings for Realtek SoCs.

Signed-off-by: Stanley Chang <stanley_chang@realtek.com>
---
v3 to v4 change:
    Add reg for register set for pm control.
    Remove maximum-speed in example.
v2 to v3 change:
    Add description for reg
    Remove property for realtek,unlink-usb3-port.
    Remove property for realtek,disable-usb3-phy.
    Use the maximum-speed instead of the above two properties.
v1 to v2 change:
    Revise the subject.
    Rename the file.
    Fix dtschema warnings.
    Remove the property realtek,enable-l4icg.
    Drop status.
---
 .../bindings/usb/realtek,rtd-dwc3.yaml        | 80 +++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/usb/realtek,rtd-dwc3.yaml

On Tue, Aug 15, 2023 at 05:54:38PM +0800, Stanley Chang wrote:
> Document the DWC3 USB bindings for Realtek SoCs.
> 
> Signed-off-by: Stanley Chang <stanley_chang@realtek.com>
> ---
> v3 to v4 change:
>     Add reg for register set for pm control.
>     Remove maximum-speed in example.
> v2 to v3 change:
>     Add description for reg
>     Remove property for realtek,unlink-usb3-port.
>     Remove property for realtek,disable-usb3-phy.
>     Use the maximum-speed instead of the above two properties.
> v1 to v2 change:
>     Revise the subject.
>     Rename the file.
>     Fix dtschema warnings.
>     Remove the property realtek,enable-l4icg.
>     Drop status.
> ---
>  .../bindings/usb/realtek,rtd-dwc3.yaml        | 80 +++++++++++++++++++
>  1 file changed, 80 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/usb/realtek,rtd-dwc3.yaml
> 
> diff --git a/Documentation/devicetree/bindings/usb/realtek,rtd-dwc3.yaml b/Documentation/devicetree/bindings/usb/realtek,rtd-dwc3.yaml
> new file mode 100644
> index 000000000000..345d0132d4a5
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/usb/realtek,rtd-dwc3.yaml
> @@ -0,0 +1,80 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +# Copyright 2023 Realtek Semiconductor Corporation
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/usb/realtek,rtd-dwc3.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Realtek DWC3 USB SoC Controller Glue
> +
> +maintainers:
> +  - Stanley Chang <stanley_chang@realtek.com>
> +
> +description:
> +  The Realtek DHC SoC embeds a DWC3 USB IP Core configured for USB 2.0
> +  and USB 3.0 in host or dual-role mode.
> +
> +properties:
> +  compatible:
> +    items:
> +      - enum:
> +          - realtek,rtd1295-dwc3
> +          - realtek,rtd1315e-dwc3
> +          - realtek,rtd1319-dwc3
> +          - realtek,rtd1319d-dwc3
> +          - realtek,rtd1395-dwc3
> +          - realtek,rtd1619-dwc3
> +          - realtek,rtd1619b-dwc3
> +      - const: realtek,rtd-dwc3
> +
> +  reg:
> +    items:
> +      - description: Address and length of register set for wrapper of dwc3 core.
> +      - description: Address and length of register set for pm control.
> +
> +  '#address-cells':
> +    const: 1
> +
> +  '#size-cells':
> +    const: 1
> +
> +  ranges: true
> +
> +patternProperties:
> +  "^usb@[0-9a-f]+$":
> +    $ref: snps,dwc3.yaml#
> +    description: Required child node
> +
> +required:
> +  - compatible
> +  - reg
> +  - "#address-cells"
> +  - "#size-cells"
> +  - ranges
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    usb@98013e00 {
> +        compatible = "realtek,rtd1319d-dwc3", "realtek,rtd-dwc3";
> +        reg = <0x98013e00 0x140>, <0x98013f60 0x4>;

These look like registers in some other block rather than a standalone 
wrapper block. Are these part of some syscon block? If so, I don't think 
a wrapper node is the right approach here, but a phandle to the syscon 
would be instead.

Hi Rob,

> > +examples:
> > +  - |
> > +    usb@98013e00 {
> > +        compatible = "realtek,rtd1319d-dwc3", "realtek,rtd-dwc3";
> > +        reg = <0x98013e00 0x140>, <0x98013f60 0x4>;
> 
> These look like registers in some other block rather than a standalone wrapper
> block. Are these part of some syscon block? If so, I don't think a wrapper node
> is the right approach here, but a phandle to the syscon would be instead.
> 
They are the same block of registers.
We have three dwc3 controllers in one SoC. The register wrapper is located at
USB1. 0x98013200 to 0x980133ff
USB2. 0x98013c00 to 0x98013dff
USB3. 0x98013e00 to 0x98013fff

Why are they split into two blocks?
Since USB_DBUS_PWR_CTRL_REG has a different offset at usb1 (0x164) than other USBs (0x160).
We split two blocks one 0x98013200 to 0x9801333f and one 0x98013364 to 0x98013367, to solve this question.

> From the register definitions, much of it looks phy related, but this is not part
> of the phys?

In our hardware design, these phy settings are location the register of wrapper.

Thanks,
Stanley

> 
> > +        #address-cells = <1>;
> > +        #size-cells = <1>;
> > +        ranges;
> > +
> > +        usb@98050000 {
> > +            compatible = "snps,dwc3";
> > +            reg = <0x98050000 0x9000>;
> > +            interrupts = <0 94 4>;
> > +            phys = <&usb2phy &usb3phy>;
> > +            phy-names = "usb2-phy", "usb3-phy";
> > +            dr_mode = "otg";
> > +            usb-role-switch;
> > +            role-switch-default-mode = "host";
> > +            snps,dis_u2_susphy_quirk;
> > +            snps,parkmode-disable-ss-quirk;
> > +            snps,parkmode-disable-hs-quirk;
> > +            maximum-speed = "high-speed";
> > +        };
> > +    };
> > --