On Thu, Sep 10, 2015 at 05:08:50PM +1000, David Gibson wrote:
> 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@xxxxxxxxxxxx> 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@xxxxxxxxxxxx>
> > > ---
> > > 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@xxxxxxxxxx>
> >
> > 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.
I reworked this as a constraint key with C-like syntax to express
allowable compatible strings. It's got some warts but let's take
a look at v2 and see if good constraint syntax can handle all these
cases. I use some macro like constructs to denote a generic compatible
string that must be included in addition to the part-specific string.
>
> > 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.
I've added type in v2 and in comments note the "reg" is indeed a
special case and derived not so much from the inherited binding but
from the actual parent node as used in an implementation.
>
> > > + 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.
Added in v2
> > > + - 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.
I added the definitions of these and an example of use. This by no
means indicates that we plan to add constraints for every converted
binding. However, in some cases it's very easy to add with a C-like
constraint syntax. I'm sure there's cases where this will fall over
and needs to be extended but let's review that in the context of the
v2 posting.
-Matt
Attachment:
signature.asc
Description: Digital signature
