Re: [PATCH 1/4] dt-bindings: usb: chipidea: Convert to json-schema

[Rob Herring <robh@kernel.org>]

On Thu, Dec 09, 2021 at 05:53:36PM +0100, Thierry Reding wrote:
> From: Thierry Reding <treding@nvidia.com>
> 
> Convert the ChipIdea USB2 bindings from the free-form text format to
> json-schema.
> 
> Signed-off-by: Thierry Reding <treding@nvidia.com>
> ---
>  .../bindings/usb/chipidea,usb2.yaml           | 310 ++++++++++++++++++
>  .../devicetree/bindings/usb/ci-hdrc-usb2.txt  | 158 ---------
>  2 files changed, 310 insertions(+), 158 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/usb/chipidea,usb2.yaml
>  delete mode 100644 Documentation/devicetree/bindings/usb/ci-hdrc-usb2.txt
> 
> diff --git a/Documentation/devicetree/bindings/usb/chipidea,usb2.yaml b/Documentation/devicetree/bindings/usb/chipidea,usb2.yaml
> new file mode 100644
> index 000000000000..0e36259f23ba
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/usb/chipidea,usb2.yaml
> @@ -0,0 +1,310 @@
> +# SPDX-License-Identifier: GPL-2.0-only
> +%YAML 1.2
> +---
> +$id: "http://devicetree.org/schemas/usb/chipidea,usb2.yaml#"
> +$schema: "http://devicetree.org/meta-schemas/core.yaml#"
> +
> +title: USB2 ChipIdea USB controller for ci13xxx
> +
> +maintainers:
> +  - Peter Chen <peter.chen@freescale.com>

This should have a reference to usb-drd.yaml I think.

> +
> +properties:
> +  compatible:
> +    oneOf:
> +      - enum:
> +          - fsl,imx23-usb
> +          - fsl,imx27-usb
> +          - fsl,imx28-usb
> +          - fsl,imx6q-usb
> +          - fsl,imx6sl-usb
> +          - fsl,imx6sx-usb
> +          - fsl,imx6ul-usb
> +          - fsl,imx7d-usb
> +          - fsl,imx7ulp-usb
> +          - lsi,zevio-usb
> +          - qcom,ci-hdrc
> +          - chipidea,usb2
> +          - xlnx,zynq-usb-2.20a
> +          - nvidia,tegra20-udc
> +          - nvidia,tegra30-udc
> +          - nvidia,tegra114-udc
> +          - nvidia,tegra124-udc
> +      - items:
> +          - const: fsl,imx6q-usb
> +          - const: fsl,imx27-usb
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  phy_type:
> +    $ref: /schemas/types.yaml#/definitions/string
> +    description: The type of the PHY connected to the core. Without this property the PORTSC
> +      register won't be touched.
> +    enum:
> +      - utmi
> +      - utmi_wide
> +      - ulpi
> +      - serial
> +      - hsic
> +
> +  dr_mode:
> +    $ref: /schemas/types.yaml#/definitions/string
> +    description: dual-role mode of the interface
> +    enum:
> +      - host
> +      - peripheral
> +      - otg
> +    default:
> +      const: otg
> +
> +  clocks:
> +    items:
> +      - description: reference to the USB clock

From the report, i.MX needs 3 clocks.

