Re: [PATCH v3] dt-bindings: phy: tegra-xusb: Convert to json-schema

[Rob Herring <robh@kernel.org>]

On Fri, Jan 13, 2023 at 04:08:04PM +0100, Thierry Reding wrote:
> From: Thierry Reding <treding@nvidia.com>
> 
> Convert the Tegra XUSB pad controller bindings from free-form text
> format to json-schema.
> 
> Signed-off-by: Thierry Reding <treding@nvidia.com>
> ---
> Changes in v3:
> - use | to keep paragraphs in multi-paragraph descriptions
> - move additionalProperties to improve readability
> - clarify that "status" can also be absent
> - drop phandle and status properties
> - remove quotes around references
> - use dual licensing
> 
> Changes in v2:
> - split up into multiple schemas
> 
>  .../phy/nvidia,tegra124-xusb-padctl.txt       | 779 -----------------
>  .../phy/nvidia,tegra124-xusb-padctl.yaml      | 654 +++++++++++++++
>  .../phy/nvidia,tegra186-xusb-padctl.yaml      | 544 ++++++++++++
>  .../phy/nvidia,tegra194-xusb-padctl.yaml      | 630 ++++++++++++++
>  .../phy/nvidia,tegra210-xusb-padctl.yaml      | 786 ++++++++++++++++++
>  5 files changed, 2614 insertions(+), 779 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.txt
>  create mode 100644 Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.yaml
>  create mode 100644 Documentation/devicetree/bindings/phy/nvidia,tegra186-xusb-padctl.yaml
>  create mode 100644 Documentation/devicetree/bindings/phy/nvidia,tegra194-xusb-padctl.yaml
>  create mode 100644 Documentation/devicetree/bindings/phy/nvidia,tegra210-xusb-padctl.yaml
> 

> diff --git a/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.yaml b/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.yaml
> new file mode 100644
> index 000000000000..33b41b6b2fd5
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/phy/nvidia,tegra124-xusb-padctl.yaml
> @@ -0,0 +1,654 @@
> +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/phy/nvidia,tegra124-xusb-padctl.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: NVIDIA Tegra124 XUSB pad controller
> +
> +maintainers:
> +  - Thierry Reding <thierry.reding@gmail.com>
> +  - Jon Hunter <jonathanh@nvidia.com>
> +
> +description: |
> +  The Tegra XUSB pad controller manages a set of I/O lanes (with differential
> +  signals) which connect directly to pins/pads on the SoC package. Each lane
> +  is controlled by a HW block referred to as a "pad" in the Tegra hardware
> +  documentation. Each such "pad" may control either one or multiple lanes,
> +  and thus contains any logic common to all its lanes. Each lane can be
> +  separately configured and powered up.
> +
> +  Some of the lanes are high-speed lanes, which can be used for PCIe, SATA or
> +  super-speed USB. Other lanes are for various types of low-speed, full-speed
> +  or high-speed USB (such as UTMI, ULPI and HSIC). The XUSB pad controller
> +  contains a software-configurable mux that sits between the I/O controller
> +  ports (e.g. PCIe) and the lanes.
> +
> +  In addition to per-lane configuration, USB 3.0 ports may require additional
> +  settings on a per-board basis.
> +
> +  Pads will be represented as children of the top-level XUSB pad controller
> +  device tree node. Each lane exposed by the pad will be represented by its
> +  own subnode and can be referenced by users of the lane using the standard
> +  PHY bindings, as described by the phy-bindings.txt file in this directory.
> +
> +  The Tegra hardware documentation refers to the connection between the XUSB
> +  pad controller and the XUSB controller as "ports". This is confusing since
> +  "port" is typically used to denote the physical USB receptacle. The device
> +  tree binding in this document uses the term "port" to refer to the logical
> +  abstraction of the signals that are routed to a USB receptacle (i.e. a PHY
> +  for the USB signal, the VBUS power supply, the USB 2.0 companion port for
> +  USB 3.0 receptacles, ...).
> +
> +properties:
> +  compatible:
> +    oneOf:
> +      - enum:
> +          - nvidia,tegra124-xusb-padctl
> +
> +      - items:
> +          - const: nvidia,tegra132-xusb-padctl
> +          - const: nvidia,tegra124-xusb-padctl
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    items:
> +      - description: XUSB pad controller interrupt
> +
> +  resets:
> +    items:
> +      - description: pad controller reset
> +
> +  reset-names:
> +    items:
> +      - const: padctl
> +
> +  avdd-pll-utmip-supply:
> +    description: UTMI PLL power supply. Must supply 1.8 V.
> +
> +  avdd-pll-erefe-supply:
> +    description: PLLE reference PLL power supply. Must supply 1.05 V.
> +
> +  avdd-pex-pll-supply:
> +    description: PCIe/USB3 PLL power supply. Must supply 1.05 V.
> +
> +  hvdd-pex-pll-e-supply:
> +    description: High-voltage PLLE power supply. Must supply 3.3 V.
> +
> +  pads:
> +    description: A required child node named "pads" contains a list of
> +      subnodes, one for each of the pads exposed by the XUSB pad controller.
> +      Each pad may need additional resources that can be referenced in its
> +      pad node.
> +
> +      The "status" property is used to enable or disable the use of a pad.
> +      If set to "disabled", the pad will not be used on the given board. In
> +      order to use the pad and any of its lanes, this property must be set
> +      to "okay" or be absent.
> +    type: object
> +    additionalProperties: false
> +    properties:
> +      usb2:
> +        type: object
> +        additionalProperties: false
> +        properties:
> +          clocks:
> +            items:
> +              - description: USB2 tracking clock
> +
> +          clock-names:
> +            items:
> +              - const: trk
> +
> +          lanes:
> +            type: object
> +            additionalProperties: false
> +            properties:
> +              usb2-0:

Any reason to not make this a pattern? '^usb2-[0-2]$'

Same question in several other cases.

> +                type: object
> +                additionalProperties: false
> +                properties:
> +                  "#phy-cells":
> +                    const: 0
> +
> +                  nvidia,function:
> +                    description: Function selection for this lane.
> +                    $ref: /schemas/types.yaml#/definitions/string
> +                    enum: [ snps, xusb, uart ]
> +
> +              usb2-1:
> +                type: object
> +                additionalProperties: false
> +                properties:
> +                  "#phy-cells":
> +                    const: 0
> +
> +                  nvidia,function:
> +                    description: Function selection for this lane.
> +                    $ref: /schemas/types.yaml#/definitions/string
> +                    enum: [ snps, xusb, uart ]
> +
> +              usb2-2:
> +                type: object
> +                additionalProperties: false
> +                properties:
> +                  "#phy-cells":
> +                    const: 0
> +
> +                  nvidia,function:
> +                    description: Function selection for this lane.
> +                    $ref: /schemas/types.yaml#/definitions/string
> +                    enum: [ snps, xusb, uart ]