# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
%YAML 1.2
---
$id: http://devicetree.org/schemas/net/pse-pd/realtek,pse-mcu-gen1.yaml#
$schema: http://devicetree.org/meta-schemas/core.yaml#

title: Realtek PSE MCU

maintainers:
  - Jonas Jelonek <jelonek.jonas@gmail.com>

description: |
  A microcontroller (MCU) that manages the PSE (Power Sourcing Equipment)
  hardware on a range of managed PoE switches. The host CPU talks only to
  this MCU - over I2C/SMBus or UART - using a small message-based protocol;
  the PSE silicon it drives sits behind the MCU and is never accessed
  directly. For example, on the Zyxel GS1900-10HP the SoC reaches the MCU
  over UART, and the MCU manages the on-board PSE chip.

  This binding describes the MCU together with its Realtek firmware: the
  firmware and its host protocol, which are stable across boards. The
  microcontroller silicon is a general-purpose part that varies, and the
  PSE silicon behind the MCU (Realtek RTL823x/RTL8239* or Broadcom
  BCM59xxx) is reported by the MCU and detected at runtime - neither is
  named here.

  Two protocol generations exist, both Realtek's:
    gen1  older boards, where the MCU fronts Broadcom PSE silicon
    gen2  the altered protocol used with Realtek's own PSE silicon

  On an I2C attachment the framing the MCU firmware expects is part of the
  compatible: '-smbus' (reads carry a leading command byte and a repeated
  start) or '-i2c' (bare block writes and reads). A UART attachment carries
  no framing suffix; the transport is given by the parent 'serial' node.

  Each board additionally carries a device-specific compatible that falls
  back to one of the protocol compatibles above. Drivers bind on the
  protocol compatible; the device-specific string identifies the board and
  reserves a place for a future per-board quirk without having to retrofit
  device trees already in the field.

properties:
  compatible:
    oneOf:
      # UART
      - items:
          - enum:
              - zyxel,gs1900-10hp-a1-pse
          - const: realtek,pse-mcu-gen1

      # I2C, SMBus framing
      - items:
          - enum:
              - zyxel,gs1920-24hp-v2-pse
          - const: realtek,pse-mcu-gen1-smbus

      # UART
      - items:
          - enum:
              - zyxel,gs1900-10hp-b1-pse
              - zyxel,xmg1915-10ep-pse
          - const: realtek,pse-mcu-gen2

      # I2C, SMBus framing
      - items:
          - enum:
              - zyxel,xs1930-12hp-pse
          - const: realtek,pse-mcu-gen2-smbus

      # I2C, raw framing
      - items:
          - enum:
              - linksys,lgs328mpc-v2-pse
          - const: realtek,pse-mcu-gen2-i2c

  reg:
    maxItems: 1

  reset-gpios:
    description: Reset line of the MCU.
    maxItems: 1

  disable-ports-gpios:
    description:
      Hardware gate that forces all ports into admin-disabled state while
      asserted.
    maxItems: 1

required:
  - compatible

allOf:
  - $ref: pse-controller.yaml#
  # A '-smbus'/'-i2c' compatible is an I2C attachment: it has 'reg' and
  # cannot carry serial bus properties. A bare gen compatible is a UART
  # attachment: no 'reg', the transport comes from the parent serial node.
  - if:
      properties:
        compatible:
          contains:
            enum:
              - realtek,pse-mcu-gen1-smbus
              - realtek,pse-mcu-gen2-smbus
              - realtek,pse-mcu-gen2-i2c
    then:
      required:
        - reg
      properties:
        current-speed: false
        max-speed: false
    else:
      allOf:
        - $ref: /schemas/serial/serial-peripheral-props.yaml#

      properties:
        reg: false

unevaluatedProperties: false

examples:
  # SMBus-framed I2C attachment
  - |
    i2c {
        #address-cells = <1>;
        #size-cells = <0>;

        ethernet-pse@20 {
            compatible = "zyxel,xs1930-12hp-pse", "realtek,pse-mcu-gen2-smbus";
            reg = <0x20>;

            pse-pis {
                #address-cells = <1>;
                #size-cells = <0>;

                pse-pi@0 {
                    reg = <0>;
                    #pse-cells = <0>;
                };
            };
        };
    };

  # Raw-I2C-framed attachment
  - |
    i2c {
        #address-cells = <1>;
        #size-cells = <0>;

        ethernet-pse@20 {
            compatible = "linksys,lgs328mpc-v2-pse", "realtek,pse-mcu-gen2-i2c";
            reg = <0x20>;

            pse-pis {
                #address-cells = <1>;
                #size-cells = <0>;

                pse-pi@0 {
                    reg = <0>;
                    #pse-cells = <0>;
                };
            };
        };
    };

  # UART attachment
  - |
    serial {
        ethernet-pse {
            compatible = "zyxel,gs1900-10hp-a1-pse", "realtek,pse-mcu-gen1";
            current-speed = <19200>;

            pse-pis {
                #address-cells = <1>;
                #size-cells = <0>;

                pse-pi@0 {
                    reg = <0>;
                    #pse-cells = <0>;
                };
            };
        };
    };