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

Rob Herring
2023-01-17T19:57:50Z

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 ]