Re: [PATCH v2 1/2] dt-bindings: phy: Add documentation for Airoha AN7583 USB PHY

[Krzysztof Kozlowski]

On Tue, Aug 11, 2026 at 02:47:22PM +0200, Christian Marangi wrote:
> Add documentation for Airoha AN7583 USB PHY that describe the USB PHY
> for the USB controller.
> 
> Airoha AN7583 SoC support a maximum of 2 USB port. The USB 2.0 mode is
> always supported. The USB 3.0 mode is optional and depends on the Serdes
> mode currently configured on the system for the relevant USB port.
> 
> To correctly calibrate, the USB 2.0 port require correct value in
> "airoha,usb2-monitor-clk-sel" property. Both the 2 USB 2.0 port permit
> selecting one of the 4 monitor clock for calibration (internal clock not
> exposed to the system) but each port have only one of the 4 actually
> connected in HW hence the correct value needs to be specified in DT
> based on board and the physical port. Normally it's monitor clock 1 for
> USB1 and monitor clock 2 for USB2.
> 
> To correctly setup the Serdes mode attached to the USB 3.0 mode, a phys
> property is required with the phandle pointing to the correct Serdes port
> provided by the SCU node. Providing the phys property is optional if USB
> 3.0 is not used.
> 
> The second USB PHY on Airoha AN7583 SoC is used for PCIe Gen2 usage and
> similar to USB 3.0 require a phys property to configure the serdes.
> 
> Signed-off-by: Christian Marangi <ansuelsmth@xxxxxxxxx>
> ---
>  .../bindings/phy/airoha,an7583-usb-phy.yaml   | 205 ++++++++++++++----
>  1 file changed, 168 insertions(+), 37 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/phy/airoha,an7583-usb-phy.yaml b/Documentation/devicetree/bindings/phy/airoha,an7583-usb-phy.yaml
> index a6e2c0b1acc4..46b311040e02 100644
> --- a/Documentation/devicetree/bindings/phy/airoha,an7583-usb-phy.yaml
> +++ b/Documentation/devicetree/bindings/phy/airoha,an7583-usb-phy.yaml
> @@ -26,64 +26,195 @@ description: >
>  
>  properties:
>    compatible:
> -    const: airoha,an7583-usb-phy
> +    enum:
> +      - airoha,an7583-usb-phy
> +      - airoha,an7583-pcie-phy

Keep the list sorted.

>  
>    reg:
> -    items:
> -      - description: phy register
> -      - description: ana register
> -      - description: pma register
> -      - description: dig register
> +    minItems: 3
> +    maxItems: 4
>  
>    reg-names:
> -    itmes:
> -      const: phy
> -      const: ana
> -      const: pma
> -      const: dif
> +    minItems: 3
> +    maxItems: 4
>  
> -  usb2-phy:
> +  '#address-cells':
> +    const: 1
> +
> +  '#size-cells':
> +    const: 0

I don't understand this diff. Why do you add cells if you do not have
chidlren with addressing for new device (pcie)?

> +
> +  usb3-phy:
>      type: object
>  
>      properties:
> -      reg: [0, 0x1000]
> +      phys:
> +        items:
> +          - description: phandle to Serdes PHY
>  
> -    airoha,usb2-monitor-clk-sel:
> -      description: Describe what oscillator across the available 4
> -        should be selected for USB 2.0 Slew Rate calibration.
> -      $ref: /schemas/types.yaml#/definitions/uint32
> -      enum: [0, 1, 2, 3]
> +      '#phy-cells':
> +        description: The cell contains the mode, PHY_TYPE_USB2 or PHY_TYPE_USB3,
> +          as defined in dt-bindings/phy/phy.h.
> +        const: 1
>  
> -    '#phy-cells':
> -      description: The cell contains the mode, PHY_TYPE_USB2 or PHY_TYPE_USB3,
> -        as defined in dt-bindings/phy/phy.h.
> -      const: 1
> +    required:
> +      - phys
> +      - '#phy-cells'
>  
> -  usb3-phy:
> +    additionalProperties: false
> +
> +  pcie-phy:
> +    type: object
> +
> +    properties:
> +      phys:
> +        items:
> +          - description: phandle to Serdes PHY
> +
> +      '#phy-cells':
> +        description: The cell contains the mode, PHY_TYPE_PCIE or PHY_TYPE_USB3,
> +          as defined in dt-bindings/phy/phy.h.
> +        const: 1
> +
> +    required:
> +      - phys
> +      - '#phy-cells'
> +
> +    additionalProperties: false
>  
> -  phys:
> -    items:
> -      - description: phandle to Serdes PHY. Optional if USB 3.0 is not used.
> +patternProperties:
> +  '^usb2-phy@[0-9-a-f]+$':
> +    type: object
> +
> +    properties:
> +      reg:
> +        enum: [0x0, 0x1000]
>  
> +      airoha,usb2-monitor-clk-sel:
> +        description: Describe what oscillator across the available 4
> +          should be selected for USB 2.0 Slew Rate calibration.
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        enum: [0, 1, 2, 3]
> +
> +      '#phy-cells':
> +        description: The cell contains the mode, PHY_TYPE_USB2 or PHY_TYPE_USB3,
> +          as defined in dt-bindings/phy/phy.h.
> +        const: 1
> +
> +    required:
> +      - reg
> +      - airoha,usb2-monitor-clk-sel
> +      - '#phy-cells'
> +
> +    additionalProperties: false

Looking at the amount of changes this should not be the same binding.
Also, things would be simpler if children were called 'phy', but OTOH
why do you need children in the first place? Your pcie-phy child has no
resources, except phy which can go to the parent device.

Best regards,
Krzysztof