> +
> +  resets:
> +    items:
> +      - description: reference to the USB reset
> +
> +  reset-names:
> +    items:
> +      - const: usb
> +
> +  phys:
> +    items:
> +      - description: reference to the USB PHY
> +
> +  phy-names:
> +    items:
> +      - const: usb-phy
> +
> +  vbus-supply:
> +    description: reference to the VBUS regulator
> +
> +  maximum-speed:
> +    description: limit the maximum connection speed to "full-speed".
> +
> +  tpl-support:
> +    description: TPL (Targeted Peripheral List) feature for targeted hosts
> +
> +  itc-setting:
> +    description: Interrupt threshold control register control, the setting should be aligned with
> +      ITC bits at register USBCMD.
> +
> +  ahb-burst-config:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: This vendor-dependent property is used to change the AHB burst configuration and
> +      should be aligned with AHBBRST at SBUSCFG. See the ChipIdea specification for the details on
> +      each of those values. If this property does not exist, the reset value will be used.
> +    minimum: 0
> +    maximum: 7
> +
> +  tx-burst-size-dword:
> +    description: This vendor-dependent property is used to configure the TX burst size (in 32-bit
> +      words). The value represents the maximum length of a burst while moving data from system
> +      memory to the USB bus. This property takes effect only if the "ahb-burst-config" property is
> +      set to 0. If this property is missing the reset default of the hardware implementation will
> +      be used.
> +
> +  rx-burst-size-dword:
> +    description: This vendor-dependent property is used to configure the RX burst size (in 32-bit
> +      words). This value represents the maximum length of a burst while moving data from the USB
> +      bus to system memory. This property takes effect only if the "ahb-burst-config" property is
> +      set to 0. If this property is missing the reset default of the hardware implementation will
> +      be used.
> +
> +  extcon:
> +    description: A list of phandles to external connector devices. The first phandle should point
> +      to the external connector which provides "USB" cable events. The second should point to the
> +      external connector device that provide "USB-HOST" cable events. If one of the external
> +      connector devices is not required, an empty phandle (0) should be specified.
> +
> +  phy-clkgate-delay-us:
> +    description: The delay time (in microseconds) between putting the PHY into low power mode and
> +      gating the PHY clock.
> +
> +  non-zero-ttctrl-ttha:
> +    description: |
> +      After setting this property, the value of register ttctrl.ttha will be 0x7f; if not, the
> +      value will be 0x0 (the default). The value for this property needs to be chosen very
> +      carefully after consulting with your IC engineer.
> +
> +      On most ChipIdea platforms, the "usage_tt" flag at RTL is 0, so this property only affects
> +      siTD.
> +
> +      If this property is not set, the maximum packet size is 1023 bytes, and if the total packet
> +      size for previous transactions is more than 256 bytes, no further transactions can be
> +      accepted within the frame. The use case is single transaction, but higher frame rate.
> +
> +      If this property is set, the maximum packet size is limited to 188 bytes and more
> +      transactions than in the above case can be handled. Transactions will be accepted as long as
> +      188 bytes or more of space are left within a frame. Software needs to make sure it does not
> +      send more than 90% maximum_periodic_data_per_frame. The use case is higher amount of
> +      transactions at the cost of a lower frame rate.
> +
> +  mux-controls:
> +    description: The mux control for toggling host/device output of this controller. It's expected
> +      that a mux state of 0 indicates device mode and a mux state of 1 indicates host mode.
> +
> +  mux-control-names:
> +    const: usb_switch
> +
> +  pinctrl-names:
> +    description: In case of HSIC-mode, "idle" and "active" pin modes are mandatory. In this case,
> +      the "idle" state needs to pull down the data and strobe pin and the "active" state needs to
> +      pull up the strobe pin.
> +    minItems: 1
> +    maxItems: 5
> +    items:
> +      enum:
> +        - default
> +        - host
> +        - device
> +        - idle # mandatory for HSIC
> +        - active # mandatory for HSIC
> +
> +  # i.MX specific properties
> +  fsl,usbmisc:
> +    $ref: /schemas/types.yaml#/definitions/phandle-array
> +    description: phandle to non-core register device, with one argument that indicate USB
> +      controller index.
> +
> +  disable-over-current:
> +    $ref: /schemas/types.yaml#/definitions/flag
> +    description: disable over current detect
> +
> +  over-current-active-low:
> +    $ref: /schemas/types.yaml#/definitions/flag
> +    description: Over-current signal polarity is active low. It's recommended to specify the
> +      over-current polarity.
> +
> +  over-current-active-high:
> +    $ref: /schemas/types.yaml#/definitions/flag
> +    description: Over-current signal polarity is active high. It's recommended to specify the
> +      over-current polarity.
> +
> +  power-active-high:
> +    $ref: /schemas/types.yaml#/definitions/flag
> +    description: power signal polarity is active high
> +
> +  external-vbus-divider:
> +    $ref: /schemas/types.yaml#/definitions/flag
> +    description: enables off-chip resistor divider for Vbus
> +
> +  samsung,picophy-pre-emp-curr-control:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: HS Transmitter Pre-Emphasis Current Control. This signal controls the amount of
> +      current sourced to the USB_OTG*_DP and USB_OTG*_DN pins after a J-to-K or K-to-J transition.
> +      Refer to the TXPREEMPAMPTUNE0 bits of register USBNC_n_PHY_CFG1 in the documentation for
> +      more details.
> +    minimum: 0
> +    maximum: 3
> +    default: 1
> +
> +  samsung,picophy-dc-vol-level-adjust:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: HS DC Voltage Level Adjustment. Adjust the high-speed transmitter DC level
> +      voltage. Refer to the TXVREFTUNE0 bits of register USBNC_n_PHY_CFG1 in the documentation for
> +      more details.
> +    minimum: 0
> +    maximum: 0xf
> +    default: 3
> +
> +  # NVIDIA Tegra specific properties
> +  nvidia,needs-double-reset:
> +    $ref: /schemas/types.yaml#/definitions/flag
> +    description: Specifies a workaround for the USB1 port that needs to be reset twice internally
> +      some Tegra devices.
> +
> +  # deprecated properties
> +  usb-phy:
> +    $ref: /schemas/types.yaml#/definitions/phandle
> +    description: phandle for the PHY device. Use "phys" instead.
> +    deprecated: true
> +
> +  fsl,usbphy:
> +    $ref: /schemas/types.yaml#/definitions/phandle
> +    description: phandle of usb phy that connects to the port. Use "phys" instead.
> +    deprecated: true
> +
> +  nvidia,phy:
> +    $ref: /schemas/types.yaml#/definitions/phandle
> +    description: phandle for the PHY device. Use "phys" instead.
> +    deprecated: true
> +

