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

[Grant Likely]

On Sat, Feb 20, 2010 at 11:30 PM, John Williams
<john.williams at petalogix.com> wrote:
> 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?

Correct.

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

That's what I tried to show in the '/cd/ &i2c1' example above.  Yes,
nodes can be added by 'cd'ing to the parent node, and then using
regular dts syntax to create new children.

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

I don't see any reason why inclusion couldn't happen at any point in
the file.  Includes could also be nested I think (And included file
could include other files)

> 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.

Thanks for the feedback.

g.