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

title: Power Sourcing Equipment (PSE).

description: Binding for the Power Sourcing Equipment (PSE) as defined in the
  IEEE 802.3 specification. It is designed for hardware which is delivering
  power over twisted pair/ethernet cable. The ethernet-pse nodes should be
  used to describe PSE controller and referenced by the ethernet-phy node.

maintainers:
  - Oleksij Rempel <o.rempel@pengutronix.de>
  - Kory Maincent <kory.maincent@bootlin.com>

properties:
  $nodename:
    pattern: "^ethernet-pse(@.*|-([0-9]|[1-9][0-9]+))?$"

  "#pse-cells":
    description:
      Used to uniquely identify a PSE instance within an IC. Will be
      0 on PSE nodes with only a single output and at least 1 on nodes
      controlling several outputs which are not described in the pse-pis
      subnode. This property is deprecated, please use pse-pis instead.
    enum: [0, 1]

  pse-pis:
    type: object
    description:
      Overview of the PSE PIs provided by the controller.

    properties:
      "#address-cells":
        const: 1

      "#size-cells":
        const: 0

    required:
      - "#address-cells"
      - "#size-cells"

    patternProperties:
      "^pse-pi@[0-9a-f]+$":
        type: object
        description:
          PSE PI for power delivery via pairsets, compliant with IEEE
          802.3-2022, Section 145.2.4. Each pairset comprises a positive and
          a negative VPSE pair, adhering to the pinout configurations
          detailed in the standard.
          See Documentation/networking/pse-pd/pse-pi.rst for details.

        properties:
          reg:
            description:
              Address describing the PSE PI index.
            maxItems: 1

          "#pse-cells":
            const: 0

          pairset-names:
            $ref: /schemas/types.yaml#/definitions/string-array
            description:
              Names of the pairsets as per IEEE 802.3-2022, Section 145.2.4.
              Each name should correspond to a phandle in the 'pairset'
              property pointing to the power supply for that pairset.
            minItems: 1
            maxItems: 2
            items:
              enum:
                - alternative-a
                - alternative-b

          pairsets:
            $ref: /schemas/types.yaml#/definitions/phandle-array
            description:
              List of phandles, each pointing to the power supply for the
              corresponding pairset named in 'pairset-names'. This property
              aligns with IEEE 802.3-2022, Section 33.2.3 and 145.2.4.
              PSE Pinout Alternatives (as per IEEE 802.3-2022 Table 145\u20133)
              |-----------|---------------|---------------|---------------|---------------|
              | Conductor | Alternative A | Alternative A | Alternative B | Alternative B |
              |           |    (MDI-X)    |     (MDI)     |      (X)      |      (S)      |
              |-----------|---------------|---------------|---------------|---------------|
              | 1         | Negative VPSE | Positive VPSE | -             | -             |
              | 2         | Negative VPSE | Positive VPSE | -             | -             |
              | 3         | Positive VPSE | Negative VPSE | -             | -             |
              | 4         | -             | -             | Negative VPSE | Positive VPSE |
              | 5         | -             | -             | Negative VPSE | Positive VPSE |
              | 6         | Positive VPSE | Negative VPSE | -             | -             |
              | 7         | -             | -             | Positive VPSE | Negative VPSE |
              | 8         | -             | -             | Positive VPSE | Negative VPSE |
            minItems: 1
            maxItems: 2

          polarity-supported:
            $ref: /schemas/types.yaml#/definitions/string-array
            description:
              Polarity configuration supported by the PSE PI pairsets.
            minItems: 1
            maxItems: 4
            items:
              enum:
                - MDI-X
                - MDI
                - X
                - S

          vpwr-supply:
            description: Regulator power supply for the PSE PI.

        required:
          - reg
          - "#pse-cells"

oneOf:
  - required:
      - "#pse-cells"
  - required:
      - pse-pis

additionalProperties: true

...