Re: [PATCH net-next 12/15] dt-bindings: net: dsa: sja1105: document the PCS nodes

[Rob Herring <robh@kernel.org>]

On Tue, Nov 18, 2025 at 09:05:27PM +0200, Vladimir Oltean wrote:
> The XPCS blocks in NXP SJA1105 and SJA1110 may be described in the
> device tree, and they follow the same bindings as the other instances
> which are memory-mapped using an APB3 or MCI interface.
> 
> Document their compatible string, positioning in the switch's "regs"
> subnode, and the pcs-handle to them.
> 
> The "type: object" addition in the ethernet-port node is to suppress
> a dt_binding_check warning that states "node schemas must have a type
> or $ref". This is fine, but I don't completely understand why it started
> being required just now (apparently, the presence of "properties" under
> the port node affects this).

Yes. It's related to quirks in how json-schema works. You would think 
'properties' would require the instance to be an object, but no, such a 
schema defining properties would pass even for a boolean property. So 
requiring 'type: object' is necessary. In this case, we already do that 
elsewhere so it's not strictly needed here, but figuring that out is 
complicated.

> Cc: Rob Herring <robh@kernel.org>
> Cc: Krzysztof Kozlowski <krzk+dt@kernel.org>
> Cc: Conor Dooley <conor+dt@kernel.org>
> Cc: devicetree@vger.kernel.org
> Signed-off-by: Vladimir Oltean <vladimir.oltean@nxp.com>
> ---
>  .../bindings/net/dsa/nxp,sja1105.yaml         | 28 +++++++++++++++++++
>  .../bindings/net/pcs/snps,dw-xpcs.yaml        |  8 ++++++
>  2 files changed, 36 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml b/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml
> index 607b7fe8d28e..ee1a95d6b032 100644
> --- a/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml
> +++ b/Documentation/devicetree/bindings/net/dsa/nxp,sja1105.yaml
> @@ -85,11 +85,31 @@ properties:
>            - compatible
>            - reg
>  
> +  regs:
> +    type: object
> +    description:
> +      Optional container node for peripherals in the switch address space other
> +      than the switching IP itself. This node and its children only need to be
> +      described if board-specific properties need to be specified, like SerDes
> +      lane polarity inversion. If absent, default descriptions are used.
> +    additionalProperties: false
> +
> +    properties:
> +      '#address-cells':
> +        const: 1
> +      '#size-cells':
> +        const: 1
> +
> +    patternProperties:
> +      "^ethernet-pcs@[0-9a-f]+$":
> +        $ref: /schemas/net/pcs/snps,dw-xpcs.yaml#
> +
>  patternProperties:
>    "^(ethernet-)?ports$":
>      additionalProperties: true
>      patternProperties:
>        "^(ethernet-)?port@[0-9]$":
> +        type: object
>          allOf:
>            - if:
>                properties:
> @@ -107,6 +127,14 @@ patternProperties:
>                  tx-internal-delay-ps:
>                    $ref: "#/$defs/internal-delay-ps"
>  
> +        properties:
> +          pcs-handle:
> +            $ref: /schemas/types.yaml#/definitions/phandle

This already has a type, so drop the $ref.

> +            description:
> +              Phandle to a PCS device node from the "regs" container.
> +              Can be skipped if the PCS description is missing - in that case,
> +              the connection is implicit.
> +
>  required:
>    - compatible
>    - reg
> diff --git a/Documentation/devicetree/bindings/net/pcs/snps,dw-xpcs.yaml b/Documentation/devicetree/bindings/net/pcs/snps,dw-xpcs.yaml
> index e77eec9ac9ee..46e4f611f714 100644
> --- a/Documentation/devicetree/bindings/net/pcs/snps,dw-xpcs.yaml
> +++ b/Documentation/devicetree/bindings/net/pcs/snps,dw-xpcs.yaml
> @@ -25,6 +25,14 @@ description:
>  properties:
>    compatible:
>      oneOf:
> +      - description:
> +          Synopsys DesignWare XPCS in NXP SJA1105 switch (direct APB3 access
> +          via SPI) with custom PMA
> +        const: nxp,sja1105-pcs
> +      - description:
> +          Synopsys DesignWare XPCS in NXP SJA1110 switch (indirect APB3 access
> +          via SPI) with custom PMA
> +        const: nxp,sja1110-pcs
>        - description: Synopsys DesignWare XPCS with none or unknown PMA
>          const: snps,dw-xpcs
>        - description: Synopsys DesignWare XPCS with Consumer Gen1 3G PMA
> -- 
> 2.34.1
>