Re: [PATCH net-next v5 4/5] dt-bindings: net: x-powers: add AC200/AC300 EPHY packages

[Krzysztof Kozlowski <krzk@kernel.org>]

On 09/08/2026 22:28, James Hilliard wrote:
> The AC200 and AC300 contain compatible Fast Ethernet link PHYs which
> report the same Clause 22 identifier and use the same link-side register
> layout. Their package control paths differ: AC200 uses registers in its
> I2C MFD, while the AC300 control range is at a second Clause 22 address
> fixed at 16 plus the link address.
> 
> Describe both variants as Ethernet PHY packages. The package reg value is
> the link PHY base address and the child supplies the documented PHY ID,
> because the identification registers cannot be read until package setup
> has completed. The AC300 driver reaches its control range with the PHY
> package offset helpers. The AC200 package instead references its MFD.
> 
> Give fixed hardware variant-specific compatibles. Also provide an ACx00
> compatible for systems which can contain either package, with one packed
> NVMEM field containing calibration in bits 3 through 0, the AC300 selector
> in bit 8 and its low-calibration selector in bit 9. Such a description
> contains the potential resources for both backends; the driver consumes
> only those selected by the configuration field.
> 
> Describe the package clock, supply and optional xMII receive-clock
> inversion needed by some integrations. A fixed AC200 package may omit the
> NVMEM field and use its internal calibration copy. Limit AC300-capable link
> addresses to 0 through 7 so the control address remains in the documented
> range 16 through 23.
> 
> Signed-off-by: James Hilliard <james.hilliard1@gmail.com>
> ---
>  .../bindings/net/x-powers,acx00-ephy-package.yaml  | 207 +++++++++++++++++++++
>  1 file changed, 207 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/net/x-powers,acx00-ephy-package.yaml b/Documentation/devicetree/bindings/net/x-powers,acx00-ephy-package.yaml
> new file mode 100644
> index 000000000000..ae0c5e980c39
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/net/x-powers,acx00-ephy-package.yaml
> @@ -0,0 +1,207 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/net/x-powers,acx00-ephy-package.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: X-Powers AC200 and AC300 Ethernet PHY packages
> +
> +maintainers:
> +  - James Hilliard <james.hilliard1@gmail.com>
> +
> +description:
> +  The AC200 and AC300 contain compatible Fast Ethernet PHY blocks which report
> +  the same Clause 22 PHY ID and use the same link-side register layout. The
> +  package control paths differ. AC200 control registers are part of an I2C MFD,
> +  while AC300 control registers occupy a second Clause 22 address fixed at 16
> +  plus the link PHY address.
> +
> +  Systems with a known package use the corresponding AC200 or AC300 compatible.
> +  Systems which can contain either package use the ACx00 compatible and a
> +  packed NVMEM configuration field to select the backend at runtime.
> +
> +  The link PHY cannot report its ID until the package control sequence has
> +  completed, so its child node supplies the documented PHY ID. The package and
> +  child use the same base address. The AC200 driver programs that address into
> +  the package, while the AC300 driver derives its control address from it.
> +
> +select:
> +  properties:
> +    compatible:
> +      enum:
> +        - x-powers,ac200-ephy-package
> +        - x-powers,ac300-ephy-package
> +        - x-powers,acx00-ephy-package
> +  required:
> +    - compatible

Why do you need the select?

> +
> +properties:
> +  compatible:
> +    enum:
> +      - x-powers,ac200-ephy-package
> +      - x-powers,ac300-ephy-package
> +      - x-powers,acx00-ephy-package
> +
> +  reg:
> +    maximum: 31
> +
> +  clocks:
> +    maxItems: 1
> +    description:
> +      AC300 input clock, running at 24, 25, or 27 MHz. The AC200 input clock
> +      belongs to the referenced AC200 MFD instead.

Drop last sentence. Just confusing - what is a referenced MFD? There is
no such thing in the bindings as MFD and the bindings cannot depend on
Linux subsystem.

> +
> +  vcc-supply:
> +    description:
> +      3.3 V package supply. This is connected to EPHY_VCC on AC200 and VCC1
> +      on AC300.
> +
> +  nvmem-cells:
> +    maxItems: 1
> +    description:
> +      Packed EPHY configuration field. Bits 3 through 0 contain the analog
> +      calibration code, bits 7 through 4 are reserved, bit 8 selects AC300
> +      when set and AC200 when clear, and bit 9 requests the AC300
> +      low-calibration tuning sequence. A fixed AC200 package may provide only
> +      the low calibration bits or omit the cell and use its internal eFuse
> +      copy instead.
> +
> +  nvmem-cell-names:
> +    const: configuration
> +
> +  x-powers,ac200:
> +    $ref: /schemas/types.yaml#/definitions/phandle
> +    description: Reference to the AC200 MFD containing this Ethernet PHY

Confusing. "Containing" means this is part of the other one, but
phandles do not express that. Anyway, there is no such thing as MFD so
describe properly without using Linuxisms what do you need here. Then
say what for (purpose).


> +
> +  x-powers,xmii-rx-clock-inverted:
> +    type: boolean
> +    description:
> +      Invert the xMII receive clock inside the PHY. This is required by some
> +      SoC integrations, including the Allwinner H6 AC200 connection.
> +
> +patternProperties:
> +  ^ethernet-phy@[a-f0-9]+$:
> +    $ref: ethernet-phy.yaml#
> +    properties:
> +      compatible:
> +        const: ethernet-phy-id0044.1400
> +    required:
> +      - compatible
> +    unevaluatedProperties: false
> +
> +required:
> +  - compatible
> +  - vcc-supply
> +
> +dependentRequired:
> +  nvmem-cells: [ nvmem-cell-names ]

Only this is needed

> +  nvmem-cell-names: [ nvmem-cells ]

This is not.

> +
> +allOf:
> +  - $ref: ethernet-phy-package.yaml#
> +  - if:
> +      properties:
> +        compatible:
> +          const: x-powers,ac200-ephy-package
> +    then:
> +      properties:
> +        clocks: false
> +      required:
> +        - x-powers,ac200
> +  - if:
> +      properties:
> +        compatible:
> +          const: x-powers,ac300-ephy-package
> +    then:
> +      properties:
> +        reg:
> +          maximum: 7
> +        x-powers,ac200: false
> +      required:
> +        - clocks
> +        - nvmem-cells
> +        - nvmem-cell-names
> +  - if:
> +      properties:
> +        compatible:
> +          const: x-powers,acx00-ephy-package
> +    then:
> +      properties:
> +        reg:
> +          maximum: 7
> +      required:
> +        - clocks
> +        - nvmem-cells
> +        - nvmem-cell-names
> +        - x-powers,ac200
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    mdio {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        ethernet-phy-package@0 {
> +            compatible = "x-powers,acx00-ephy-package";
> +            reg = <0>;
> +            #address-cells = <1>;
> +            #size-cells = <0>;
> +            clocks = <&pwm 5>;
> +            vcc-supply = <&reg_3v3>;
> +            nvmem-cells = <&ephy_configuration>;
> +            nvmem-cell-names = "configuration";
> +            x-powers,ac200 = <&ac200>;
> +
> +            ethernet-phy@0 {
> +                compatible = "ethernet-phy-id0044.1400";
> +                reg = <0>;
> +            };
> +        };
> +    };

One example is enough, they are all almost the same (difference in one
property - clocks - does not warrant a new example usually).


Best regards,
Krzysztof