[RFC PATCH v2 0/3] DT binding documents using text markup

[RFC PATCH v2 0/3] DT binding documents using text markup

[Matt Porter]

Changes since v1:
	* Add dt binding format version
	* Treat compatible strings as another property
	* Required, optional, deprecated now a property field
	* Add property type field
	* Add property constraint field using C syntax for constraints
	* Move binding references to a top level inherits sequence
	* Dropped eeprom and phy examples. Example bindings are now only
	  the spi-slave binding and the skeleton device binding which
	  inherits the spi-slave binding.
	* Added notes field to capture any notes on properties
	* Update DT format docs to match new format.
	* Add language about use of YAML core binding
	* Refer to defined YAML sequences/keys consistently as such, remove
	  all vague reference to types and tags.

TODO:
	* reach agreement on format of sequences/keys
		* need a flexible constraint syntax. this is only described
		  in examples but needs a specific description in the format
		  document.
		* determine if compatibles can be handled generically in the
		  property sequence or are better handled in their own specific
		  compatible sequence
		* compatibles as properties have the ugliness of how to
		  handle deprecated strings, for now this is a "deprecated"
		  key that contains a C-syntax expression of all deprecated
		  strings.
	* simple binding doc validator
	* simple checkpatch.pl dts compatible string validator against yaml
	  binding doc compatible property constraints
	* update dtdocgen.py to process inherited bindings and current
	  sequence/key format.

---

During the Device Tree microconference at Linux Plumbers 2015, we had
a short discussion about how to improve DT Binding Documentation. A
number of issues were raised (again, as these things have been
discussed in the past) including:

	* Inconsistency between binding documents due to prose text
	  format.
	* Inability to reliably machine read bindings for mass update
          or search.
        * Bit rot of bindings as new conventions are agreed upon but
	  only new bindings are changed.

When the topic of needing the bindings in a rigid format was raised,
there was general head nodding that this was needed. It was noted that
this has been discussed many times before and nothing has been done.

My proposed solution to the problem is to convert all DT bindings
a rigid text markup format. In choosing a text markup language my
requirements were:

	1) Human readable
	2) Well documented
	3) Easy to translate to other data formats
	4) Well supported by tools and libraries

After looking at a number of markup options, YAML stood out as the
one that meets all of these requirements. The YAML syntax is adopted
in many projects specifically because of the high level of readability.
A comprehensive spec is at http://www.yaml.org/spec/1.2/spec.html.
There's a number of tools to convert between YAML and other popular
data formats such as JSON and XML. XML was cited by Behan Webster
during the microconference as an important data format as the type
of developers that may produce comprehensive DTS Binding validation
tools will want to use XML. Every major scripting language has a
high level binding to the low level libyaml C library to facilitate
handling of YAML data files.

This series is broken up into three parts:

1) The documentation defining the YAML DT binding format
2) A conversion of the generic SPI slave binding
2) A skeleton device binding example illustrating use of this format
   and inheriting the generic SPI slave binding properties.

As a proof of concept of what can be done with a proper machine
readable DT binding source file, there's a simple markdown document
generator at https://github.com/konsulko/dtgendoc. Also, to see
actual output from the generator, the generated markdown from those
bindings is viewable at https://github.com/konsulko/dtgendoc/wiki
(Note: this is not updated yet for v2, see TODO list)

There's a lot of other possibilities for validation tools using
only the data we have today in the bindings. In addition, Frank
Rowand covered some DT debug techniques that would benefit from
the binding documentation being 100% reliably searchable.

-Matt

Matt Porter (3):
  Documentation: dt-bindings: add documentation on new DT binding format
  Documentation: dt-bindings: spi: add generic YAML SPI slave binding
  Documentation: dt-bindings: add example DT binding document

 .../devicetree/bindings/dt-binding-format.txt      | 105 ++++++++++++++++
 Documentation/devicetree/bindings/skeleton.yaml    | 138 +++++++++++++++++++++
 .../devicetree/bindings/spi/spi-slave.yaml         | 108 ++++++++++++++++
 3 files changed, 351 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/dt-binding-format.txt
 create mode 100644 Documentation/devicetree/bindings/skeleton.yaml
 create mode 100644 Documentation/devicetree/bindings/spi/spi-slave.yaml

