dtsi vs dts files, where to better understand this

[David Gibson]

On Wed, Mar 21, 2012 at 02:50:09PM -0600, John Linn wrote:
> > -----Original Message-----
> > From: Stephen Warren [mailto:swarren at wwwdotorg.org]
> > Sent: Wednesday, March 21, 2012 1:37 PM
> > To: John Linn
> > Cc: devicetree-discuss at lists.ozlabs.org
> > Subject: Re: dtsi vs dts files, where to better understand this
> > 
> > On 03/21/2012 12:36 PM, John Linn wrote:
> > > Hi,
> > >
> > > I've done some digging and not found any info, maybe I looked in the
> > > wrong places.
> > >
> > > I'm trying to better understand how the dtsi file works with the dts
> > > file and what can go in each file.
> > 
> > The basic idea is that what's inside the SoC is identical across all
> > boards using that SoC. This information is put into the .dtsi file so
> > it
> > can be included by the .dts file for any boards using the SoC.
> > 
> > Anything that's board-specific goes into the board's individual .dts
> > file. This might be new nodes to e.g. define which chips are connected
> > to an I2C bus hosted by the SoC, and much more.
> > 
> > Where properties existing in both, the most recent value in parsing
> > order overrides any earlier values. So for example, if the .dtsi file
> > said that 'status = "disabled"' for a particular HW module, the board
> > .dts could later override it by saying 'status = "okay"' within the
> > same
> > node.
> > 
> > One other factor: Something like an SDHCI controller may have
> > properties
> > that are defined by the SoC (e.g. compatible, reg, interrupts), and
> > properties that are defined by the board (e.g. the GPIO ID to use for
> > CD, WP, etc.). Just set the relevant properties in the .dtsi and .dts
> > files and they'll get merged together to form the final device tree.
> > 
> > Was that what you were looking for?
> 
> That was very helpful.  I was hoping there were details written
> somewhere I had missed.  My apologies if I'm just not getting it yet :)
> 
> It's not clear to me how the hierarchy is maintained across both files
> such as an i2c controller would be in the dtsi, while the i2c eeprom on
> the bus is in the board file.
> 
> Do I have to duplicate the i2c controller (and the bus it's on also) in
> the board file? It's not clear how smart the merge is.
> 
> The examples in the 3.3 tree don't seem that clear to me yet.

The model used by dtc for this is a "stack of overlays".  Once the
/include/s are processed you effectively have one big dts file with
several partial trees specified one after another.  The first one
always starts at /, the later ones can start at / but more likely
start at a subtree of the first tree, specified by a path or a label.

dtc then starts with the first tree and lays the later trees over it
in order.  If the same property is specified in a later tree, it
replaces the value from an earlier tree.  If the same node is
specified, its properties and subnodes are merged into the existing
version.

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson