On Tue, Sep 01, 2015 at 09:59:14AM -0700, Tim Bird wrote: > On Thu, Aug 27, 2015 at 10:23 PM, Matt Porter <mporter@xxxxxxxxxxxx> wrote: > > Documentation explaining the syntax and format of the YAML-based DT binding > > documentation. > > > > Signed-off-by: Matt Porter <mporter@xxxxxxxxxxxx> > > --- > > .../devicetree/bindings/dt-binding-format.txt | 106 +++++++++++++++++++++ > > 1 file changed, 106 insertions(+) > > create mode 100644 Documentation/devicetree/bindings/dt-binding-format.txt > > > > diff --git a/Documentation/devicetree/bindings/dt-binding-format.txt b/Documentation/devicetree/bindings/dt-binding-format.txt > > new file mode 100644 > > index 0000000..f9acc22 > > --- /dev/null > > +++ b/Documentation/devicetree/bindings/dt-binding-format.txt > > @@ -0,0 +1,106 @@ > > +-------------------------- > > +Device Tree Binding Format > > +-------------------------- > > + > > +Background > > +---------- > > + > > +DT bindings historically were written as text in prose format which > > +led to issues in usability of that source documentation. Some of > > +these issues include the need to programmatically process binding > > +source documentation to do DTS validation, perform mass updates to > > +format/style, and to generate publishable documentation in HTML or > > +PDF form. > > + > > +Overview > > +-------- > > + > > +The DT binding format is based on the YAML text markup language. > > +Although there are many text markup options available, YAML > > +fulfills all requirements considered for a DT binding source format > > +which include: > > + > > +1) Must be human readable > > +2) Must be easily translated to other data formats (XML, JSON, etc). > > +3) Must have sufficient tools and libraries to enable developers to > > + build new tools for DT binding processing > > +4) Must have a complete spec to refer to syntax > > + > > +YAML is documentated in the specification found at > > +http://www.yaml.org/spec/1.2/spec.html > > + > > +The required YAML DT binding tag format and syntax are defined in > > +the following sections. > > + > > +YAML DT Binding Syntax > > +---------------------- > > + > > +* Lines starting with "#" are comments and not part of the binding itself > > +* "%YAML 1.2" starts a file, indicating the version of YAML in use > > I think it would be good to specify a DT Binding Format version as well. > I would expect we may expand the syntax, or we may alter it, so it > would be good to have a number for our specific syntax. This would > help in some circumstances, if we make multiple passes over the > documents to achieve our conversion. Maybe this should be added > below. Good point. In fact, I think it's absolutely essential that we include that. This is a complicated business and we're bound to make mistakes in the binding definition format - a version number gives us a way to fix them without requiring changing all the existing bindings at once. [snip] > > +* [O] compatible: sequence of valid compatible descriptors > > + [R] name: the compatible string surrounded in double quotes > > + [O] deprecated: a deprecated compatible string surrounded in > > + double quotes > > + [O] description: description of the compatible string > > compatible is a property like all the others, and I think it's confusing > to have it in a separate section. For example, when listing other > properties, the "name:" field specifies the property name, but for > the compatible section the "name:" field specifies the possible values > for the compatible property. This is (at least to me) quite confusing. > > Can we make this a regular property, with an option 'deprecated' attribute. > I guess we may need to distinguish between deprecated properties and > deprecated vales of properties. > The above 'deprecated' specifies deprecated values for the compatible > property, while > the section below specifies deprecated properties. I don't see a way > to indicate a deprecated > value for a still-existing property, but that may be too much detail for now. So, I think folding compatible in with the rest is a mistake. There are two important distinctions between compatible and the other property descriptions: 1) (See my other post for context) The most important is that compatible is the "key" for the binding. It's what lets you know the binding is in play, rather than just saying what the requirements are once you know it's a relevant binding. 2) The condition we're typically listing for compatible is that it must contain the given compatible string - it's valid and common to also have additional compatible strings (e.g. for the future, backwards-compatible revision of this device). For most other properties we're describing the *whole* value it should have. Eventually I think we'll want a general way of expressing such "equals" versus "contains" conditions, but that's a pretty hard problem, so for the first cut I think it's reasonable to special case 'compatible'. Incidentally, note that it would also be quite common for 'compatible' to appear in *both* the "key" and the requirements. e.g. the binding for "foo,bardev-revision-b" could require that compatible also list "foo,bardev-revision-a" if it's backwards compatible. > > +* [O] required: sequence of required properties: > > + [R] name: name of the property surrounded in double quotes > > + [R] description: description of the property > > + [O] reference: optional reference to a binding id > > I would recommend we add types and value constraints to the > binding schema: > > [O] type: type of value for this property, and if specified must be > one of the following (without quotes): > "string", "number", "array", "phandle" It might be worth re-using the type names used in old OF documents here. Although "prop-encoded-array" tends to cover an awful lot there. > [O] value constraint: specifies a limit on the value for a property. > This can be specified as English text, or be a range or choice constraint. > The latter two should be expressed with the following exact english > phrases (without quotes): > "must be in the range x to y, inclusive" > where x and y are numbers > "must be one of <choice 1>, <choice 2>, ..." > where <choice x> is a string, which should be quoted > if it includes a comma. > > Any other constraint is expressed in free-form English text Requiring exact english phrases when we're already have a flexible encoding scheme with YAML is pretty horrid. I'd suggest instead that English constraints just go in the description. We can add new fields for specific types of machine verifiable constraints as we implement them (e.g. "max", "min", "allowed-values"). > I would recommend adding these to this binding schema doc, but > not requiring them on the first conversion pass of the docs. > > Basically my idea is that you want the each pass over the binding > documents to be as painless as possible. Every time a user encounters > something they're not sure about, it will slow them down. There will > be lots of ambiguous situations, and we want the process to be as > lossless as possible, so I would recommend a strategy of doing as > much as people can, and if in doubt just put any outstanding text > in the descriptions. The descriptions will always be free-form text, > and we can come along later and convert these to types, constraints, > as we see fit. > > > +* [O] optional: sequence of optional properties: > > + [R] name: name of the property surrounded in double quotes > > + [R] description: description of the property > > + [O] reference: optional reference to a binding id > > + > > +* [O] deprecated: sequence of deprecated properties: > > + [R] name: name of the property surrounded in double quotes > > + [R] description: description of the property > > + [O] reference: optional reference to a binding id > > + > > +* [R] example: sequence of examples: > > + [R] dts: DT source of example usage. The example text must use > > + literal style ("|") so that it retains indentation and > > + newlines. > > + [O] description: description of the example > > + > > I'd recommend having a top-level notes section: > * [O] note: any other notes about this node that are not covered by > preceding property descriptions. Good call. Although I'd suggest "description" to match the name used elsewhere. > > +Note: [R] and [O] denote required and optional fields, respectively. > > I'd put this note before the format description. > > -- Tim > > > + > > +Skeleton Binding > > +---------------- > > + > > +The skeleton.yaml binding found in the top of the DT binding tree > > +is the canonical example of syntax and format to use when writing > > +a DT binding document. It is maintained with the latest formatting > > +conventions, making it the best starting point when writing a new DT > > +binding. > > -- -- David Gibson | I'll have my music baroque, and my code david AT gibson.dropbear.id.au | minimalist, thank you. NOT _the_ _other_ | _way_ _around_! http://www.ozlabs.org/~dgibson
Attachment:
pgpaFO7OFJVCk.pgp
Description: PGP signature