-- 
2.5.1

[RFC PATCH v2 1/3] 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 <mporter-OWPKS81ov/FWk0Htik3J/w@public.gmane.org>
---
 .../devicetree/bindings/dt-binding-format.txt      | 105 +++++++++++++++++++++
 1 file changed, 105 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..3763487
--- /dev/null
+++ b/Documentation/devicetree/bindings/dt-binding-format.txt
@@ -0,0 +1,105 @@
+--------------------------
+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 four 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 DT binding format is based on the YAML Core schema defined in the
+specification. The following YAML sequences and keys are supported in
+the DT binding format:
+
+[Note: [R] and [O] denote required and optional sequences/keys,respectively]
+
+* [R] version: DT binding format version. Currently 1.
+
+* [R] id: unique identifier in property form (e.g. skel-device)
+
+* [R] title: title of the binding
+
+* [R] 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] inherits: sequence of inherited bindings
+      [R] id: unique identifier of inherited binding
+
+* [R] properties: sequence of properties
+      [R] name: name of property surrounded in double quotes
+      [R} category: category of property. One of "required",
+                    "optional", or "deprecated".
+      [R] type: type of property. One of "string", "int", "empty",
+                "phandle", or "array".
+      [O] constraint: constraint expression using C syntax
+      [O] deprecated: C syntax expression of deprecated compatible
+                      strings.
+      [O] description: description of the property
+
+* [O] notes: Any additional notes about properties in this binding.
+
+* [O] 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
+
+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.5.1

[RFC PATCH v2 2/3] Documentation: dt-bindings: spi: add generic YAML SPI slave binding

[Matt Porter]

Convert the SPI slave portion of the spi-bus.txt binding to the
standard YAML DT binding format.

Signed-off-by: Matt Porter <mporter-OWPKS81ov/FWk0Htik3J/w@public.gmane.org>
---
 .../devicetree/bindings/spi/spi-slave.yaml         | 108 +++++++++++++++++++++
 1 file changed, 108 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/spi/spi-slave.yaml

diff --git a/Documentation/devicetree/bindings/spi/spi-slave.yaml b/Documentation/devicetree/bindings/spi/spi-slave.yaml
new file mode 100644
index 0000000..8447bb9
--- /dev/null
+++ b/Documentation/devicetree/bindings/spi/spi-slave.yaml
@@ -0,0 +1,108 @@
+%YAML 1.2
+---
+version: 1
+
+id: spi-slave
+
+title: SPI Slave Devices
+
+maintainer:
+    -   name: Mark Brown <broonie-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
+
+description: >
+    SPI (Serial Peripheral Interface) slave bus devices are children of
+    of a SPI master bus device.
+properties:
+    -   name: "reg"
+        category: required
+        type: int
+        description: chip select address of device
+
+    -   name: "compatible"
+        category: required
+        type: string
+        description: compatible strings
+
+    -   name: "spi-max-frequency"
+        category: required
+        type: int
+        description: Maximum SPI clocking speed of device in Hz
+
+    -   name: "spi-cpol"
+        category: optional
+        type: empty
+        description: >
+            Empty property indicating device requires
+            inverse clock polarity (CPOL) mode
+
+    -   name: "spi-cpha"
+        category: optional
+        type: empty
+        description: >
+            Empty property indicating device requires
+            shifted clock phase (CPHA) mode
+
+    -   name: "spi-cs-high"
+        category: optional
+        type: empty
+        description: >
+            Empty property indicating device requires
+            chip select active high
+
+    -   name: "spi-3wire"
+        category: optional
+        type: empty
+        description: >
+            Empty property indicating device requires
+            3-wire mode.
+
+    -   name: "spi-lsb-first"
+        category: optional
+        type: empty
+        description: >
+            Empty property indicating device requires
+            LSB first mode.
+
+    -   name: "spi-tx-bus-width"
+        category: optional
+        type: int
+        constraint: 1 || 2 || 4
+        description: >
+            The bus width(number of data wires) that
+            used for MOSI. Defaults to 1 if not present.
+
+    -   name: "spi-rx-bus-width"
+        category: optional
+        type: int
+        constraint: 1 || 2 || 4
+        description: >
+            The bus width(number of data wires) that
+            used for MISO. Defaults to 1 if not present.
+
+notes: >
+    Some SPI controllers and devices support Dual and Quad SPI transfer mode.
+    It allows data in the SPI system to be transferred in 2 wires(DUAL) or
+    4 wires(QUAD).
+    Now the value that spi-tx-bus-width and spi-rx-bus-width can receive is
+    only 1(SINGLE), 2(DUAL) and 4(QUAD). Dual/Quad mode is not allowed when
+    3-wire mode is used.
+    If a gpio chipselect is used for the SPI slave the gpio number will be
+    passed via the SPI master node cs-gpios property.
+
+examples:
+    -   dts: |
+            spi@f00 {
+                ...
+                ethernet-switch@0 {
+                    compatible = "micrel,ks8995m";
+                    spi-max-frequency = <1000000>;
+                    reg = <0>;
+                };
+
+                codec@1 {
+                    compatible = "ti,tlv320aic26";
+                    spi-max-frequency = <100000>;
+                    reg = <1>;
+                };
+            };
+...
-- 
2.5.1

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

