Proposal: new device-tree syntax and semantics for extendinginformation from included dts files

[Stephen Neuendorffer]

> -----Original Message-----
> From: glikely at secretlab.ca [mailto:glikely at secretlab.ca] On Behalf Of Grant Likely
> Sent: Friday, October 15, 2010 12:33 PM
> To: Stephen Neuendorffer
> Cc: David Gibson; John Bonesio; devicetree-discuss at lists.ozlabs.org
> Subject: Re: Proposal: new device-tree syntax and semantics for extendinginformation from included dts
> files
> 
> On Fri, Oct 15, 2010 at 10:10 AM, Stephen Neuendorffer
> <stephen.neuendorffer at xilinx.com> wrote:
> >
> >
> >> -----Original Message-----
> >> From: Grant Likely [mailto:glikely at secretlab.ca] On Behalf Of Grant
> > Likely
> >> Sent: Friday, October 15, 2010 8:19 AM
> >> To: Stephen Neuendorffer
> >> Cc: David Gibson; John Bonesio; devicetree-discuss at lists.ozlabs.org
> >> Subject: Re: Proposal: new device-tree syntax and semantics for
> > extendinginformation from included dts
> >> files
> >>
> >> On Thu, Oct 14, 2010 at 09:38:44AM -0700, Stephen Neuendorffer wrote:
> >> [fixed quoting header]
> >> > On Wed, Oct 13, 2010 5:46 PM, David Gibson wrote:
> >> > > On Wed, Oct 13, 2010 at 04:41:59PM -0700, Stephen Neuendorffer
> > wrote:
> >> > > [snip]
> >> > > > Or better yet, outside of the braces?
> >> [...]
> >> > > >             /remove/ {
> >> > > >                                 serial at 2600 { };
> > // PSC4
> >> > > >
> >> > > >                                 serial at 2800 { };
> > // PSC5
> >> > > >                 };
> >> > >
> >> > > Um.. no.  That makes even less sense in the conceptual framework
> > of a
> >> > > stack of overlays.
> >> >
> >> > Why exactly?  Instead of being a stack of overlays, it seems to me
> > like
> >> > a stack of trees with operators..
> >> > The point is exactly that operators make most sense at the stack of
> >> > trees level and not
> >> > at the individual node level.
> >>
> >> I don't think I'm understanding what you're trying to say.  How do you
> > differentiate "stack of
> >> overlays" and "stack of trees"?
> >>
> >> The reason I don't like this approach is that in many cases many
> >> things will need to be changed by a single overlay, and not all those
> >> changes will be the same operation.  For example, an overlay for a
> >> board could add a bunch of nodes for i2c devices, and at the same time
> >> remove an unused spi bus device.
> >
> > So why not have two trees stacked to do the job?
> 
> Umm, isn't the suggestion currently on the table?
> 
> >> The "stack of overlays" conceptual model that we've settled on uses
> >> the concept that subsequent top level trees stack on top of the
> >> preceding tree and can mask out or add/change nodes and properties.
> >> The trees are merged together before going on to the next top level
> >> tree.
> >>
> >> g.
> >>
> >
> > I guess I'm stuck on 'overlay' to me implies '/extend/', so I associate
> > the operations being on trees, not individual nodes.
> > (Although, there's still the tough part about /remove-node/ vs
> > /remove-property/,
> > which might meant that the operations have to be in the trees to
> > distinguish that).
> 
> Yes, the operations would need to be on the individual nodes; whether
> operating on the top level node, or on one of the child nodes.  I
> think some examples are in order....
> 
> Just for argument, I'm going to assume that we define two new
> keywords; /trim-property/ and /trim-node/.  The sole purpose of
> /trim-property/ is to remove a property.  /trim-node/ can be used
> either to either remove or replace a node.  We can still argue about
> the name and the ordering, but the principle remains the same.
> 
> Example 1: using full tree overlay
> ---------
> The following .dts file:
> 
> 	/ {
> 		the-red: red {
> 			rgb = <255 0 0>;
> 		};
> 		the-blue: blue {
> 			rgb = <0 0 255>;
> 			favourite-colour;
> 		};
> 		the-green: green {
> 			rgb = <0 255 0>;
> 		};
> 	};
> 
> 	/ {
> 		blue {
> 			rgb = <0 0 127>;
> 			/trim-property/ favourite-color;
> 		};
> 
> 		/trim-node/ green;
> 
> 		/trim-node/ red {
> 			vendor = "Benjamin Moore"
> 		};
> 	};
> 
> This example uses only one overlay tree.  It removes (trims) the
> 'favourite-colour' property from the blue node.  It removes the
> green node outright, and it replaced the red node.
> 
> Would be collapse to:
> 
> 	/ {
> 		the-red: red {
> 			vendor = "Benjamin Moore"
> 		};
> 		the-blue: blue {
> 			rgb = <0 0 127>;
> 		};
> 	};
> 
> Example 2: using label references
> ---------
> The following .dts file:
> 
> 	/ {
> 		the-red: red {
> 			rgb = <255 0 0>;
> 			firebrick {
> 				rgb = <178 34 34>;
> 			};
> 		};
> 		the-blue: blue {
> 			rgb = <0 0 255>;
> 			favourite-colour;
> 		};
> 		the-green: green {
> 			rgb = <0 255 0>;
> 		};
> 	};
> 
> 	&the-red {
> 		rgb = <127 0 0>;
> 		pink {
> 			rgb = <255 192 203;
> 		};
> 		/trim-node/ firebrick {
> 			ugly-colour;
> 		};
> 	};
> 
> 	/trim-node/ &the-blue;
> 
> 	/trim-node/ &the-green {
> 		shade = "radioactive slime"
> 	};
> 
> This example uses three overlay trees.  The first overlay
> modified the node pointed to by the label "the-red". It changes the
> rgb property, it adds a 'pink' node, and it *replaces* the firebrick
> node (by using both the /trim-node/ keyword and a set of { }  braces).
> 
> The second removes the node pointed to by "the-blue".
> 
> The third replaces the node pointed to by "the-green".
> 
> This tree collapses to:
> 
> 	/ {
> 		the-red: red {
> 			rgb = <127 0 0>;
> 			pink {
> 				rgb = <255 192 203>;
> 			};
> 			firebrick {
> 				ugly-colour;
> 			};
> 		};
> 		green {
> 			shade = "radioactive slime"
> 		};
> 	};
> 
> The /trim-node/ keyword in this model is valid at both the top level
> and inside a node.  Properties can never be defined at the top level,
> so /trim-property/ only makes sense inside a node.

I think this all makes sense.. :)

Maybe I can try to sum up in one sentence:
The mental model is still one of overlays, but if a /trim-*/ attribute is present
before a node or property, then the existing node or property is deleted before 
continuing the overlay.

Steve

This email and any attachments are intended for the sole use of the named recipient(s) and contain(s) confidential information that may be proprietary, privileged or copyrighted under applicable law. If you are not the intended recipient, do not read, copy, or forward this email message or any attachments. Delete this email message and any attachments immediately.