On Fri, Aug 28, 2015 at 12:23 AM, Matt Porter <mporter@xxxxxxxxxxxx> 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@xxxxxxxxxxxx>
> ---
> Documentation/devicetree/bindings/skeleton.yaml | 98 +++++++++++++++++++++++++
> 1 file changed, 98 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..175965f
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/skeleton.yaml
> @@ -0,0 +1,98 @@
> +%YAML 1.2
> +---
> +id: skel-device
> +
> +title: Skeleton Device
> +
> +maintainer:
> + - name: Skeleton Person <skel@xxxxxxxxxx>
We'd want to tie this into get_maintainers.pl obviously.
> +
> +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.
> +
> +compatible:
> + - name: "skel,sk11"
> + - name: "faux,fx11"
Is this an OR or AND? We need both.
The complicated case is "one of {specific names} followed by {generic name}."
> + description: A clone of the original sk11 device
> +
> +required:
> + - name: "reg"
We definitely need type info from the start.
> + description: chip select address of skeleton device
> + reference: spi-slave
I would like to not have to list properties if the inherited binding
lists it. The problem is we need to say how many cells and the order
(not a problem here, but for mmio devices).
Perhaps we can list the reference at the top level for the node
instead of for every property.
> + - name: "spi-max-frequency"
> + description: >
> + Maximum SPI clocking speed of skeleton device in Hz, must be
> + 1000000
> + reference: spi-slave
Rather than listing the property and having constraint in description,
perhaps we could add constraints like this:
- spi-max-frequency-range: 1000000 1000000
Or groups of constraints:
- spi-max-frequency-constraints:
range: 1000000 1000000
some-other-constraint: <value>
> +
> +optional:
> + - name: "spi-cs-high"
> + description: >
> + Set if skeleton device configuration straps are set for chip
> + select polarity high
> + reference: spi-slave
> +
> +deprecated:
> + - name: "skel,deprecated1"
> + description: >
> + First of two deprecated properties.
> + - name: "skel,deprecated2"
> + description: >
> + Second of two deprecated properties.
> +
> +example:
> + - dts: |
> + sk11@0 {
> + compatible = "skel,sk11";
> + reg = <0>;
> + spi-max-frequency = <1000000>;
> + spi-cs-high;
> + };
At least in this example, we could generate it. Examples are nice, but
we have dts files full of examples already. I get a fair number of
"fix the example" patches, so maybe we should eliminate the simple
ones.
Rob
--
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
