# 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 package control registers are accessed
  through the companion IC's I2C register interface, 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.

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

  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 little-endian EPHY configuration value, with the least-significant
      byte first. 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. Bits 15
      through 10 are reserved.

      AC300 and selectable ACx00 packages require the full configuration
      field, including bits 8 and 9 even when their values are zero, returned
      as two bytes. A fixed AC200 package may provide a one-byte calibration
      value or a two-byte configuration with bit 8 clear, or omit the cell
      and use its internal eFuse calibration copy.

  nvmem-cell-names:
    const: configuration

  x-powers,ac200:
    $ref: /schemas/types.yaml#/definitions/phandle
    description:
      Phandle to the AC200 companion IC described by the x-powers,ac200 MFD
      binding. Its I2C interface provides access to the package control
      registers used to power and configure the Ethernet PHY.

  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 ]

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:
        x-powers,ac200: false
      required:
        - clocks
        - nvmem-cells
        - nvmem-cell-names
  - if:
      properties:
        compatible:
          const: x-powers,acx00-ephy-package
    then:
      required:
        - clocks
        - nvmem-cells
        - nvmem-cell-names
        - x-powers,ac200
  - if:
      properties:
        compatible:
          enum:
            - x-powers,ac300-ephy-package
            - x-powers,acx00-ephy-package
    then:
      properties:
        reg:
          maximum: 7
      patternProperties:
        ^ethernet-phy@[a-f0-9]+$:
          properties:
            reg:
              maximum: 7

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>;
            };
        };
    };

...