Re: [RFC PATCH 1/5] Documentation: dt-bindings: add documentation on new DT binding format

[David Gibson]

On Fri, Aug 28, 2015 at 01:23:49AM -0400, Matt Porter wrote:
> Documentation explaining the syntax and format of the YAML-based DT binding
> documentation.

Sorry I've taken so long to comment; I've had sickness and a backlog
of day-job work to deal with.

> Signed-off-by: Matt Porter 
> ---
>  .../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 000..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

I've read through this.  At least tentatively, YAML seems like a
pretty good choice to me.  It seems to have a pretty good balance
between human readability and machine parsability.


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

I think the recommended indentation should be increased.  At just 2
spaces it's easy to lose track of indentation level if you scroll down
a page.

8 would match the kernel code style, but might get cumbersome since I
think our YAML structures will probably be more deeply nested in
practice than code blocks generally should be.

So, I'd suggest 4.

> +* 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:

I find the wording above really confusing.  Mentioning "types" makes
me thinnk you're talking about the actual YAML tags, which usually
have typing information, but actually you seem to be talking about the
expected members of the top level YAML mapping.

Speaking of YAML tags, we really should specify the YAML schema we're
using here.  From the rest of the stuff, I'm assuming it's the "Core"
schema described in section 10.3 of the YAML spec.  That seems a
reasonable first choice to me, although eventually we may want to
define our own YAML schema.

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

So, when thinking about DT validation, I like to make a distinction
between the binding's "key" and its requirements.  By the "key"
(because I haven't thought of a better term) I mean the thing that
tells you this binding is in play.  From a validator's point of view,
given a DT 

Re: [RFC PATCH 1/5] Documentation: dt-bindings: add documentation on new DT binding format

[Matt Porter]

On Sun, Aug 30, 2015 at 03:04:33PM -0700, Frank Rowand wrote:
> On 8/27/2015 10:23 PM, Matt Porter wrote:
> > Documentation explaining the syntax and format of the YAML-based DT binding
> > documentation.
> > 
> > Signed-off-by: Matt Porter 
> > ---
> >  .../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 000..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
> > +* "---" 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:
> > +
> > +* [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
> > +
> > +* [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
> > +
> > +* [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
> 
> I commented in reply to patch 0 that we should think through how
> this structure will support adding new features as the next step
> after converting existing bindings.
> 
> The specific case I started thinking about was the distinction between
> required, optional, required-if, and optional-if.  A property might
> be required in all cases, optional in all cases, required in some
> specified cases, and/or optional in some specified cases.  So a
> property could be both "required-if" 

[RFC PATCH 1/5] Documentation: dt-bindings: add documentation on new DT binding format

[Matt Porter]

Documentation explaining the syntax and format of the YAML-based DT binding
documentation.

Signed-off-by: Matt Porter mpor...@konsulko.com
---
 .../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 000..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
+* --- 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:
+
+* [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
+
+* [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
+
+* [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
+
+Note: [R] and [O] denote required and optional fields, respectively.
+
+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.
-- 
2.1.4

--
To unsubscribe from this list: send the line unsubscribe devicetree-spec in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html