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

[Grant Likely]

On Mon, Mar 1, 2010 at 5:13 PM, Stephen Neuendorffer
<stephen.neuendorffer at xilinx.com> wrote:
>> >> The main problem is that it doesn't fit the use cases I need to solve.
>> >>  I need to start with a 'stock' or 'vanilla' tree, and then add into
>> >> it board details.  ie. lay down a generic MPC5200 tree (include a .dts
>> >> file), and then fill it in with i2c and spi devices.  Or include the
>> >> .dts file generated by the XIlinx FPGA toolchain, and then populate it
>> >> with board details.  Sequential operations within the tree doesn't do
>> >> anything to support this use case because the board level fixups will
>> >> be applied all over the tree.
>> >
>> > Aside: I always pictured this the other way round, where the DTS for an
>> > FPGA design includes the DTS for the board.  Then again, as long as they
>> > are independent, it probably doesn't matter.
>>
>> Heh, interesting.  Yeah, I suppose it could be done that way too.  The
>> /include/ directive works pretty much anywhere in the input file, so a
>> file could either lay down a structure and then include a modifer, or
>> include a structure and then modify it.  I was thinking in terms of
>> the board file including the FPGA file because it matches the pattern
>> for say an SoC where there would be a common SoC .dts file and all the
>> boards using that SoC would include it.
>
> Yeah, but in FPGA, the board is likely to be more stable than the FPGA design... :)
> Or maybe 'some' FPGA designs are that way and others are not.

Ah, but even the board file has to change depending on the FPGA
design, and nodes will move around depending on the FPGA internal bus
structure, but I understand what you're saying.  This is why being
able to redefine labelled nodes is a critical feature.  For instance,
the following isn't actually very useful because it assumes knowledge
of the exact location of the i2c bus node:

/ {
        plb at 0 {
                ranges;
                i2c at c0000000 {
                        #address-cells = <1>;
                        #size-cells = <1>;
                        reg = <0xc0000000 0x1000>;
                };
        };
};

/ {
        plb at 0 {
                i2c at c0000000 {
                        rtc at 0 {
                               reg = <0>;
                        };
                        eeprom at 1 {
                               reg = <1>;
                        };
                };
        };
};

However, the following is really useful because the xilinx toolchain
already generates the device labels, and the i2c node can move without
breaking the board devices:

/ {
        plb at 0 {
                ranges;
                i2c-bus-0: i2c at c0000000 {
                        #address-cells = <1>;
                        #size-cells = <1>;
                        reg = <0xc0000000 0x1000>;
                };
        };
};

&i2c-bus-0 {
        rtc at 0 {
                reg = <0>;
        };
        eeprom at 1 {
               reg = <1>;
        };
};

And this way the Platform Studio toolchain doesn't need to be taught
anything about the board layout.  A board file could look something
like this:

/include/ "fpga-design-file.dts"
&i2c-bus-0 {
        rtc at 0 {
                reg = <0>;
        };
        eeprom at 1 {
               reg = <1>;
        };
};

Now, if we're talking about Xilinx eval boards, I can see the argument
for having a stock file like ml507.dts, and then a project .dts file
might look something like this:

/include/ "fpga-design-file.dts"
/* Map between FPGA device names and ML507 board file labels by
applying the ml507 labels to the nodes from the FPGA file */
ml507-i2c-bus-0: &fpga-i2c-bus-0 { };
ml507-i2c-bus-1: &fpga-i2c-bus-1 { };
/include/ "ml507.dts"

This needs new syntax of course, but you get the idea, and it doesn't
require teaching the FPGA toochain all kinds of details about the
board or project files.

> Yes... I think this should just be allowed... or at the very least I don't see a
> reason to make this an error...  It does occur to me that it might be useful to
> explicitly note the 'extension' of a previous node, which asserts that it *must*
> exist.  i.e.
>
> foo {
>        bar + {
>                bar = 3;
>        }
> }
>
> Here it is explicitly clear that bar is an incomplete definition?

hmmm... I don't think I like this so much, and I don't yet see a use
case where this is really a required feature.

g.