Re: [PATCH net-next 1/4] dt-bindings: net: dsa: realtek: describe LED usage

[Linus Walleij <linus.walleij@linaro.org>]

On Sun, Mar 10, 2024 at 5:52 AM Luiz Angelo Daros de Luca
<luizluca@gmail.com> wrote:

> Each port can have up to 4 LEDs (3 for current rtl8365mb devices). The
> LED reg property will indicate its LED group.
>
> An example of LED usage was included in an existing switch example.
>
> Cc: devicetree@vger.kernel.org
> Signed-off-by: Luiz Angelo Daros de Luca <luizluca@gmail.com>

But... is this patch even needed at all?

On the top of Documentation/devicetree/bindings/net/dsa/realtek.yaml:

allOf:
  - $ref: dsa.yaml#/$defs/ethernet-ports

In Documentation/devicetree/bindings/net/dsa/dsa.yaml:

$defs:
  ethernet-ports:
    description: A DSA switch without any extra port properties
    $ref: '#'

    patternProperties:
      "^(ethernet-)?ports$":
        patternProperties:
          "^(ethernet-)?port@[0-9a-f]+$":
            description: Ethernet switch ports
            $ref: dsa-port.yaml#
            unevaluatedProperties: false

(NB, just "ports" is fine.)
In Documentation/devicetree/bindings/net/dsa/dsa-port.yaml:

$ref: /schemas/net/ethernet-switch-port.yaml#

In Documentation/devicetree/bindings/net/ethernet-switch-port.yaml:

$ref: ethernet-controller.yaml#

In Documentation/devicetree/bindings/net/ethernet-controller.yaml:

  leds:
    description:
      Describes the LEDs associated by Ethernet Controller.
      These LEDs are not integrated in the PHY and PHY doesn't have any
      control on them. Ethernet Controller regs are used to control
      these defined LEDs.

    type: object

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

      '#size-cells':
        const: 0

    patternProperties:
      '^led@[a-f0-9]+$':
        $ref: /schemas/leds/common.yaml#

        properties:
          reg:
            maxItems: 1
            description:
              This define the LED index in the PHY or the MAC. It's really
              driver dependent and required for ports that define multiple
              LED for the same port.

        required:
          - reg

        unevaluatedProperties: false

    additionalProperties: false

Try to introduce small errors in your DTS leds node and it should warn!

I'm not claiming that above include chain is "easy to read"... It makes
perfect sense to machines but maybe is a bit to construed for human
readers.

What you should do instead (IMO) is to just keep the last part that
adds a leds node example.

Yours,
Linus Walleij