[RFC PATCH v2 3/3] Documentation: dt-bindings: add example DT binding document

[Matt Porter]

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-OWPKS81ov/FWk0Htik3J/w@public.gmane.org>
---
 Documentation/devicetree/bindings/skeleton.yaml | 138 ++++++++++++++++++++++++
 1 file changed, 138 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..d7a27cb
--- /dev/null
+++ b/Documentation/devicetree/bindings/skeleton.yaml
@@ -0,0 +1,138 @@
+%YAML 1.2
+---
+version: 1
+
+id: skel-device
+
+title: Skeleton Device
+
+maintainer:
+    -   name: Skeleton Person <skel-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.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.
+
+# This binding inherits property characteristics from the generic
+# spi-slave binding
+
+inherits:
+    -   id: spi-slave
+
+properties:
+
+# The compatible property is a reserved name. The type is always "string"
+# and should not be repeated device binding.
+
+    -   name: "compatible"
+        constraint: |
+            "skel,sk11" || "faux,fx11" , BASE("skel,sk11")
+        description: FX11 is a clone of the original SK11 device
+
+# The reg property is a reserved name. The type is always "int" and
+# should not be repeated in a device binding. Constraints are defined
+# only in the context of the parent node's address, size, and ranges
+# cells. The description is inherited from the spi-slave binding.
+
+    -   name: "reg"
+
+# spi-max-frequency needs the device-specific constraint to be supplied
+
+    -   name: "spi-max-frequency"
+        constraint: |
+            if (compatible == "skel,sk11") c <= 10000000 else c <= 1000000
+
+# This property overrides the generic binding description with
+# a device specific description in order to mention the chip's
+# h/w cfg strapping pins.
+
+    -   name: "spi-cs-high"
+        description: >
+            Set if skeleton device configuration pins are set for chip
+            select polarity high
+
+# Device specific properties don't inherit characteristic from a generic
+# binding so category, type, constraint, and description must be specified
+# if needed.
+
+    -   name: "skel,deprecated1"
+        category: deprecated
+        type: int
+        constraint: |
+            (c >= 100000) && (c <= 200000)
+        description: >
+            First of two deprecated properties.
+
+# There are no constraints for properties of empty type
+
+    -   name: "skel,deprecated2"
+        category: deprecated
+        type: empty
+        description: >
+            Second of two deprecated properties.
+
+# This example could be auto-generated rather than explicitly included
+# in the yaml source.
+
+example:
+    -   dts: |
+            sk11@0 {
+                compatible = "skel,sk11";
+                reg = <0>;
+                spi-max-frequency = <1000000>;
+                spi-cs-high;
+            };
+...
+
+---
+version: 1
+
+id: skel-mini
+
+title: Skeleton Mini Device
+
+maintainer:
+    -   name: Rogue Developer <rogue-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
+
+description: >
+    The Skeleton Mini Device binding represents the SK47x series devices
+    produced by the Skeleton Corporation.
+
+properties:
+    -   name: "compatible"
+        category: required
+        constraint: |
+            "skel,sk472" || skel,sk473" || "skel,sk474" , BASE("skel,sk472")
+        deprecated: "skel,sk47x"
+        description: >
+            SK472 is the original part in the family. SK473/4 are later releases
+            with minor register changes.
+
+    -   name: "reg"
+        category: required
+        description: Address and size of Skeleton Mini register range.
+
+    -   name: "skel,sync-mode"
+        category: optional
+        type: empty
+        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", "skel,sk472";
+                reg = <0xdead0000 0x100>;
+                skel,sync-mode;
+            };
+        description: >
+            Demonstrates an SK474 in synchronous mode.
+...
-- 
2.5.1

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

