Re: [PATCH net-next + leds v2 1/7] dt-bindings: leds: document binding for HW controlled LEDs

[Rob Herring <robh@kernel.org>]

On Wed, Sep 09, 2020 at 08:33:10PM +0200, Marek Behún wrote:
> On Wed, 9 Sep 2020 20:27:30 +0200
> Andrew Lunn <andrew@lunn.ch> wrote:
> 
> > On Wed, Sep 09, 2020 at 06:25:46PM +0200, Marek Behún wrote:
> > > Document binding for LEDs connected to and controlled by various
> > > chips (such as ethernet PHY chips).
> > > 
> > > Signed-off-by: Marek Behún <marek.behun@nic.cz>
> > > Cc: Rob Herring <robh+dt@kernel.org>
> > > Cc: devicetree@vger.kernel.org
> > > ---
> > >  .../leds/linux,hw-controlled-leds.yaml        | 99
> > > +++++++++++++++++++ 1 file changed, 99 insertions(+)
> > >  create mode 100644
> > > Documentation/devicetree/bindings/leds/linux,hw-controlled-leds.yaml
> > > 
> > > diff --git
> > > a/Documentation/devicetree/bindings/leds/linux,hw-controlled-leds.yaml
> > > b/Documentation/devicetree/bindings/leds/linux,hw-controlled-leds.yaml
> > > new file mode 100644 index 0000000000000..eaf6e5d80c5f5 ---
> > > /dev/null +++
> > > b/Documentation/devicetree/bindings/leds/linux,hw-controlled-leds.yaml
> > > @@ -0,0 +1,99 @@ +# SPDX-License-Identifier: GPL-2.0-only OR
> > > BSD-2-Clause +%YAML 1.2
> > > +---
> > > +$id:
> > > http://devicetree.org/schemas/leds/linux,hw-controlled-leds.yaml#
> > > +$schema: http://devicetree.org/meta-schemas/core.yaml# +
> > > +title: LEDs that can be controlled by hardware (eg. by an ethernet
> > > PHY chip) +
> > > +maintainers:
> > > +  - Marek Behún <marek.behun@nic.cz>
> > > +
> > > +description:
> > > +  Many an ethernet PHY (and other chips) supports various HW
> > > control modes
> > > +  for LEDs connected directly to them. With this binding such LEDs
> > > can be
> > > +  described.
> > > +
> > > +properties:
> > > +  compatible:
> > > +    const: linux,hw-controlled-leds
> > > +
> > > +  "#address-cells":
> > > +    const: 1
> > > +
> > > +  "#size-cells":
> > > +    const: 0
> > > +
> > > +patternProperties:
> > > +  "^led@[0-9a-f]+$":
> > > +    type: object
> > > +    allOf:
> > > +      - $ref: common.yaml#
> > > +    description:
> > > +      This node represents a LED device connected to a chip that
> > > can control
> > > +      the LED in various HW controlled modes.
> > > +
> > > +    properties:
> > > +      reg:
> > > +        maxItems: 1
> > > +        description:
> > > +          This property identifies the LED to the chip the LED is
> > > connected to
> > > +          (eg. an ethernet PHY chip can have multiple LEDs
> > > connected to it). +
> > > +      enable-active-high:
> > > +        description:
> > > +          Polarity of LED is active high. If missing, assumed
> > > default is active
> > > +          low.
> > > +        type: boolean
> > > +
> > > +      led-tristate:
> > > +        description:
> > > +          LED pin is tristate type. If missing, assumed false.
> > > +        type: boolean
> > > +
> > > +      linux,default-hw-mode:
> > > +        description:
> > > +          This parameter, if present, specifies the default HW
> > > triggering mode
> > > +          of the LED when LED trigger is set to `dev-hw-mode`.
> > > +          Available values are specific per device the LED is
> > > connected to and
> > > +          per LED itself.
> > > +        $ref: /schemas/types.yaml#definitions/string
> > > +
> > > +    required:
> > > +      - reg  
> > 
> > My Yaml foo is not very good. Do you need to list colour, function and
> > linux,default-trigger, or do they automagically get included from the
> > generic LED binding?

They do with the '$ref: common.yaml#'. You need to list them if you want 
to say which properties of a common schema you are using (IMO, you 
should, but that's a secondary concern) and/or you have additional 
constraints on them.

> > 
> > 	Andrew
> 
> I don't know :) I copied this from other drivers, I once tried setting
> up environment for doing checking of device trees with YAML schemas,
> and it was a little painful :)

pip3 install dtschema ?

Can you elaborate on the issue.

Rob