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

[Grant Likely]

On Mon, Feb 22, 2010 at 6:47 PM, David Gibson
<david at gibson.dropbear.id.au> wrote:
> On Sun, Feb 21, 2010 at 11:26:18PM -0700, Grant Likely wrote:
>> That being said, I could see it potentially being valuable to be able
>> to assign an 'invalid' value to a property so that is *must* get
>> overridden before dtc will generate valid output.
>
> That is a very good point.  And it ties in with something I've
> considered before of having some sort of invalid value (which might or
> might not also reserve space in the dtb) to mark things which ought to
> be poked by the bootloader before the tree is passed to the kernel.
> Thoughts have varied on whether that would be purely a documentation
> thing, or whether this would also have a dtb representation so it
> could actually be checked at runtime, but then syntax which allows the
> first would easily allow a later extension to implement the second.
>
> Obviously that's not quite the same thing as here, since clearly it
> would be permissible to generate trees with this sort of invalid
> value, unlike your proposal.  But I don't think that's an
> insurmountable problem.

Right, not quite the same thing, but this easy can easily be deferred.
 I don't actually have any real use cases that depend on this, so I
don't think we need to jump through hoops right now to get it.

>>  I
>> think this might even be able to be handled as part (3) because it
>> doesn't have the '/' processing issue that part (2) has.  For example:
>>
>> instead of:
>> / {
>>         parent at 1234 {
>>                 child at abcd {
>>                         new-property = <0x01234567>;
>>                 };
>>         };
>> };
>>
>> do this:
>>
>> &child-label {
>>         new-property = <0x01234567>;
>> };
>
> And, you know, it turns out '&' is one of the other characters that is
> neither in the current grammar for node names, nor does it appear in
> any device tree I've encountered.  So this syntax is probably ok,
> too.

I specifically chose this syntax because it matches the "property =
&label;" syntax used when assigning a path to a property, so .dts
authors know that a bare "&label" means the full path to a node.  I
think it helps with clarity.

>   Ah.. with the proviso that I think to make sense you could only
> use this form at the top level (so at the top level nodes would be
> introduced by either '/' or '&label' whereas at lowever levels it
> would be by a nodepropname token.

Absolutely.  I also made the assumption that &label is only valid at
the top level.

> [Something to be aware of in the lexical issues that surround node and
> property names is that while IEEE1275 specifies a fairly limited set
> of characters for them, there exist device trees in the wild (in Apple
> and IBM firmwares, mostly) that have characters not in that set.  So
> to be pragmatic we have to allow a pretty wide selection here]

On that note, does the grammer support an escape sequence for
characters with a special meaning?  ie. a \<char> sequence?  Doing so
would sidestep the issue for any exotic trees that come across.

>> > (2) is a bit more problematic syntax-wise.  The fact that paths are
>> > now possible before the node definition raises some lexical issues.
>> > In particular it means the /-surrounded "reserved words" might no
>> > longer be clearly lexically distinct from a node definition (I chose
>> > to make the reserved words surround by / specifically so that that
>> > would be the case).  I suspect this is not a fatal problem, but I'll
>> > need to think about it some more.
>>
>> Actually, as long as I can reference a specific node by label, I don't
>> think I need the ability to pass in the full path.  Label provides the
>> functionality I need.
>
> You know, I was kind of hoping you'd say that :).  After all it is
> still possible to override by explicit path, it's just a bit verbose,
> which is ok if it's not needed particularly often.

:-)  I'm okay with verbose in this case.

>> 4) add a label to an existing node
>> /include/ "base-tree.dtsi"
>> / {
>>         new-label: existing-node { };
>> };
>
> Ah.. yes, hadn't thought of that.  Which reminds me of another
> extension I've had in mind for a while, which I suspect we'll want
> along with this stuff to avoid having some really weird corner cases.
> At present, because of the way things are stored in the internal data
> structures, it's only possible to have a single label on a node or
> property (which a wart already, since you can have any number of
> labels at the same point within a property value).  I think having
> redefinitions would significantly increase the chances that this
> limitation will be a problem in practice.

Okay, this will probably need to be solved then.  It would probably be
a bad idea to encode limitations into the language that are really
just an artifact of the current implementation.  That being said,
while I would use this, I won't be hamstrung by the lack of this
feature in the near term.

>
>> 5) Start from a labeled node instead of the root node:
>> /include/ "base-tree.dtsi"
>> &existing-label {
>>         new-property = <0xabcd>;
>> };
>>
>> Do I have this right?
>
> I think so.

Cool.  Are you able to prototype the new features?  I have no idea
where to start, and I'm pretty buried in the ARM port at the moment.
However, if you implement it then I'll immediately convert all the
MPC5200 .dts files to use it.

Cheers,
g.