[Rob Herring]

On Mon, Sep 21, 2015 at 10:59 PM, Matt Porter <mporter-OWPKS81ov/FWk0Htik3J/w@public.gmane.org> wrote:
> Documentation explaining the syntax and format of the YAML-based DT binding
> documentation.
>
> Signed-off-by: Matt Porter <mporter-OWPKS81ov/FWk0Htik3J/w@public.gmane.org>
> ---
>  .../devicetree/bindings/dt-binding-format.txt      | 105 +++++++++++++++++++++
>  1 file changed, 105 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..3763487
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/dt-binding-format.txt
> @@ -0,0 +1,105 @@
> +--------------------------
> +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 four spaces
> +* Key value pairs are denoted by "key: value"
> +* Sequences are denoted by "-"

I'm going to pick on sequences...

> +* 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 DT binding format is based on the YAML Core schema defined in the
> +specification. The following YAML sequences and keys are supported in
> +the DT binding format:
> +
> +[Note: [R] and [O] denote required and optional sequences/keys,respectively]
> +
> +* [R] version: DT binding format version. Currently 1.
> +
> +* [R] id: unique identifier in property form (e.g. skel-device)
> +
> +* [R] title: title of the binding
> +
> +* [R] 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] inherits: sequence of inherited bindings
> +      [R] id: unique identifier of inherited binding
> +
> +* [R] properties: sequence of properties

I've been playing around with this some. Just looking at what pyyaml
does doing yaml.dump(yaml.load()) makes me think we need to change the
syntax some. What comes out is much less readable than the input:

-   category: required
    description: Address and size of Skeleton Mini register range.
    name: reg
-   category: optional
    description: Enable synchronous transfer mode
    name: skel,sync-mode
    type: empty

I suppose this could be fixed by changing the sorting in pyyaml
somehow to keep "name" first, but why? And perhaps we don't care about
generating yaml right now, but we could in the future.
This is also making me wondering if we are using "-" in the right way
looking at other examples. Most examples I've found use sequences for
values, not key/value pairs.

If I change "properties" sub nodes to be property names instead of "-
name", the output remains readable:

properties:
    compatible:
        constraint: '"skel,sk11" || "faux,fx11" , BASE("skel,sk11")

            '
        description: FX11 is a clone of the original SK11 device
    reg: null
    skel,deprecated1:
        category: deprecated
        constraint: '(c >= 100000) && (c <= 200000)

            '
        description: 'First of two deprecated properties.

            '
        type: int


Similarly, we'd want to align other uses of sequences. Nesting of
sequences is also a bit awkward IMO compared to just adding
indentation.

This is where we need the YAML expert...

Rob

Re: [RFC PATCH v2 3/3] Documentation: dt-bindings: add example DT binding document

[Rob Herring]

