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

[John Williams]

On Sun, Feb 21, 2010 at 2:13 AM, Grant Likely <grant.likely at secretlab.ca> wrote:
> 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?

So the "commands" are interpreted at DTS compile time right?  They
have no representation in the DTB?

How about support for adding nodes, such as MTD partitions as child
nodes of a flash device and so on?

Does inclusion happen only at the root?  If so is it meaningful to
have multiple includes in a single dts?

Again with the flash partition example, it might be usefiul to include
a partitional table .dtsi insidethe flash device node.

Seems overall like a useful functionality, we tend to create tools to
tweak the DTS based upon preferences that cannot be expressed to or
known by the device tree generator, their needs would be mostly served
by what you are proposing I think.

John