Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.32 as permitted sender) client-ip=23.128.96.32;
Date:   Thu, 19 Oct 2023 08:41:09 -0500
From:   Rob Herring <robh@kernel.org>
To:     Conor Dooley <conor@kernel.org>
Cc:     "Russell King (Oracle)" <linux@armlinux.org.uk>,
        Linus Walleij <linus.walleij@linaro.org>,
        Christian Marangi <ansuelsmth@gmail.com>,
        Andrew Lunn <andrew@lunn.ch>,
        Florian Fainelli <f.fainelli@gmail.com>,
        linux-arm-kernel@lists.infradead.org,
        Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>,
        devicetree@vger.kernel.org, Conor Dooley <conor+dt@kernel.org>,
        Sebastian Hesselbarth <sebastian.hesselbarth@gmail.com>,
        Eric Dumazet <edumazet@google.com>,
        Vladimir Oltean <olteanv@gmail.com>, netdev@vger.kernel.org,
        Jakub Kicinski <kuba@kernel.org>,
        Paolo Abeni <pabeni@redhat.com>,
        "David S. Miller" <davem@davemloft.net>,
        linux-kernel@vger.kernel.org,
        Gregory Clement <gregory.clement@bootlin.com>
Subject: Re: [PATCH net-next v4 1/7] dt-bindings: net: dsa: Require ports or
 ethernet-ports
Message-ID: <20231019134109.GA63240-robh@kernel.org>
References: <20231018-marvell-88e6152-wan-led-v4-0-3ee0c67383be@linaro.org>
 <20231018-marvell-88e6152-wan-led-v4-1-3ee0c67383be@linaro.org>
 <169762516670.391804.7528295251386913602.robh@kernel.org>
 <CACRpkdZ4hkiD6jwENqjZRX8ZHH9+3MSMMLcJe6tJa=6Yhn1w=g@mail.gmail.com>
 <ZTEL6Yw+Xcc0E4TJ@shell.armlinux.org.uk>
 <20231019-pulse-autopilot-166bb6c96090@spud>
 <ZTEgnUP0rFL2frkk@shell.armlinux.org.uk>
 <20231019-friday-fabulous-4882c4048b8c@spud>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <20231019-friday-fabulous-4882c4048b8c@spud>
Precedence: bulk

On Thu, Oct 19, 2023 at 01:46:36PM +0100, Conor Dooley wrote:
> On Thu, Oct 19, 2023 at 01:27:09PM +0100, Russell King (Oracle) wrote:
> > On Thu, Oct 19, 2023 at 12:58:46PM +0100, Conor Dooley wrote:
> > > On Thu, Oct 19, 2023 at 11:58:49AM +0100, Russell King (Oracle) wrote:
> > > > On Wed, Oct 18, 2023 at 01:11:45PM +0200, Linus Walleij wrote:
> > > > > On Wed, Oct 18, 2023 at 12:32 PM Rob Herring <robh@kernel.org> wrote:
> > > > > > On Wed, 18 Oct 2023 11:03:40 +0200, Linus Walleij wrote:
> > > > > 
> > > > > > > Bindings using dsa.yaml#/$defs/ethernet-ports specify that
> > > > > > > a DSA switch node need to have a ports or ethernet-ports
> > > > > > > subnode, and that is actually required, so add requirements
> > > > > > > using oneOf.
> > > > > > >
> > > > > > > Suggested-by: Rob Herring <robh@kernel.org>
> > > > > > > Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
> > > > > > > ---
> > > > > > >  Documentation/devicetree/bindings/net/dsa/dsa.yaml | 6 ++++++
> > > > > > >  1 file changed, 6 insertions(+)
> > > > > > >
> > > > > >
> > > > > > My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
> > > > > > on your patch (DT_CHECKER_FLAGS is new in v5.13):
> > > > > >
> > > > > > yamllint warnings/errors:
> > > > > > ./Documentation/devicetree/bindings/net/dsa/dsa.yaml:60:7: [warning] wrong indentation: expected 8 but found 6 (indentation)
> > > > > > ./Documentation/devicetree/bindings/net/dsa/dsa.yaml:62:7: [warning] wrong indentation: expected 8 but found 6 (indentation)
> > > > > 
> > > > > Really?
> > > > > 
> > > > > +  oneOf:
> > > > > +    - required:
> > > > > +      - ports
> > > > > +    - required:
> > > > > +      - ethernet-ports
> > > > > 
> > > > > Two spaces after the oneOf, 2 spaces after a required as usual.
> > > > > I don't get it.

Either way is valid. It's just 2 different common styles and I picked 
the other way. The reason is to look different for a sequence vs. 
mapping:

- required:
  - ethernet-ports

- required:
    ethernet-ports

It's easy to miss the missing '-'.


> > > > Given the other python errors spat out in Rob's report, I would suggest
> > > > that the "bot" is running a development version that hasn't been fully
> > > > tested, so anything it spits out is suspect. Maybe Rob can comment on
> > > > the validity of the warnings in the report.
> > > 
> > > In this case, I think it is correct.
> > > 2 spaces for the oneOf, 2 spaces the start of the required for the
> > > nested list, so:
> > > oneOf:
> > >   - required:
> > 
> > This is a total of two spaces indentation.
> > 
> > >       - ports
> > 
> > This is a total of six spaces indentation.
> > 
> > You mention 2 spaces for the oneOf, which explains why the "- required"
> > needs to be indented by two spaces. You also say 2 spaces for the
> > required nested list, but what about the other two spaces?
> 
> I a word that might've made it more clear.
> It is 2 spaces for the oneOf and 2 spaces _from_ the start of the
> required for the nested list.

Yes, 'oneOf' here is not a json-schema keyword, but a key under $defs 
because it is indented. 

'$defs' entries must be a schema/dict/mapping (json-schema/python/yaml 
terms). 

> 
> In theory you might have a contrived example that looks like:
> 
> oneOf:
>   - required:
>       - ports
>     properties:
>       ethernet-ports: false
> 
>   - required:
>       - ethernet-ports
>     properties:
>       ports: false
> 
> Maybe with that example you can see that each option of the oneOf
> contains a `required` and a `properties` component at 4 spaces of
> indent, and then in turn the required properties, being sub-components
> of `required` grow 2 more spaces for 6.
> 
> > I guess if you're a YAML expert, this all makes sense, but to those of
> > us who aren't, these quirky "features" of it just seem totally
> > illogical.

Indentation being significant is not quirky. Languages choose either 
indentation or brackets of some form. YAML uses one and JSON uses the 
other.

> If I were a yaml expert, I would probably be able to use the correct
> terminology to explain this better, but hopefully the example is useful.

It has little to do with YAML other than indentation is *very* 
significant in YAML. It's actually valid YAML. It's probably valid 
json-schema, but questionable use in terms of how $defs is typically 
used.

Anyways, I'm working on a fix for the meta-schema.

Rob