From mboxrd@z Thu Jan 1 00:00:00 1970 From: Rob Herring Subject: Re: [RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document Date: Fri, 28 Aug 2015 09:53:06 -0500 Message-ID: References: <1440739433-6799-1-git-send-email-mporter@konsulko.com> <1440739433-6799-3-git-send-email-mporter@konsulko.com> Mime-Version: 1.0 Return-path: DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc:content-type; bh=c/Joet34a1V3CfLEXdPw2xm9rCk+8RvoqaZeloU8PSE=; b=0vZ0DAay9ircAMStYtKkzwwUza5P+5CjU6+U8WWRfVwrgeVTgfpYEmVgzULKWGc+i1 2Xtx/Xljef0V56/QwBNSCILa9VVxSVggqFoZT1jwkEfkUTFIoCO9BMTrN4wWZ5Zw6UCl Rtjtu7ZZOebkLkfiVyTv54Cr0k0Dqm13L3hXzY8zPYxbTrHfl8rD3LU4YvmjqX6Kjcm7 sXWf20vqF9YRpiRgZNe5+vOEPIQo5/o78daJMzQtk4cGtEjJkMv/kSCsNrbHloGc0YYI Q0VoGWCzWF1tPYiafVATg3X8GrvBmsFFOJh9Qfl0Nf5Ptn57ksFNMX8VqvFiWv+GbY/o T6XQ== In-Reply-To: <1440739433-6799-3-git-send-email-mporter-OWPKS81ov/FWk0Htik3J/w@public.gmane.org> Sender: devicetree-spec-owner-u79uwXL29TY76Z2rM5mHXA@public.gmane.org List-ID: Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit To: Matt Porter Cc: Devicetree List , Devicetree Spec List , Grant Likely , Frank Rowand , Rob Herring , Mark Rutland , Pantelis Antoniou , Behan Webster On Fri, Aug 28, 2015 at 12:23 AM, 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 > --- > 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 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: > + > +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