Re: [PATCH 1/3] overlay: Documentation for the overlay sugar syntax

[David Gibson <david-xT8FGy+AXnRB3Ne2BGzF6laj5H9X9Tb+@public.gmane.org>]

[-- Attachment #1: Type: text/plain, Size: 3139 bytes --]

On Fri, Jun 23, 2017 at 09:39:27AM +0300, Pantelis Antoniou wrote:
> Hi Frank,
> 
> On Thu, 2017-06-22 at 14:30 -0700, Frank Rowand wrote:
> > Hi David, Pantelis,
> > 
> > On 06/14/17 07:53, Pantelis Antoniou wrote:
> > > There exists a syntactic sugar version of overlays which
> > > make them simpler to write for the trivial case of a single target.
> > > 
> > > Document it in the device tree object internals.
> > > 
> > > Signed-off-by: Pantelis Antoniou <pantelis.antoniou-OWPKS81ov/FWk0Htik3J/w@public.gmane.org>
> > > ---
> > >  Documentation/dt-object-internal.txt | 17 +++++++++++++++++
> > >  1 file changed, 17 insertions(+)
> > > 
> > > diff --git a/Documentation/dt-object-internal.txt b/Documentation/dt-object-internal.txt
> > > index 51d68ab..624aa43 100644
> > > --- a/Documentation/dt-object-internal.txt
> > > +++ b/Documentation/dt-object-internal.txt
> > > @@ -308,3 +308,20 @@ the run time loader must apply an offset to each phandle in every dynamic
> > >  DT object loaded. The __local_fixups__ node records the offset relative to the
> > >  start of every local reference within that property so that the loader can apply
> > >  the offset.
> > > +
> > > +There is an alternative syntax to the expanded form for overlays with phandle
> > > +targets which makes the format similar to the one using in .dtsi include files.
> > > +
> > > +So for the &ocp target example above one can simply write:
> > > +
> > > +/dts-v1/;
> > > +/plugin/;
> > > +&ocp {
> > > +	/* bar peripheral */
> > > +	bar {
> > > +		compatible = "corp,bar";
> > > +		... /* various properties and child nodes */
> > > +	}
> > > +};
> > > +
> > > +The resulting dtb object is identical.
> > 
> > 
> > Ignoring the fact that this file describes the device tree internals
> > instead of the device tree source format -- did we decide that we can
> > deprecate specifying nodes __symbols__,  __overlay__, __fixups__, and
> > __local_fixups__ (any node name beginning with an underscore) in
> > device tree source.  Then at a future date make node names beginning
> > with an underscore an error (maybe with a command line flag to override
> > the error?)?
> > 
> 
> There are a few things in mind about this. In my TODO list is a patch
> that completely deprecates the manual overlay crafting.
> 
> My goal is to have the overlay format be source identical to a .dtsi
> file that usually is included when crafting the single dtb blob we're
> booting with. That is a format that most are familiar with.
> 
> For that to work, we need to handle transformations of the form
> /foo -> <&/foo> -> runtime phandle insertion of <&/foo> if it doesn't
> work.
> 
> This patch is a prerequisite, and we can take it from there. 

The information looks useful, but this is definitely the wrong place
for it.  The file describes internals and the source format is exactly
the opposite of that.

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]