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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 




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" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Index of Archives]     [Device Tree Compilter]     [Device Tree Spec]     [Linux Driver Backports]     [Video for Linux]     [Linux USB Devel]     [Linux PCI Devel]     [Linux Audio Users]     [Linux Kernel]     [Linux SCSI]     [XFree86]     [Yosemite Backpacking]
  Powered by Linux