Re: [PATCH v2 1/2] dt-bindings: mfd: Document support for Airoha AN8855 Switch SoC

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:
- [Medium] dt-bindings: mfd: airoha,an8855: missing ethernet-switch node breaks DT ABI
- [Low] dt-bindings: mfd: airoha,an8855: undocumented PHY nvmem-cells in example
--

commit 5c22f417efc026df5dc02aca005efec24fec3d06
Author: Christian Marangi <ansuelsmth@gmail.com>

dt-bindings: mfd: Document support for Airoha AN8855 Switch SoC

This commit adds the MFD device tree binding schema for the Airoha AN8855
Switch SoC, documenting its efuse NVMEM provider and MDIO bus child nodes.

> diff --git a/Documentation/devicetree/bindings/mfd/airoha,an8855.yaml b/Documentation/devicetree/bindings/mfd/airoha,an8855.yaml
> new file mode 100644
> index 0000000000000..ee72411548516
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mfd/airoha,an8855.yaml
> @@ -0,0 +1,134 @@

[ ... ]

> +properties:
> +  compatible:
> +    const: airoha,an8855
> +
> +  reg:
> +    maxItems: 1
> +
> +  reset-gpios:
> +    maxItems: 1
> +
> +  efuse:
> +    type: object
> +    $ref: /schemas/nvmem/airoha,an8855-efuse.yaml
> +    description: EFUSE exposed by the Airoha AN8855 SoC
> +
> +  mdio:
> +    type: object
> +    $ref: /schemas/net/mdio.yaml#
> +    description: MDIO exposed by the Airoha AN8855 SoC
> +    unevaluatedProperties: false
> +
> +required:
> +  - compatible
> +  - reg
> +  - mdio
> +
> +additionalProperties: false

[Severity: Medium]
The description states that the Airoha AN8855 Switch SoC exposes an Ethernet
Switch, an NVMEM provider, and Ethernet PHYs, and the accompanying MFD driver
registers MFD cells for both airoha,an8855-efuse and airoha,an8855-switch.

However, properties in airoha,an8855.yaml omits the ethernet-switch child
node while setting additionalProperties: false, and leaves efuse out of the
required list.

In Device Tree bindings, adding a child node to required after the binding is
merged breaks DT ABI compatibility because existing DTBs without that child
node become invalid, and bindings are expected to describe the complete
hardware up front rather than staging child nodes across driver series.

Should the DSA switch schema be included with this series so that
ethernet-switch and efuse can both be documented and marked required from the
start?

[ ... ]

> +            mdio {
> +                #address-cells = <1>;
> +                #size-cells = <0>;
> +
> +                internal_phy1: ethernet-phy@1 {
> +                  compatible = "ethernet-phy-idc0ff.0410",
> +                               "ethernet-phy-ieee802.3-c22";
> +                  reg = <1>;
> +
> +                  nvmem-cells = <&shift_sel_port0_tx_a>,
> +                      <&shift_sel_port0_tx_b>,
> +                      <&shift_sel_port0_tx_c>,
> +                      <&shift_sel_port0_tx_d>;
> +                  nvmem-cell-names = "tx_a", "tx_b", "tx_c", "tx_d";
> +                };

[Severity: Low]
In examples, internal_phy1 and internal_phy2 under the mdio node specify
compatible = "ethernet-phy-idc0ff.0410", "ethernet-phy-ieee802.3-c22" along
with nvmem-cells and nvmem-cell-names = "tx_a", "tx_b", "tx_c", "tx_d".

Documentation/devicetree/bindings/net/ethernet-phy.yaml does not define
nvmem-cells or nvmem-cell-names, and no binding schema under
Documentation/devicetree/bindings/net/ documents ethernet-phy-idc0ff.0410 or
these calibration cell names. The example only passes dt_binding_check
because ethernet-phy.yaml sets additionalProperties: true.

Does this need a dedicated PHY binding schema documenting those nvmem
calibration properties before using them in the example?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261103203034.12869-1-ansuelsmth@gmail.com?part=1