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