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

[Grant Likely]

Okay, I'm going to reach way into the past here and reopen an old argument...

Here's a link to the original conversation:

http://www.mail-archive.com/devicetree-discuss@ozlabs.org/msg00161.html

On Tue, Sep 30, 2008 at 8:46 PM, David Gibson
<david at gibson.dropbear.id.au> wrote:
> On Tue, Sep 30, 2008 at 08:55:37AM -0600, Grant Likely wrote:
>> On Fri, Sep 26, 2008 at 03:25:47PM -0500, Jon Loeliger wrote:
>> > From: Jon Loeliger <jdl at freescale.com>
>> >
>> > Signed-off-by: Jon Loeliger <jdl at freescale.com>
>> > ---
>> >  Documentation/manual.txt |  500 ++++++++++++++++++++++++++++++++++++++++++----
>> >  1 files changed, 463 insertions(+), 37 deletions(-)

[snip Jon's new language proposal]

>> I'm not convinced about the approach of interleaving the executable and
>> data syntaxes.  The whole design of the existing syntax is to represent
>> the data structure.  Adding additional syntax to define executable
>> elements doesn't feel right to me.  I think many people will find the
>> resulting file structure to be confusing.

[Snip the rest of my comments]

> The current device tree description is purely declarative, but this
> proposal would make it a rather odd hybrid of declarative and
> imperative components.  I do think this could be confusing,
> particularly to device tree newcomers who may not realise which
> components are compile time evaluated and which go into the output
> tree.  I had in mind a rather more functional-programming style for
> macros/computed properties to ameliorate this.

[snip the rest of David's comments]

Now that I've had about a year and a half to simmer about it, I think
I have a counter proposal on a dts syntax extension.

First, I should state the problems I'm trying to solve.  I have two
use cases that interest me:

1) Multiple boards that use the same SoC.
Right now each dts file carries around the full dts definition, even
though 95% of it is 'stock' description of the soc.  For example,
arch/powerpc/boot/dts/*5200* and arch/powerpc/boot/dts/*8349*.  I want
a way to put all the common description into an SoC dts file, and then
be able to tailor it (add nodes, change properties, etc) for the
specific board.

2) FPGA designs
The Xilinx FPGA toolchain will generate a dts file to describe a
PowerPC or Microblaze FPGA design.  However, the generated file is
usually not complete.  Properties need to be modified (ie. console
device or kernel command line) and additional devices need to be added
(devices hanging off the i2c, mdio and spi busses, gpio connections).
The tool doesn't have a way to tailor the device tree generation, and
the FPGA toolchain doesn't know about board level details.  I want a
way for the developer to write a board-level .dts file that "wraps" or
includes the generated file so that it doesn't need to be modified by
hand.

I also have some design goals for the proposed solution.  First, I
want to avoid design a new programming language.  If we need full
programmatic generation of device trees, there are plenty of general
purpose languages that can do the job.  I already know of two existing
device tree generators; I wrote a prototype generator written in
Python, and the Michal wrote the Xilinx dts generator using TCL.  I
don't want users to have to learn a new language, and I don't want it
to be more complex than is needed to solve the specific use cases.  As
such, I've got no loops, no macros, and no conditionals.

The model that I'm using to approach the problem is to add syntax for
including .dts files (exactly how Jon proposed) and syntax for going
back after the tree is parsed and changing things.  I'm not an expert
on syntax, so I'm open to changes in the details, but this is what I'm
thinking.  Add the following directives to the syntax:

/include/ Include a file
/cd/ Change the 'working node', accepts a full or relative path to a
node.  Also accepts labels.
/delete-node/ Delete a child node.  Similar to /cd/, accepts a full
path, a relative path, or a label.
/delete-property/ Delete a property from the working node.

So, for example, I might have the following for the pcm030.dts:

/dts-v1/;
/include/ mpc5200.dtsi;  /* dts include file */
/* at this point the basic structure of an mpc5200 board is layed down */

/* Change some properties in the chosen and memory nodes. */
/cd/ /chosen;
linux,stdout-path = &psc1;
/cd/ /memory
reg = <0 0x10000000>;

/* Add some devices to the i2c bus */
/cd/ &i2c1;   /* "i2c1" is a label from mpc5200.dtsi */
rtc at 51 {
        compatible = "nxp,pcf8563";
        reg = <0x51>;
};
eeprom at 52 {
        compatible = "catalyst,24c32";
        reg = <0x52>;
};

/* Remove the first i2c bus because it isn't used */
/delete-node/ &i2c0

/* The watchdog doesn't work, so remove the fsl,has-wdt property */
/cd/ &timer0;
/delete-prop/ fsl,has-wdt;

And that's it.  I think this covers the functionality that I need.
What does everyone think?  Are there other important use cases that I
should also be addressing?

Cheers,
g.