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

Rob Herring
2025-11-20T17:30:14Z

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
>