linux-kernel - Re: [PATCH v1 2/2] doc: dt: bindings: usb: realtek,dwc3: Add Realtek DHC RTD SoC DWC3 USB

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <4bbdd646-ad16-1a7d-a727-878c6cf92410@linaro.org>
Date:   Fri, 28 Jul 2023 09:04:13 +0200
From:   Krzysztof Kozlowski <krzysztof.kozlowski@...aro.org>
To:     Stanley Chang <stanley_chang@...ltek.com>,
        Thinh Nguyen <Thinh.Nguyen@...opsys.com>
Cc:     Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Rob Herring <robh+dt@...nel.org>,
        Krzysztof Kozlowski <krzysztof.kozlowski+dt@...aro.org>,
        Conor Dooley <conor+dt@...nel.org>, linux-usb@...r.kernel.org,
        devicetree@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH v1 2/2] doc: dt: bindings: usb: realtek,dwc3: Add Realtek
 DHC RTD SoC DWC3 USB

On 28/07/2023 05:53, Stanley Chang wrote:
> Document the DWC3 USB bindings for Realtek SoCs.

Please use subject prefixes matching the subsystem. You can get them for
example with `git log --oneline -- DIRECTORY_OR_FILE` on the directory
your patch is touching.

My filtering of emails depends on it.

> 
> Signed-off-by: Stanley Chang <stanley_chang@...ltek.com>
> ---
>  .../devicetree/bindings/usb/realtek,dwc3.yaml | 107 ++++++++++++++++++
>  1 file changed, 107 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/usb/realtek,dwc3.yaml
> 
> diff --git a/Documentation/devicetree/bindings/usb/realtek,dwc3.yaml b/Documentation/devicetree/bindings/usb/realtek,dwc3.yaml

realtek,rtd-dwc3.yaml

> new file mode 100644
> index 000000000000..74d388809924
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/usb/realtek,dwc3.yaml
> @@ -0,0 +1,107 @@
> +# 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,dwc3.yaml#"
> +$schema: "http://devicetree.org/meta-schemas/core.yaml#"

Drop quotes. Wasn't tested, because dtschema reports warnings here...

> +
> +title: Realtek DWC3 USB SoC Controller Glue
> +
> +maintainers:
> +  - Stanley Chang <stanley_chang@...ltek.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:
> +    maxItems: 1
> +
> +  '#address-cells':
> +    const: 1
> +
> +  '#size-cells':
> +    const: 1
> +
> +  ranges: true
> +
> +  realtek,unlink-usb3-port:
> +    description: Disable link between USB 3.0 PHY and USB mac.
> +      Only for RTD1619 SoC, if the board design support maximum 2.0 speed.
> +    type: boolean
> +
> +  realtek,disable-usb3-phy:
> +    description: Close USB 3.0 PHY if the board design not support USB 3.0.
> +    type: boolean
> +
> +  realtek,enable-l4icg:
> +    description: Enable the power saving feature l4icg by hardware clock.
> +      gating.

You described the desired Linux feature or behavior, not the actual
hardware. The bindings are about the latter, so instead you need to
rephrase the property and its description to match actual hardware
capabilities/features/configuration etc.

> +    type: boolean
> +
> +patternProperties:
> +  "^usb@[0-9a-f]+$":
> +    $ref: snps,dwc3.yaml#
> +    description: Required child node
> +
> +required:
> +  - compatible
> +  - reg
> +  - "#address-cells"
> +  - "#size-cells"
> +  - ranges
> +
> +allOf:
> +  - if:
> +      not:
> +        properties:
> +          compatible:
> +            contains:
> +              enum:
> +                - realtek,rtd1619-dwc3
> +    then:
> +      properties:
> +        realtek,unlink-usb3-port: false
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    usb@...13e00 {
> +        compatible = "realtek,rtd1319d-dwc3", "realtek,rtd-dwc3";
> +        reg = <0x98013e00 0x200>;
> +        #address-cells = <1>;
> +        #size-cells = <1>;
> +        ranges;
> +        status = "okay";

Drop status.

> +        realtek,disable-usb3-phy;
> +        realtek,enable-l4icg;
> +
> +        usb@...50000 {
> +            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";
> +        };
> +    };

Best regards,
Krzysztof