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

[Christian Marangi <ansuelsmth@gmail.com>]

On Thu, Aug 13, 2026 at 10:33:31AM +0200, Krzysztof Kozlowski wrote:
> 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@gmail.com>
> > ---
> >  .../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.
> 

Yes while writing the schema I also got this doubt that I should have just
made 2 different schema. I wanted to put everything in one as they are the
same HW and driver.

I will just split these 2 to simplify it.

The child is just for consistency with the USB and easier implementation on
the driver. But I guess for DT this is a no go. I will rework the driver to
drop the redundant child for the PCIe variant.

-- 
	Ansuel