> +  # USB bus
> +  "#address-cells":
> +    const: 1
> +
> +  "#size-cells":
> +    const: 0

Covered by common schema (I think).

> +
> +patternProperties:
> +  "^pinctrl-[0-9]+$": true
> +
> +additionalProperties:
> +  $ref: usb-device.yaml

This is wrong as usb.device.yaml applies to child nodes.

> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +
> +dependencies:
> +  mux-control-names: [ mux-controls ]
> +
> +examples:
> +  - |
> +    #include <dt-bindings/clock/berlin2.h>
> +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> +
> +    usb@f7ed0000 {
> +      compatible = "chipidea,usb2";
> +      reg = <0xf7ed0000 0x10000>;
> +      interrupts = <GIC_SPI 11 IRQ_TYPE_LEVEL_HIGH>;
> +      clocks = <&chip CLKID_USB0>;
> +      phys = <&usb_phy0>;
> +      phy-names = "usb-phy";
> +      vbus-supply = <&reg_usb0_vbus>;
> +      itc-setting = <0x4>; /* 4 micro-frames */
> +      /* Incremental burst of unspecified length */
> +      ahb-burst-config = <0x0>;
> +      tx-burst-size-dword = <0x10>; /* 64 bytes */
> +      rx-burst-size-dword = <0x10>;
> +      extcon = <0>, <&usb_id>;
> +      phy-clkgate-delay-us = <400>;
> +      mux-controls = <&usb_switch>;
> +      mux-control-names = "usb_switch";
> +    };
> +
> +  # HSIC
> +  - |
> +    #include <dt-bindings/clock/imx6qdl-clock.h>
> +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> +
> +    usb@2184400 {
> +      compatible = "fsl,imx6q-usb", "fsl,imx27-usb";
> +      reg = <0x02184400 0x200>;
> +      interrupts = <GIC_SPI 41 IRQ_TYPE_LEVEL_HIGH>;
> +      clocks = <&clks IMX6QDL_CLK_USBOH3>;
> +      fsl,usbphy = <&usbphynop1>;
> +      fsl,usbmisc = <&usbmisc 2>;
> +      phy_type = "hsic";
> +      dr_mode = "host";
> +      ahb-burst-config = <0x0>;
> +      tx-burst-size-dword = <0x10>;
> +      rx-burst-size-dword = <0x10>;
> +      pinctrl-names = "idle", "active";
> +      pinctrl-0 = <&pinctrl_usbh2_idle>;
> +      pinctrl-1 = <&pinctrl_usbh2_active>;
> +      #address-cells = <1>;
> +      #size-cells = <0>;
> +
> +      usbnet: smsc@1 {
> +        compatible = "usb424,9730";
> +        reg = <1>;
> +      };
> +    };