Re: [RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document

[David Gibson <david-xT8FGy+AXnRB3Ne2BGzF6laj5H9X9Tb+@public.gmane.org>]

[-- Attachment #1: Type: text/plain, Size: 4628 bytes --]

On Fri, Aug 28, 2015 at 09:53:06AM -0500, Rob Herring wrote:
> On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter <mporter-OWPKS81ov/FWk0Htik3J/w@public.gmane.org> wrote:
> > Add a skeleton DT binding document that serves as the canonical
> > example for implementing YAML-based DT bindings documentation.
> > The skeleton binding illustrates use of all fields and variations
> > described in the dt-binding-format.txt documentation.
> >
> > Signed-off-by: Matt Porter <mporter-OWPKS81ov/FWk0Htik3J/w@public.gmane.org>
> > ---
> >  Documentation/devicetree/bindings/skeleton.yaml | 98 +++++++++++++++++++++++++
> >  1 file changed, 98 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/skeleton.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/skeleton.yaml b/Documentation/devicetree/bindings/skeleton.yaml
> > new file mode 100644
> > index 0000000..175965f
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/skeleton.yaml
> > @@ -0,0 +1,98 @@
> > +%YAML 1.2
> > +---
> > +id: skel-device
> > +
> > +title: Skeleton Device
> > +
> > +maintainer:
> > +  - name: Skeleton Person <skel-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> 
> We'd want to tie this into get_maintainers.pl obviously.
> 
> > +
> > +description: >
> > +  The Skeleton Device binding represents the SK11 device produced by
> > +  the Skeleton Corporation. The binding can also support compatible
> > +  clones made by second source vendors.
> > +
> > +compatible:
> > +  - name: "skel,sk11"
> > +  - name: "faux,fx11"
> 
> Is this an OR or AND? We need both.

Hrm.  So, from the example below it's an OR.  But.. I think the
considerations here change when you separate out "tag" information as
I've suggested elsewhere.

The command AND case, I can think of is where you want both
"foo,new-model-device" and "foo,old-model-device".  I think the first
belongs in the "tag", but the second in the body of the requirements.

The OR case demonstrated here strikes me as very poor binding design -
but that doesn't mean we can totally avoid it, since we do have poor
bindings we want to convert.

Fwiw, I think the right way to encode "OR" at least in the "tag" is to
pick just the preferred form, then have additional bindings tagged on
the alternative forms and inheriting the main binding.  I don't know
if that's practical in the short term though.

> The complicated case is "one of {specific names} followed by {generic name}."
> 
> > +    description: A clone of the original sk11 device
> > +
> > +required:
> > +  - name: "reg"
> 
> We definitely need type info from the start.

It's interesting you should mention that here, because 'reg' is
actually a hard case for describint the type: because it's format is
determined as much by the parent bus binding as this node's binding.

I suspect it will be worth special-casing "reg" in order to make
common bindings more compact, but again, probably not in the first
pass.

> > +    description: chip select address of skeleton device
> > +    reference: spi-slave
> 
> I would like to not have to list properties if the inherited binding
> lists it. The problem is we need to say how many cells and the order
> (not a problem here, but for mmio devices).
> 
> Perhaps we can list the reference at the top level for the node
> instead of for every property.

Yeah, I think it would be worth having a top-level "inherits" field.

> > +  - name: "spi-max-frequency"
> > +    description: >
> > +      Maximum SPI clocking speed of skeleton device in Hz, must be
> > +      1000000
> > +    reference: spi-slave
> 
> Rather than listing the property and having constraint in description,
> perhaps we could add constraints like this:
> 
> - spi-max-frequency-range: 1000000 1000000
> 
> Or groups of constraints:
> 
> - spi-max-frequency-constraints:
>   range: 1000000 1000000
>   some-other-constraint: <value>

Not for the first pass I think.  What I would suggest is having
"description" for pure informational stuff, and "constraint" or maybe
just "extra" for normative constraints expressed in English.

The idea here is that over time we can add new ways of expressing
constraints.  In the meantime tools can use the "extra" field to
preseve any difficult text in the current versions and at least let
tools know that they won't be able to check everything.

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson

[-- Attachment #2: Type: application/pgp-signature, Size: 819 bytes --]