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. > +* "---" 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. > +* [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" [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 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. > +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. > -- -- 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
