| Message ID | 1440739433-6799-3-git-send-email-mporter@konsulko.com |
|---|---|
| State | Superseded, archived |
| Headers | show |
On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter <mporter@konsulko.com> 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@konsulko.com> > --- > 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@kernel.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. 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 > + 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> > + > +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 = <1000000>; > + 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" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Hi Rob, > On Aug 28, 2015, at 17:53 , Rob Herring <robherring2@gmail.com> wrote: > > On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter <mporter@konsulko.com> 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@konsulko.com> >> --- >> 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@kernel.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. > > 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 >> + 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> > I would like something that looks like a C expression. For instance - constraint: spi-max-frequency >= 1000000 && spi-max-frequency < 10000000 >> + >> +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 = <1000000>; >> + 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" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
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@konsulko.com> 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@konsulko.com> > > --- > > 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@kernel.org> > > 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 > > + 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> 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 require some thought. > > + > > +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 = <1000000>; > > + 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. Yeah, I would say that a huge majority of the examples we have now become useless with this format. I like that idea of just generating it for those users trying to read and understand what it looks like in dts form. Less room for error. We can retain the examples field for those complex examples that need human intervention to craft and describe them properly. -Matt -- To unsubscribe from this list: send the line "unsubscribe devicetree" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Fri, Aug 28, 2015 at 12:49 PM, Matt Porter <mporter@konsulko.com> 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@konsulko.com> 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@konsulko.com> >> > --- >> > 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@kernel.org> >> >> 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 >> >> 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. Yes, in many cases they are implied. It should be simple enough to generate the list though whether they point to the doc file or just list the properties. > > 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 >> > + 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> > > 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 require some thought. We can always add constraints as a second step, but I'd like to define the structure at least. Rob -- To unsubscribe from this list: send the line "unsubscribe devicetree" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On 8/28/2015 11:55 AM, Rob Herring wrote: > On Fri, Aug 28, 2015 at 12:49 PM, Matt Porter <mporter@konsulko.com> 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@konsulko.com> 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@konsulko.com> >>>> --- >>>> 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@kernel.org> >>> >>> 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 means that we need to define the how to specify the type information. >> 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 >>> >>> 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. > > Yes, in many cases they are implied. It should be simple enough to > generate the list though whether they point to the doc file or just > list the properties. > >> >> 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 >>>> + 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> >> >> 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 require some thought. > > We can always add constraints as a second step, but I'd like to define > the structure at least. Agreed, this is something that I would like to see defined, just to make sure that we can do it in a reasonable way with the proposed tool. > Rob > -Frank -- To unsubscribe from this list: send the line "unsubscribe devicetree" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Fri, Aug 28, 2015 at 01:55:11PM -0500, Rob Herring wrote: > On Fri, Aug 28, 2015 at 12:49 PM, Matt Porter <mporter@konsulko.com> 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@konsulko.com> 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@konsulko.com> > >> > --- > >> > 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@kernel.org> > >> > >> 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 by reference, the task of documenting these won't be so bad. > > 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 I was expecting the YAML haters by now, I'll give it another few days. :) > 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. Agreed. > > 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. > > Yes, in many cases they are implied. It should be simple enough to > generate the list though whether they point to the doc file or just > list the properties. Ok. > > > > > 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 > >> > + 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> > > > > 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 require some thought. > > We can always add constraints as a second step, but I'd like to define > the structure at least. Ok, this sounds reasonable, I'm goling to take a stab at reorganizing the format based on the big areas of references, property types, and property constraints. -Matt -- To unsubscribe from this list: send the line "unsubscribe devicetree" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Fri, Aug 28, 2015 at 7:53 AM, Rob Herring <robherring2@gmail.com> wrote: > On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter <mporter@konsulko.com> wrote: ... >> +example: >> + - dts: | >> + sk11@0 { >> + compatible = "skel,sk11"; >> + reg = <0>; >> + spi-max-frequency = <1000000>; >> + 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" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Le 01/09/2015 19:35, Tim Bird a écrit : > On Fri, Aug 28, 2015 at 7:53 AM, Rob Herring <robherring2@gmail.com> wrote: >> On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter <mporter@konsulko.com> wrote: > ... >>> +example: >>> + - dts: | >>> + sk11@0 { >>> + compatible = "skel,sk11"; >>> + reg = <0>; >>> + spi-max-frequency = <1000000>; >>> + 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,
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 <mporter@konsulko.com> 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@konsulko.com> 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@konsulko.com> > >>>> --- > >>>> 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@kernel.org> > >>> > >>> 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 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. Ok. > Which means that we need to define the how to specify the type information. Agreed, I'm adding that to the format in v2. > >> 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 > >>> > >>> 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. > > > > Yes, in many cases they are implied. It should be simple enough to > > generate the list though whether they point to the doc file or just > > list the properties. > > > >> > >> 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 > >>>> + 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> > >> > >> 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 require some thought. > > > > We can always add constraints as a second step, but I'd like to define > > the structure at least. > > Agreed, this is something that I would like to see defined, just to make > sure that we can do it in a reasonable way with the proposed tool. Will do, adding that in v2. -Matt -- To unsubscribe from this list: send the line "unsubscribe devicetree" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Tue, Sep 01, 2015 at 10:35:44AM -0700, Tim Bird wrote: > On Fri, Aug 28, 2015 at 7:53 AM, Rob Herring <robherring2@gmail.com> wrote: > > On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter <mporter@konsulko.com> wrote: > ... > >> +example: > >> + - dts: | > >> + sk11@0 { > >> + compatible = "skel,sk11"; > >> + reg = <0>; > >> + spi-max-frequency = <1000000>; > >> + 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" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
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 <robherring2@gmail.com> wrote: > >> On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter <mporter@konsulko.com> wrote: > > ... > >>> +example: > >>> + - dts: | > >>> + sk11@0 { > >>> + compatible = "skel,sk11"; > >>> + reg = <0>; > >>> + spi-max-frequency = <1000000>; > >>> + 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" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
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@konsulko.com> 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@konsulko.com> > > --- > > 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@kernel.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.
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 <mporter@konsulko.com> 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@konsulko.com> >>> --- >>> 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@kernel.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. 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 >>> + 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. 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 current versions and at least let > tools know that they won't be able to check everything. Just keeping the existing doc text will preserve things. Rob -- To unsubscribe from this list: send the line "unsubscribe devicetree" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
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 <mporter@konsulko.com> 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@konsulko.com> > >>> --- > >>> 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@kernel.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. > > 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. > > > >> 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. True/ > > 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 > >>> + 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. > > 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. Sure. > > 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. > > Just keeping the existing doc text will preserve things.
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@konsulko.com> 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@konsulko.com> > > > --- > > > 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@kernel.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. 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
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@kernel.org> + +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 + 1000000 + 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 = <1000000>; + spi-cs-high; + }; +... + +--- +id: skel-mini + +title: Skeleton Mini Device + +maintainer: + - name: Rogue Developer <rogue@gmail.com> + +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@beef0000 { + compatible = "skel,sk472"; + reg = <0xbeef0000 0x100>; + }; + description: > + Demonstrates an SK472 in normal mode. + + - dts: | + sk474@dead0000 { + compatible = "skel,sk474"; + reg = <0xdead0000 0x100>; + skel,sync-mode; + }; + description: > + Demonstrates an SK474 in synchronous mode. +...
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@konsulko.com> --- Documentation/devicetree/bindings/skeleton.yaml | 98 +++++++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 Documentation/devicetree/bindings/skeleton.yaml