[PATCH 8/9 V3] Add documentation for the new DTS language.

[Scott Wood]

Stephen Neuendorffer wrote:
> One thing I've seen in the past is that there is a sequentialization question in this, which becomes
> more apparent once deletion is allowed.
> 
> First off, my assumption is that each node name is always unique in a tree, even when overrides are allowed.
> Otherwise the sub-node and property ordering becomes important.
> 
> foo {
> 	bar = 2;
> 	bar = 3; // Illegal
> } ;
> 
> 
> foo {
> 	bar = 2;
> } 
> foo {
> 	bar = 3; // Legal
> };
> 
> 
> So, essentially, sequentialization of operation is forced by the concatenation of trees.

Hmm, I'd think it would be useful to e.g. include a template and subsequently 
modify it within the same node, rather than a more verbose and error-prone 
process of referencing labels later.

If sequential operations within a tree are supported, I'm not sure that there's 
any remaining need for separate top-level trees -- you could express the same 
thing as top-level property/node redefinitions.

What are the problems with supporting this?

> foo {
> 	bar-label: bar = 2;
> }
> delete(&bar-label);  // Legal.
> foo {
> 	bar-label: bar = 4;  // Legal, even though previously deleted
> }

Is it legal to reuse the label, even though it sort of points to the same spot?

If you don't reuse the label, but bar is redefined, where does bar-label point?

Do all labels to nodes in separate trees that end up referring to the same node 
in the final tree have the same phandle?  Are they interchangeable in subsequent 
delete commands?

> One trick is that the below is problematic, or at least hard to verify statically.
> 
> foo {
> 	delete(&bar-label); // Legal.
> 	delete(bar); // May or may not be Illegal, since don't know what bar-label references
> }

That raises the question of whether it's legal to delete things that aren't 
there.  There may be cases where a dts fragment A doesn't know whether fragment 
B will have defined something, and fragment A wants to make sure it ends up 
undefined one way or another.

> So, to syntax: the sequentialization property may be more syntactically obvious if deletion resembles
> setting a property or node like:
> 
>  ^bar
>  !bar
> or even
>   bar = !;
>   bar !;

What specifically is made more obvious?  Using symbols rather than names seems 
more cryptic to me.

Only the "bar = !" form seems to clearly indicate that, for the purposes of this 
particular tree, you're assigning some special placeholder to bar rather than 
performing an immediate action.  That could just as well be done with something 
like "bar = /delete-prop/".

I'd rather make them actually behave like immediate commands, though.

> Which brings up the question 'undeletion question'.  Can you do:
> 
> d-label: delete(bar);
> delete(&d-label);

I'd say no -- delete operates on data, not commands.

-Scott