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. Added this in v2, thanks. > > > +* "---" starts a binding document > > +* "..." ends a binding document > > +* Multiple binding documents may exist in a single file > > +* Tabs are not permitted > > +* Scope is denoted by indentation of two spaces > > +* Key value pairs are denoted by "key: value" > > +* Sequences are denoted by "- " > > +* Scalar values may convert newlines to spaces and preserve blank > > + lines for long description formatting using ">" > > +* Scalar values may escape all reserved characters and preserve > > + newlines by using "|" to denote literal style > > + > > +For additional information on YAML syntax, refer to the specification > > +at http://www.yaml.org/spec/1.2/spec.html > > + > > +YAML DT Binding Format > > +---------------------- > > + > > +The following YAML types are supported in the DT binding format: > > + > > Based on my comment above, I recommend: > [R] binding-format: 1 > > > +* [R] id: unique identifier in property form (e.g. skel-device) > > + > > +* [R] title: title of the binding > > + > > +* [O] maintainer: sequence of maintainers > > + [R] name: name and email of maintainer or mailing list in RFC822 > > + form. > > + > > +* [O] description: full description of the binding > > + > > +* [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. I've made an attempt at this in v2. There's some ugly fall-out I haven't decided the best way to handle. That is, I can show a allowable compatible strings including a specific, generic type syntax using C-like expressions. However, showing deprecated compatible requires a special key. I'll be interested if anybody can suggestion something cleaner. There's definitely a trade-off in folding compatibles into properties > > > > +* [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" I modified this a bit to be "string", "int", "array", "phandle", and "empty". I find "empty" to be useful for those properties and a validator will find that useful to validate those boolean type property switches it encounters i.e. skip constraint checking > [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. Got them, but Pantelis' C syntax suggestion for constraints seemed popular and flexible so I went with that initially, please let me know what you think of that. > > Any other constraint is expressed in free-form English text Yes, I believe the description field can hold this information until bindings are fully converted with constraint info in the C-syntax (if we stick with that). > I would recommend adding these to this binding schema doc, but > not requiring them on the first conversion pass of the docs. Sounds good. > 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. Agreed! > > +* [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. Added in v2, thanks. > > > +Note: [R] and [O] denote required and optional fields, respectively. > > I'd put this note before the format description. Done, thanks. > > -- 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. > > -- -- To unsubscribe from this list: send the line "unsubscribe devicetree-spec" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