On 09/21/2015 10:59 PM, Matt Porter 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-OWPKS81ov/FWk0Htik3J/w@public.gmane.org>
> ---
>  Documentation/devicetree/bindings/skeleton.yaml | 138 ++++++++++++++++++++++++
>  1 file changed, 138 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..d7a27cb
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/skeleton.yaml
> @@ -0,0 +1,138 @@
> +%YAML 1.2
> +---
> +version: 1
> +
> +id: skel-device
> +
> +title: Skeleton Device
> +
> +maintainer:
> +    -   name: Skeleton Person <skel-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>

Do we need more than just name and more than 1 maintainer? With both
we'd need to figure out the grouping.

> +
> +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.
> +
> +# This binding inherits property characteristics from the generic
> +# spi-slave binding
> +
> +inherits:
> +    -   id: spi-slave

I would drop "id" here and inherits is just an array of values.

> +
> +properties:
> +
> +# The compatible property is a reserved name. The type is always "string"
> +# and should not be repeated device binding.

I think we should just always be explicit with type.

> +
> +    -   name: "compatible"
> +        constraint: |
> +            "skel,sk11" || "faux,fx11" , BASE("skel,sk11")
> +        description: FX11 is a clone of the original SK11 device
> +
> +# The reg property is a reserved name. The type is always "int" and
> +# should not be repeated in a device binding. Constraints are defined
> +# only in the context of the parent node's address, size, and ranges
> +# cells. The description is inherited from the spi-slave binding.

Is this a general statement or specific to spi-slave? On I2C devices, we
know the constraints. It may be a single value or a list of strapped values.

> +
> +    -   name: "reg"

We also need to know how many entries and what each entry is. We will
only ever be able to validate the count except cases we have
constraints, but those should only have 1 entry I think. So I would just
add "count" which can be a list of valid counts.


> +
> +# spi-max-frequency needs the device-specific constraint to be supplied
> +
> +    -   name: "spi-max-frequency"
> +        constraint: |
> +            if (compatible == "skel,sk11") c <= 10000000 else c <= 1000000
> +
> +# This property overrides the generic binding description with
> +# a device specific description in order to mention the chip's
> +# h/w cfg strapping pins.
> +
> +    -   name: "spi-cs-high"
> +        description: >
> +            Set if skeleton device configuration pins are set for chip
> +            select polarity high
> +
> +# Device specific properties don't inherit characteristic from a generic
> +# binding so category, type, constraint, and description must be specified
> +# if needed.
> +
> +    -   name: "skel,deprecated1"
> +        category: deprecated
> +        type: int
> +        constraint: |
> +            (c >= 100000) && (c <= 200000)
> +        description: >
> +            First of two deprecated properties.
> +
> +# There are no constraints for properties of empty type
> +
> +    -   name: "skel,deprecated2"
> +        category: deprecated
> +        type: empty
> +        description: >
> +            Second of two deprecated properties.
> +
> +# This example could be auto-generated rather than explicitly included
> +# in the yaml source.
> +
> +example:
> +    -   dts: |
> +            sk11@0 {
> +                compatible = "skel,sk11";
> +                reg = <0>;
> +                spi-max-frequency = <1000000>;
> +                spi-cs-high;
> +            };
> +...
> +
> +---
> +version: 1
> +
> +id: skel-mini
> +
> +title: Skeleton Mini Device
> +
> +maintainer:
> +    -   name: Rogue Developer <rogue-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> +
> +description: >
> +    The Skeleton Mini Device binding represents the SK47x series devices
> +    produced by the Skeleton Corporation.
> +
> +properties:
> +    -   name: "compatible"
> +        category: required
> +        constraint: |
> +            "skel,sk472" || skel,sk473" || "skel,sk474" , BASE("skel,sk472")
> +        deprecated: "skel,sk47x"
> +        description: >
> +            SK472 is the original part in the family. SK473/4 are later releases
> +            with minor register changes.
> +
> +    -   name: "reg"
> +        category: required
> +        description: Address and size of Skeleton Mini register range.
> +
> +    -   name: "skel,sync-mode"
> +        category: optional
> +        type: empty
> +        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", "skel,sk472";
> +                reg = <0xdead0000 0x100>;
> +                skel,sync-mode;
> +            };
> +        description: >
> +            Demonstrates an SK474 in synchronous mode.
> +...
>