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]

 




Hi Rob,

> On Aug 28, 2015, at 17:53 , Rob Herring <robherring2@xxxxxxxxx> wrote:
> 
> 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>
> 

I would like something that looks like a C expression.

For instance
- constraint: spi-max-frequency >= 1000000 && spi-max-frequency < 10000000

>> +
>> +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.
> 

How about we make sure we parse the example in the binding always, so
that we verify that it does much what the binding states?

> Rob

Regards

— Pantelis

--
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