Re: [PATCH 1/2] dt-bindings: usb: Add documentation for AM62 USB Wrapper module

[Krzysztof Kozlowski]

On 23/03/2022 06:35, Aswath Govindraju wrote:
> Add bindings for the TI's AM62 wrapper module for the Synopsys USBSS-DRD
> controller.
> 
> Signed-off-by: Aswath Govindraju <a-govindraju@xxxxxx>
> ---
>  .../devicetree/bindings/usb/ti,am62-usb.yaml  | 98 +++++++++++++++++++
>  1 file changed, 98 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/usb/ti,am62-usb.yaml
> 
> diff --git a/Documentation/devicetree/bindings/usb/ti,am62-usb.yaml b/Documentation/devicetree/bindings/usb/ti,am62-usb.yaml
> new file mode 100644
> index 000000000000..4bb139d1926d
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/usb/ti,am62-usb.yaml
> @@ -0,0 +1,98 @@
> +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/usb/ti,am62-usb.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Bindings for the TI's AM62 wrapper module for the Synopsys USBSS-DRD controller

Skip the "Bindings for the", just leave the HW description.

> +
> +maintainers:
> +  - Aswath Govindraju <a-govindraju@xxxxxx>
> +
> +properties:
> +  compatible:
> +    const: ti,am62-usb
> +
> +  reg:
> +    maxItems: 1
> +
> +  ranges: true
> +
> +  power-domains:
> +    description:
> +      PM domain provider node and an args specifier containing
> +      the USB ISO device id value. See,
> +      Documentation/devicetree/bindings/soc/ti/sci-pm-domain.yaml
> +    maxItems: 1
> +
> +  clocks:
> +    description: Clock phandles to usb2_refclk
> +    maxItems: 1
> +
> +  clock-names:
> +    items:
> +      - const: ref
> +
> +  id-gpio:
> +    description:
> +      GPIO to be used as ID pin
> +    maxItems: 1
> +
> +  interrupts:
> +    description:
> +      interrupt line to be used for detecting changes in VBUS
> +
> +  ti,vbus-divider:
> +    description:
> +      Should be present if USB VBUS line is connected to the
> +      VBUS pin of the SoC via a 1/3 voltage divider.
> +    type: boolean
> +
> +  ti,syscon-phy-pll-refclk:
> +    $ref: /schemas/types.yaml#/definitions/phandle-array
> +    items:
> +      - items:
> +          - description: Phandle to the SYSCON entry
> +          - description: USB phy control register offset within SYSCON
> +    description: Specifier for configuring frequency of ref clock input.

This is a bit strange. The ref clock is the "ref" input clock, right? In
such case use clk_set_rate()... Using syscon for managing clocks is not
the proper way.

Plus all the issues pointed out by Roger.

> +
> +  '#address-cells':
> +    const: 2
> +
> +  '#size-cells':
> +    const: 2

No children allowed?

I understand this is a wrapper, which explains why you do not include
usb-hcd.yaml schema. But since it is a wrapper, what is it wrapping?

> +
> +required:
> +  - compatible
> +  - reg
> +  - power-domains
> +  - clocks
> +  - clock-names
> +  - interrupts
> +  - ti,syscon-phy-pll-refclk
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/soc/ti,sci_pm_domain.h>
> +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> +    #include <dt-bindings/gpio/gpio.h>
> +
> +    bus {
> +      #address-cells = <2>;
> +      #size-cells = <2>;
> +
> +      dwc3-usb@f910000 {

Generic node name, so usb.

> +        compatible = "ti,am62-usb";


Best regards,
Krzysztof