Re: [RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document
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 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
> > > ---
> > > 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 000..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
> >
> > 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
> > > + 100
> > > +reference: spi-slave
> >
> > Rather than listing the property and having constraint in description,
> > perhaps we could add constraints like this:
> >
> > - spi-max-frequency-range: 100 100
> >
> > Or groups of constraints:
> >
> > - spi-max-frequency-constraints:
> > range: 100 100
> > some-other-constraint:
>
> 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 abl
Re: [RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document
On Thu, Sep 10, 2015 at 11:46:13PM -0500, Rob Herring wrote: > On 09/10/2015 02:08 AM, 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 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 > >>> --- > >>> 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 000..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 > >> > >> 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. > > I don't think so. Often "old" is a singleton, and "new" is one of > several newer chips. Yeah, so the trouble is bindings like that are kind of unclear (although you can generally figure it out by convention). Giving AND and OR conditions gives more detail, but still doesn't really express what you want here. Supposeyou have the SK33 device, and its backwards compatible revisions the SK34 and SK35. There's also the SK38, which is compatible with the original SK33, but not the revised versions. So really, you have a cluster of related bindings: SK33 binding: Applies when compatible contains "skel,sk33" Requires compatible contain "skel,sk33" Describes all the basic properties of the device SK34 binding: Applies when compatible contains "skel,sk34" Requires compatible contain "skel,sk34" AND "skel,sk33" Inherits the SK33 binding Describes any properties necessary for SK34 extensions SK35 binding Applies when compatible contains "skel,sk35" Requires compatible contains "skel,sk35", "skel,sk34" AND "skel,sk33" Inherits the SK34 binding Describes any properties for SK35 extensions SK38 binding Applies when compatible contains "skel,sk38" Requires compatible contains "skel,sk38" AND "skel,sk33" Requires compatible DOES NOT contain "skel,sk34" or "skel,sk35" (arguably you don't need to specify that, though) Inherits the SK33 binding Describes any properties for SK38 extensions Plus, for backwards compatibility you might have to have the: SK3x binding Deprecated Applies when compatible contains "skel,sk3x" Inherits the SK33 binding > It is also very common for licensed IP blocks. All > the vendors have different quirks and possibly different versions of the > IP. In the better cases, we can have a vendor compat for each vendor and > then a generic compat. So, similar considerations here. You really have a bunch of at least potentially different bindings for each licensed variant, but all based on the core common binding. > > 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. But, yeah, these are common cases so we need a less verbose way of describing it than the full version above. At least when the differences between the devices don't require any new properties at all. I think we want to special case this for the compatible property though. I thinkAND and OR conditions will be complex, while still not really expressing what we need for compatible. > >
Re: [RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document
On 09/10/2015 02:08 AM, 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 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
>>> ---
>>> 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 000..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
>>
>> 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.
I don't think so. Often "old" is a singleton, and "new" is one of
several newer chips. It is also very common for licensed IP blocks. All
the vendors have different quirks and possibly different versions of the
IP. In the better cases, we can have a vendor compat for each vendor and
then a generic compat.
> 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.
And reg is well defined, so that's one I'm least worried about.
> 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.
Yes, I would fully expect reg to just be flagged as used and how many
addresses.
>
>>> +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
>>> + 100
>>> +reference: spi-slave
>>
>> Rather than listing the property and having constraint in description,
>> perhaps we could add constraints like this:
>>
>> - spi-max-frequency-range: 100 100
>>
>> Or groups of constraints:
>>
>> - spi-max-frequency-constraints:
>> range: 100 100
>> some-other-constraint:
>
> 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.
At least for simple constraints, I don't see the point of manually
converting to something still not machine parse-able. We should be able
to figure out a syntax. Sure, there may be complex examples we just punt
on, but we can address most common cases. But if we can't define a
syntax, then lets do nothing until we do.
> 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
Re: [RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document
On Fri, Aug 28, 2015 at 09:53:06AM -0500, Rob Herring wrote:
> On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter 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
> > ---
> > 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 000..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
>
> 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
> > + 100
> > +reference: spi-slave
>
> Rather than listing the property and having constraint in description,
> perhaps we could add constraints like this:
>
> - spi-max-frequency-range: 100 100
>
> Or groups of constraints:
>
> - spi-max-frequency-constraints:
> range: 100 100
> some-other-constraint:
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
pgpPtBxeMRn38.pgp
Description: PGP signature
Re: [RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document
On Wed, Sep 02, 2015 at 10:45:13AM +0200, Nicolas Ferre wrote:
> Le 01/09/2015 19:35, Tim Bird a écrit :
> > On Fri, Aug 28, 2015 at 7:53 AM, Rob Herring wrote:
> >> On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter wrote:
> > ...
> >>> +example:
> >>> + - dts: |
> >>> + sk11@0 {
> >>> + compatible = "skel,sk11";
> >>> + reg = <0>;
> >>> + spi-max-frequency = <100>;
> >>> + spi-cs-high;
> >>> + };
> >>
> >> At least in this example, we could generate it. Examples are nice, but
> >> we have dts files full of examples already. I get a fair number of
> >> "fix the example" patches, so maybe we should eliminate the simple
> >> ones.
> >
> > I would hesitate to eliminate examples. I've been saved by them on
> > a few occasions, when the dts files only had one or two instances
> > of a type of binding, somewhat different from each other, and the example
> > helped
> > break the tie. If there's something wrong with the example, it's a sign
> > of an out-of-date binding doc, just as much as if the text were wrong.
> > It ought to be possible to validate the example versus the binding doc
> > (as Pantelis says), so ultimately we should be able to catch errors here
> > as well.
>
> I back Tim's advice.
> Example are so important that I regularly find myself thinking "ah-ha,
> okay that's supposed to work like that" after having read the binding
> documentation.
See my comments on Tim's post. In summary, we'd retain the complex type
examples but allow the trivial ones to not bother with it in explicit
source. OTOH, this would have to be a final change in the conversion
process, most likely, because we need all the type: and constraints:
tags present in order to generate a working example.
Of course, that's the same info necessary to validate a dts as well.
Perhaps it's best to look at this as the automated conversion process
that Rob suggested. That is, we'll have the current text (including
all examples) brought into the .yaml file as comments. So we aren't
eliminating examples. Later, if those examples are too trivial to
bother capturing as above, we simply remove and one can dump an example
via a doc generator not unlike my markdown example (which can spit out
pasteable text).
-Matt
--
To unsubscribe from this list: send the line "unsubscribe devicetree-spec" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document
On Tue, Sep 01, 2015 at 10:35:44AM -0700, Tim Bird wrote:
> On Fri, Aug 28, 2015 at 7:53 AM, Rob Herring wrote:
> > On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter wrote:
> ...
> >> +example:
> >> + - dts: |
> >> + sk11@0 {
> >> + compatible = "skel,sk11";
> >> + reg = <0>;
> >> + spi-max-frequency = <100>;
> >> + spi-cs-high;
> >> + };
> >
> > At least in this example, we could generate it. Examples are nice, but
> > we have dts files full of examples already. I get a fair number of
> > "fix the example" patches, so maybe we should eliminate the simple
> > ones.
>
> I would hesitate to eliminate examples. I've been saved by them on
> a few occasions, when the dts files only had one or two instances
> of a type of binding, somewhat different from each other, and the example
> helped
> break the tie. If there's something wrong with the example, it's a sign
> of an out-of-date binding doc, just as much as if the text were wrong.
> It ought to be possible to validate the example versus the binding doc
> (as Pantelis says), so ultimately we should be able to catch errors here
> as well.
I think part of the suggestion is that we can simply generate the common
examples from the tags (as part of formatted doc generation) rather than it
being a verbatim paste from a dts file. This has the benefit of not
getting that verbatim text of of sync with a dts (because we'll
eventually validating the dts files versus the binding doc). Does that
still achieve what you want? Keep in mind that we aren't talking about
taking away the ability to put an explicit verbatim example, but rather
making it an exception case to demonstrate some variants where an author
wants to point out different common use cases.
-Matt
--
To unsubscribe from this list: send the line "unsubscribe devicetree-spec" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document
On Sun, Aug 30, 2015 at 03:18:19PM -0700, Frank Rowand wrote:
> On 8/28/2015 11:55 AM, Rob Herring wrote:
> > On Fri, Aug 28, 2015 at 12:49 PM, Matt Porter 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
> >>> 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
> ---
> 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 000..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
> >>>
> >>> We'd want to tie this into get_maintainers.pl obviously.
> >>
> >> Right, I broke my rule of "no new tags for content we don't already
> >> have" by adding this. It stems out of the discussion at LPC where
> >> Mark suggested we could avoid the core bindings being moved by adding
> >> maintainer info into the binding itself.
> >
> > If you stated that rule, I missed it...
> >
> >> This is an area where more docs are needed. Ideally, on the first pass
> >> conversion we would not attempt to populate these. I had considered
> >> that we *could* only add maintainer: tags on core bindings to and
> >> adjust get_maintainers.pl to use that info to override the standard
> >> directory-based info if it exists. I don't think it's necessary to add
> >> a specific maintainer for all of the peripheral bindings if the default
> >> is the subsystem maintainer and the dt list. We could at least start
> >> directing core binding discussion to the -spec list which is where I
> >> think you'd like it.
>
> I think that adding the maintainer: tags for core bindings in the conversion
> process (and optionally add the tag for other bindings in the person
> converting has the driver and subsystem knowledge to intelligently
> do so -- not just a blind list from get_maintainer) would be a valid
> exception to your desire to not add new information on the conversion
> step. As much as other uses of information from bindings is near and
> dear to me, I think that throttling the binding review fire hose is
> the highest priority use of additional information.
Ok, and the other suggestion is to just populate it with the original
author so that's straightforward enough to do.
>
>
> > Yes, certainly this can solve my problem around handling core bindings.
> >
> > Some subsystem maintainers require a driver have a maintainer. We
> > could certainly enforce that too. We could probably automatically
> > populate this with the original author as a starting point. OTOH,
> > bindings should not change frequently.
> >
> >>
> +
> +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.
> >>
> >> True, this only covers the OR case atm.
> >>
> >>> The complicated case is "one of {specific names} followed by {generic
> >>> name}."
> >>
> >> I need to rethink these. I do have deprecated: tag for that case and
> >> possibly "name:" gets split to "generic:" and "specific:" and we can
> >> then do the right thing.
> >>
> >> For the above I would have:
> >>
> >> compatible:
> >> - specific: "skel,sk11"
> >> - specific: "faux,fx11"
> >
> > This can still be an AND or OR relationship.
> >
> >>
> >> and something like the Allwinner simple framebuffer would be:
> >>
> >> compatible:
> >> - generic: "simple-framebuffer"
> >> - specific: "allwinner,simple-framebuffer"
> >>
> >> where our validator would insist on seeing one of the specific: tags
> >> along with the generic: tag. A lot of bindings, given current doc
> >> patterns would just have two tags like above.
> >
> > We could follow Pantelis' suggestion and do C style logic expressions:
> >
> > name: ("chip1-ipblock" || "chip2-ipblock") && "generic-ipblock"
> >
> >
> >>
> +description: A clone of the original sk11 device
> +
> +required:
> + - name: "reg"
> >>>
> >>> We definitely need type info from the start.
> >>
> >> Are you sure? Ugh.
> >>
> >> My big contention here is
Re: [RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document
Le 01/09/2015 19:35, Tim Bird a écrit :
> On Fri, Aug 28, 2015 at 7:53 AM, Rob Herring wrote:
>> On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter wrote:
> ...
>>> +example:
>>> + - dts: |
>>> + sk11@0 {
>>> + compatible = "skel,sk11";
>>> + reg = <0>;
>>> + spi-max-frequency = <100>;
>>> + spi-cs-high;
>>> + };
>>
>> At least in this example, we could generate it. Examples are nice, but
>> we have dts files full of examples already. I get a fair number of
>> "fix the example" patches, so maybe we should eliminate the simple
>> ones.
>
> I would hesitate to eliminate examples. I've been saved by them on
> a few occasions, when the dts files only had one or two instances
> of a type of binding, somewhat different from each other, and the example
> helped
> break the tie. If there's something wrong with the example, it's a sign
> of an out-of-date binding doc, just as much as if the text were wrong.
> It ought to be possible to validate the example versus the binding doc
> (as Pantelis says), so ultimately we should be able to catch errors here
> as well.
I back Tim's advice.
Example are so important that I regularly find myself thinking "ah-ha,
okay that's supposed to work like that" after having read the binding
documentation.
Bye,
--
Nicolas Ferre
--
To unsubscribe from this list: send the line "unsubscribe devicetree-spec" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document
On Fri, Aug 28, 2015 at 7:53 AM, Rob Herring wrote:
> On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter wrote:
...
>> +example:
>> + - dts: |
>> + sk11@0 {
>> + compatible = "skel,sk11";
>> + reg = <0>;
>> + spi-max-frequency = <100>;
>> + spi-cs-high;
>> + };
>
> At least in this example, we could generate it. Examples are nice, but
> we have dts files full of examples already. I get a fair number of
> "fix the example" patches, so maybe we should eliminate the simple
> ones.
I would hesitate to eliminate examples. I've been saved by them on
a few occasions, when the dts files only had one or two instances
of a type of binding, somewhat different from each other, and the example helped
break the tie. If there's something wrong with the example, it's a sign
of an out-of-date binding doc, just as much as if the text were wrong.
It ought to be possible to validate the example versus the binding doc
(as Pantelis says), so ultimately we should be able to catch errors here
as well.
-- Tim
--
To unsubscribe from this list: send the line "unsubscribe devicetree-spec" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document
On Fri, Aug 28, 2015 at 01:55:11PM -0500, Rob Herring wrote:
> On Fri, Aug 28, 2015 at 12:49 PM, Matt Porter 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 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
> >> > ---
> >> > 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 000..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
> >>
> >> We'd want to tie this into get_maintainers.pl obviously.
> >
> > Right, I broke my rule of "no new tags for content we don't already
> > have" by adding this. It stems out of the discussion at LPC where
> > Mark suggested we could avoid the core bindings being moved by adding
> > maintainer info into the binding itself.
>
> If you stated that rule, I missed it...
Mental list of rules I made for my initial cut at this. I was trying
really hard to have this be a cut and paste reformatting to start and
then see where comments take us.
> > This is an area where more docs are needed. Ideally, on the first pass
> > conversion we would not attempt to populate these. I had considered
> > that we *could* only add maintainer: tags on core bindings to and
> > adjust get_maintainers.pl to use that info to override the standard
> > directory-based info if it exists. I don't think it's necessary to add
> > a specific maintainer for all of the peripheral bindings if the default
> > is the subsystem maintainer and the dt list. We could at least start
> > directing core binding discussion to the -spec list which is where I
> > think you'd like it.
>
> Yes, certainly this can solve my problem around handling core bindings.
>
> Some subsystem maintainers require a driver have a maintainer. We
> could certainly enforce that too. We could probably automatically
> populate this with the original author as a starting point. OTOH,
> bindings should not change frequently.
Populating with the original author seems easy enough.
> >> > +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.
> >
> > True, this only covers the OR case atm.
> >
> >> The complicated case is "one of {specific names} followed by {generic
> >> name}."
> >
> > I need to rethink these. I do have deprecated: tag for that case and
> > possibly "name:" gets split to "generic:" and "specific:" and we can
> > then do the right thing.
> >
> > For the above I would have:
> >
> > compatible:
> > - specific: "skel,sk11"
> > - specific: "faux,fx11"
>
> This can still be an AND or OR relationship.
Ok, so this might need to be sequences of and: and or:
key value pairs to reflect the combinations.
> > and something like the Allwinner simple framebuffer would be:
> >
> > compatible:
> > - generic: "simple-framebuffer"
> > - specific: "allwinner,simple-framebuffer"
> >
> > where our validator would insist on seeing one of the specific: tags
> > along with the generic: tag. A lot of bindings, given current doc
> > patterns would just have two tags like above.
>
> We could follow Pantelis' suggestion and do C style logic expressions:
>
> name: ("chip1-ipblock" || "chip2-ipblock") && "generic-ipblock"
That might work. More specialized parsing, but it probably is needed
to handle property values ranges anyway.
> >> > +description: A clone of the original sk11 device
> >> > +
> >> > +required:
> >> > + - name: "reg"
> >>
> >> We definitely need type info from the start.
> >
> > Are you sure? Ugh.
> >
> > My big contention here is that we don't carry that content in the
> > docs today so we shouldn't try to add it in the initial conversion.
>
> What? We have that all over the place. Boolean properties, phandles, etc.
I mean that it's not always explicitly called out in peripheral
DT bindings...it's inconsistently documented. I think that by properly
documenting this in the generic bindings as you are suggesting and
getting those properties
Re: [RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document
On 8/28/2015 11:55 AM, Rob Herring wrote:
> On Fri, Aug 28, 2015 at 12:49 PM, Matt Porter 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 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
---
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 000..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
>>>
>>> We'd want to tie this into get_maintainers.pl obviously.
>>
>> Right, I broke my rule of "no new tags for content we don't already
>> have" by adding this. It stems out of the discussion at LPC where
>> Mark suggested we could avoid the core bindings being moved by adding
>> maintainer info into the binding itself.
>
> If you stated that rule, I missed it...
>
>> This is an area where more docs are needed. Ideally, on the first pass
>> conversion we would not attempt to populate these. I had considered
>> that we *could* only add maintainer: tags on core bindings to and
>> adjust get_maintainers.pl to use that info to override the standard
>> directory-based info if it exists. I don't think it's necessary to add
>> a specific maintainer for all of the peripheral bindings if the default
>> is the subsystem maintainer and the dt list. We could at least start
>> directing core binding discussion to the -spec list which is where I
>> think you'd like it.
I think that adding the maintainer: tags for core bindings in the conversion
process (and optionally add the tag for other bindings in the person
converting has the driver and subsystem knowledge to intelligently
do so -- not just a blind list from get_maintainer) would be a valid
exception to your desire to not add new information on the conversion
step. As much as other uses of information from bindings is near and
dear to me, I think that throttling the binding review fire hose is
the highest priority use of additional information.
> Yes, certainly this can solve my problem around handling core bindings.
>
> Some subsystem maintainers require a driver have a maintainer. We
> could certainly enforce that too. We could probably automatically
> populate this with the original author as a starting point. OTOH,
> bindings should not change frequently.
>
>>
+
+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.
>>
>> True, this only covers the OR case atm.
>>
>>> The complicated case is "one of {specific names} followed by {generic
>>> name}."
>>
>> I need to rethink these. I do have deprecated: tag for that case and
>> possibly "name:" gets split to "generic:" and "specific:" and we can
>> then do the right thing.
>>
>> For the above I would have:
>>
>> compatible:
>> - specific: "skel,sk11"
>> - specific: "faux,fx11"
>
> This can still be an AND or OR relationship.
>
>>
>> and something like the Allwinner simple framebuffer would be:
>>
>> compatible:
>> - generic: "simple-framebuffer"
>> - specific: "allwinner,simple-framebuffer"
>>
>> where our validator would insist on seeing one of the specific: tags
>> along with the generic: tag. A lot of bindings, given current doc
>> patterns would just have two tags like above.
>
> We could follow Pantelis' suggestion and do C style logic expressions:
>
> name: ("chip1-ipblock" || "chip2-ipblock") && "generic-ipblock"
>
>
>>
+description: A clone of the original sk11 device
+
+required:
+ - name: "reg"
>>>
>>> We definitely need type info from the start.
>>
>> Are you sure? Ugh.
>>
>> My big contention here is that we don't carry that content in the
>> docs today so we shouldn't try to add it in the initial conversion.
>
> What? We have that all over the place. Boolean properties, phandles, etc.
Piling on... If the type information is obvious in the current binding
doc, then it should be captured in the conversion and not lost. If the
information is not currently present then it should not be required in
the conversion step.
Which mea
Re: [RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document
On Fri, Aug 28, 2015 at 12:49 PM, Matt Porter 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 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
>> > ---
>> > 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 000..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
>>
>> We'd want to tie this into get_maintainers.pl obviously.
>
> Right, I broke my rule of "no new tags for content we don't already
> have" by adding this. It stems out of the discussion at LPC where
> Mark suggested we could avoid the core bindings being moved by adding
> maintainer info into the binding itself.
If you stated that rule, I missed it...
> This is an area where more docs are needed. Ideally, on the first pass
> conversion we would not attempt to populate these. I had considered
> that we *could* only add maintainer: tags on core bindings to and
> adjust get_maintainers.pl to use that info to override the standard
> directory-based info if it exists. I don't think it's necessary to add
> a specific maintainer for all of the peripheral bindings if the default
> is the subsystem maintainer and the dt list. We could at least start
> directing core binding discussion to the -spec list which is where I
> think you'd like it.
Yes, certainly this can solve my problem around handling core bindings.
Some subsystem maintainers require a driver have a maintainer. We
could certainly enforce that too. We could probably automatically
populate this with the original author as a starting point. OTOH,
bindings should not change frequently.
>
>> > +
>> > +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.
>
> True, this only covers the OR case atm.
>
>> The complicated case is "one of {specific names} followed by {generic name}."
>
> I need to rethink these. I do have deprecated: tag for that case and
> possibly "name:" gets split to "generic:" and "specific:" and we can
> then do the right thing.
>
> For the above I would have:
>
> compatible:
> - specific: "skel,sk11"
> - specific: "faux,fx11"
This can still be an AND or OR relationship.
>
> and something like the Allwinner simple framebuffer would be:
>
> compatible:
> - generic: "simple-framebuffer"
> - specific: "allwinner,simple-framebuffer"
>
> where our validator would insist on seeing one of the specific: tags
> along with the generic: tag. A lot of bindings, given current doc
> patterns would just have two tags like above.
We could follow Pantelis' suggestion and do C style logic expressions:
name: ("chip1-ipblock" || "chip2-ipblock") && "generic-ipblock"
>
>> > +description: A clone of the original sk11 device
>> > +
>> > +required:
>> > + - name: "reg"
>>
>> We definitely need type info from the start.
>
> Are you sure? Ugh.
>
> My big contention here is that we don't carry that content in the
> docs today so we shouldn't try to add it in the initial conversion.
What? We have that all over the place. Boolean properties, phandles, etc.
> I think you are right in that we should have it documented in the
> schema but I'm concerned that we make the starting conversion
> effort too large by adding type info to all converted docs.
How we do the conversion certainly needs to be worked out. However,
first we need some sort of agreement that yes this looks promising
before we spend too much time on it. We need to wait for all the YAML
haters to come out of hiding. :) Once the direction is settled, then
we can iron out the details of the structure. Finally, then we can
determine how to do the conversion. Just because we define how type
information looks doesn't mean it has to be there day 1.
> I think we gain a lot even without at the start, but I understand
> why we need it and how it will help reduce the review firehose
> with the associated validation tools.
>
>>
>> > +description: chip select address of skeleton device
>> > +reference: spi-slave
>
Re: [RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document
On Fri, Aug 28, 2015 at 09:53:06AM -0500, Rob Herring wrote:
> On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter 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
> > ---
> > 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 000..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
>
> We'd want to tie this into get_maintainers.pl obviously.
Right, I broke my rule of "no new tags for content we don't already
have" by adding this. It stems out of the discussion at LPC where
Mark suggested we could avoid the core bindings being moved by adding
maintainer info into the binding itself.
This is an area where more docs are needed. Ideally, on the first pass
conversion we would not attempt to populate these. I had considered
that we *could* only add maintainer: tags on core bindings to and
adjust get_maintainers.pl to use that info to override the standard
directory-based info if it exists. I don't think it's necessary to add
a specific maintainer for all of the peripheral bindings if the default
is the subsystem maintainer and the dt list. We could at least start
directing core binding discussion to the -spec list which is where I
think you'd like it.
> > +
> > +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.
True, this only covers the OR case atm.
> The complicated case is "one of {specific names} followed by {generic name}."
I need to rethink these. I do have deprecated: tag for that case and
possibly "name:" gets split to "generic:" and "specific:" and we can
then do the right thing.
For the above I would have:
compatible:
- specific: "skel,sk11"
- specific: "faux,fx11"
and something like the Allwinner simple framebuffer would be:
compatible:
- generic: "simple-framebuffer"
- specific: "allwinner,simple-framebuffer"
where our validator would insist on seeing one of the specific: tags
along with the generic: tag. A lot of bindings, given current doc
patterns would just have two tags like above.
> > +description: A clone of the original sk11 device
> > +
> > +required:
> > + - name: "reg"
>
> We definitely need type info from the start.
Are you sure? Ugh.
My big contention here is that we don't carry that content in the
docs today so we shouldn't try to add it in the initial conversion.
I think you are right in that we should have it documented in the
schema but I'm concerned that we make the starting conversion
effort too large by adding type info to all converted docs.
I think we gain a lot even without at the start, but I understand
why we need it and how it will help reduce the review firehose
with the associated validation tools.
>
> > +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).
Yeah, make sense.
> Perhaps we can list the reference at the top level for the node
> instead of for every property.
That's a good point. I was wondering if per prop references would
get unwieldy once we actually add them into all the converted docs.
There's a huge number of existing docs without proper references.
Ok, I'll take a look at collecting references per group of properties.
>
> > + - name: "spi-max-frequency"
> > +description: >
> > + Maximum SPI clocking speed of skeleton device in Hz, must be
> > + 100
> > +reference: spi-slave
>
> Rather than listing the property and having constraint in description,
> perhaps we could add constraints like this:
>
> - spi-max-frequency-range: 100 100
>
> Or groups of constraints:
>
> - spi-max-frequency-constraints:
> range: 100 100
> some-other-constraint:
I was hoping to avoid this to start due to my argument for keeping it
simple for the first pass at conversion. However, the latter looks
flexible enough. We have cases with enumerated values as well to handle
the
Re: [RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document
Hi Rob,
> On Aug 28, 2015, at 17:53 , Rob Herring wrote:
>
> On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter 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
>> ---
>> 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 000..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
>
> 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.
>
> 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.
>
>> +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.
>
>> + - name: "spi-max-frequency"
>> +description: >
>> + Maximum SPI clocking speed of skeleton device in Hz, must be
>> + 100
>> +reference: spi-slave
>
> Rather than listing the property and having constraint in description,
> perhaps we could add constraints like this:
>
> - spi-max-frequency-range: 100 100
>
> Or groups of constraints:
>
> - spi-max-frequency-constraints:
> range: 100 100
> some-other-constraint:
>
I would like something that looks like a C expression.
For instance
- constraint: spi-max-frequency >= 100 && spi-max-frequency < 1000
>> +
>> +optional:
>> + - name: "spi-cs-high"
>> +description: >
>> + Set if skeleton device configuration straps are set for chip
>> + select polarity high
>> +reference: spi-slave
>> +
>> +deprecated:
>> + - name: "skel,deprecated1"
>> +description: >
>> + First of two deprecated properties.
>> + - name: "skel,deprecated2"
>> +description: >
>> + Second of two deprecated properties.
>> +
>> +example:
>> + - dts: |
>> + sk11@0 {
>> + compatible = "skel,sk11";
>> + reg = <0>;
>> + spi-max-frequency = <100>;
>> + spi-cs-high;
>> + };
>
> At least in this example, we could generate it. Examples are nice, but
> we have dts files full of examples already. I get a fair number of
> "fix the example" patches, so maybe we should eliminate the simple
> ones.
>
How about we make sure we parse the example in the binding always, so
that we verify that it does much what the binding states?
> Rob
Regards
— Pantelis
--
To unsubscribe from this list: send the line "unsubscribe devicetree-spec" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document
On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter 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
> ---
> 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 000..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
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.
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.
> +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.
> + - name: "spi-max-frequency"
> +description: >
> + Maximum SPI clocking speed of skeleton device in Hz, must be
> + 100
> +reference: spi-slave
Rather than listing the property and having constraint in description,
perhaps we could add constraints like this:
- spi-max-frequency-range: 100 100
Or groups of constraints:
- spi-max-frequency-constraints:
range: 100 100
some-other-constraint:
> +
> +optional:
> + - name: "spi-cs-high"
> +description: >
> + Set if skeleton device configuration straps are set for chip
> + select polarity high
> +reference: spi-slave
> +
> +deprecated:
> + - name: "skel,deprecated1"
> +description: >
> + First of two deprecated properties.
> + - name: "skel,deprecated2"
> +description: >
> + Second of two deprecated properties.
> +
> +example:
> + - dts: |
> + sk11@0 {
> + compatible = "skel,sk11";
> + reg = <0>;
> + spi-max-frequency = <100>;
> + spi-cs-high;
> + };
At least in this example, we could generate it. Examples are nice, but
we have dts files full of examples already. I get a fair number of
"fix the example" patches, so maybe we should eliminate the simple
ones.
Rob
--
To unsubscribe from this list: send the line "unsubscribe devicetree-spec" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document
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
---
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 000..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
+
+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"
+description: A clone of the original sk11 device
+
+required:
+ - name: "reg"
+description: chip select address of skeleton device
+reference: spi-slave
+ - name: "spi-max-frequency"
+description: >
+ Maximum SPI clocking speed of skeleton device in Hz, must be
+ 100
+reference: spi-slave
+
+optional:
+ - name: "spi-cs-high"
+description: >
+ Set if skeleton device configuration straps are set for chip
+ select polarity high
+reference: spi-slave
+
+deprecated:
+ - name: "skel,deprecated1"
+description: >
+ First of two deprecated properties.
+ - name: "skel,deprecated2"
+description: >
+ Second of two deprecated properties.
+
+example:
+ - dts: |
+ sk11@0 {
+ compatible = "skel,sk11";
+ reg = <0>;
+ spi-max-frequency = <100>;
+ spi-cs-high;
+ };
+...
+
+---
+id: skel-mini
+
+title: Skeleton Mini Device
+
+maintainer:
+ - name: Rogue Developer
+
+description: >
+ The Skeleton Mini Device binding represents the SK47x series devices
+ produced by the Skeleton Corporation.
+
+compatible:
+ - name: "skel,sk472"
+ - name: "skel,sk473"
+ - name: "skel,sk474"
+ - deprecated: "skel,sk47x"
+
+required:
+ - name: "reg"
+description: offset and length of the registers
+
+optional:
+ - name: "skel,sync-mode"
+description: Enable synchronous transfer mode
+
+example:
+ - dts: |
+ sk472@beef {
+ compatible = "skel,sk472";
+ reg = <0xbeef 0x100>;
+ };
+description: >
+ Demonstrates an SK472 in normal mode.
+
+ - dts: |
+ sk474@dead {
+ compatible = "skel,sk474";
+ reg = <0xdead 0x100>;
+ skel,sync-mode;
+ };
+description: >
+ Demonstrates an SK474 in synchronous mode.
+...
--
2.1.4
--
To unsubscribe from this list: send the line "unsubscribe devicetree-spec" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
