Re: Discussion on SOC device tree bindings

Re: Discussion on SOC device tree bindings

[Grant Likely]

Bah!  I forgot to CC the mailing list on this email; so this is a resend.

On 1/13/07, Grant Likely <grant.likely@secretlab.ca> wrote:
> A number of us spent a bit of time discussing this Thursday and today
> on IRC; here is a summary for everyone else's benefit.
>
> Most of this conversation centered around the mpc5200, but there are
> implications for other soc's too.
>
> The issue discussed was whether or not the description of the
> compatible field in
> Documentation/powerpc/mpc5200-device-tree-bindings.txt is the best way
> to describe the hardware.  At the moment, it recommends something like
> "mpc5200b-psc-uart\0mpc52xx-psc-uart" to describe a PSC in UART mode.
> This isn't the first time these issues have come up; but it is the
> first time we've discussed it in any depth.
>
> The problems with this are:
> 1. it's a bit premature to define mpc52xx when there are only 2
> devices in the family and the primary reason they are named
> differently is that the 5200b has bug fixes that are not 100%
> backwards compatible with the 5200.
> 2. It still doesn't give enough information; ie. it doesn't give any
> information about silicon revision for a particular board.  ie. If
> there is a bug in M08A but not in M62C, then driver doesn't get that
> from the current scheme.
>
> When I wrote the document, I based it on the assumption that the
> driver would have all the information it needs based on the compatible
> property (which is naive).  'compatible' is supposed to be a
> description of the interface; not a full description of the hardware
> revision.
>
> It also makes the assumption that names matter.  They don't.  If we
> call an fec on the 5200 "mpc5200-fec", it will always be
> "mpc5200-fec", even if it shows up on a mpc5233 or a mpc5400, or any
> other chip.  All that matters is that two incompatible device are not
> named the same thing.  So, using 52xx-* in compatible lists is
> premature as we have no idea how many other 52xx parts will arrive
> using the same device, and a future 52xx could use an incompatible FEC
> that would have to be called something different (because 52xx-fec is
> already taken)
>
> The main value of the bindings document is so we do have a list of
> already assigned device names to be used in the compatible property.
>
> What *is* interesting is to know exactly which silicon version of the
> device it is.  In a perfect world, device drivers shall never need
> this information.  However, if a bug is found in the future, this
> information is needed to enable/disable bug fix code.
>
> It's also interesting to know about extra features and quirks of a
> device.  ie. gpt0 has a watchdog timer feature.  The device interface
> is mostly the same; but probably not different enough to warrant a
> separate device driver.  (things get hazy here; more of an art than
> science to decide whether this information is encoded in 'compatible'
> or with an extra property)  ie. The gpt0 node could have an empty
> property called 'has-wdt'.
>
> So, the following changes are proposed:
> 1. "mpc52xx-*" items will be dropped from the compatible property
> because they are premature.  Unless the 5200B device is incompatible
> with the 5200, then the 5200B will specify "mpc5200b-*\0mpc5200-*".
> (strong recommendation, but not required; if a 5200b board just has
> "mpc5200-*", in most cases it won't cause breakage).
> 2. known quirks/extra features will be reported with additional
> properties to the device.  ie. gpt0 will add a 'has-wdt' empty
> property
> 3. an /soc5200/model property will be added for last resort
> determination of chip version (The soc5200 node is called 'builtin' on
> the efika)
> 4. most of the 5200 drivers will be changed to bind on 5200-* instead
> of 52xx-*.  Drivers will not bind on 5200b-* unless truly incompatible
> with the 5200.
> 5. new 5200-ish devices, like a fictional 5300 or a 5437 (random
> numbers out of my head) will use something like
> "mpc5300-psc-uart\0mpc5200-psc-uart" (strong recommendation)
> 6. A /soc5200/model property shall be added to describe the chip type
> (ie model="mpc5200b").
> 7. A /soc5200/version property shall be added to describe the silicon
> revision (ie. version="M62C")
>
> Note: the presence of the soc node is important, but I don't think the
> name of it matters much.  It should be sufficient to define it as the
> parent of the device node.  What matters is that device drivers know
> how to reach it.
>
> Implications:
> 1. Encoding /soc/model and /soc/version is probably a good idea for
> *all* SOCs.  If everyone agrees, then I'll add it to
> booting_without_of.txt.
> 2. It means the Efika compatible properties match without fixups.  I'm
> still not happy with using "mpc5200-xxx" instead of "mpc5200-psc-xxx"
> for PSC functions because it means there is a collision between the
> two different SPI devices.  However, if names don't matter then I
> shouldn't get my nickers in a knot over this one.  It's more important
> to document what is done.
>
> Comments?
> g.
>
> --
> Grant Likely, B.Sc. P.Eng.
> Secret Lab Technologies Ltd.
> grant.likely@secretlab.ca
> (403) 399-0195
>


-- 
Grant Likely, B.Sc. P.Eng.
Secret Lab Technologies Ltd.
grant.likely@secretlab.ca
(403) 399-0195

Re: Discussion on SOC device tree bindings

[Sascha Hauer]

Hi,

On Sun, Jan 14, 2007 at 03:29:24PM -0700, Grant Likely wrote:
> >
> > So, the following changes are proposed:
> > 1. "mpc52xx-*" items will be dropped from the compatible property
> > because they are premature.  Unless the 5200B device is incompatible
> > with the 5200, then the 5200B will specify "mpc5200b-*\0mpc5200-*".
> > (strong recommendation, but not required; if a 5200b board just has
> > "mpc5200-*", in most cases it won't cause breakage).

How about always specifying the exact name and only the exact name
in the device tree, i.e. mpc5200-fec on mpc5200, mpc5200b-fec on
mpc5200b and so on. This way the driver can decide whether or not it's
compatible to a device and we can be sure not to overlook any
incompatibilities. We could even decide in later kernel versions that
two devices are too incompatible and split the driver into two.

> > 2. known quirks/extra features will be reported with additional
> > properties to the device.  ie. gpt0 will add a 'has-wdt' empty
> > property
> > 3. an /soc5200/model property will be added for last resort
> > determination of chip version (The soc5200 node is called 'builtin' on
> > the efika)
> > 4. most of the 5200 drivers will be changed to bind on 5200-* instead
> > of 52xx-*.  Drivers will not bind on 5200b-* unless truly incompatible
> > with the 5200.

There may be incompatibilities between 5200 and 5200b which we simply did
not discover yet. 


  Sascha

-- 
 Dipl.-Ing. Sascha Hauer | http://www.pengutronix.de
  Pengutronix - Linux Solutions for Science and Industry
    Handelsregister: Amtsgericht Hildesheim, HRA 2686
      Hannoversche Str. 2, 31134 Hildesheim, Germany
    Phone: +49-5121-206917-0 |  Fax: +49-5121-206917-9

Re: Discussion on SOC device tree bindings

[Grant Likely]

On 1/15/07, Sascha Hauer <s.hauer@pengutronix.de> wrote:
> Hi,
>
> On Sun, Jan 14, 2007 at 03:29:24PM -0700, Grant Likely wrote:
> > >
> > > So, the following changes are proposed:
> > > 1. "mpc52xx-*" items will be dropped from the compatible property
> > > because they are premature.  Unless the 5200B device is incompatible
> > > with the 5200, then the 5200B will specify "mpc5200b-*\0mpc5200-*".
> > > (strong recommendation, but not required; if a 5200b board just has
> > > "mpc5200-*", in most cases it won't cause breakage).
>
> How about always specifying the exact name and only the exact name
> in the device tree, i.e. mpc5200-fec on mpc5200, mpc5200b-fec on
> mpc5200b and so on. This way the driver can decide whether or not it's
> compatible to a device and we can be sure not to overlook any
> incompatibilities. We could even decide in later kernel versions that
> two devices are too incompatible and split the driver into two.

That's the point I started from, but if you go down that path it still
doesn't provide the right amount of information.  What if one silicon
version of the 5200b has a problem?  For that kind of stuff we need to
know the exact version of the chip.

The compatible property has a different purpose.  It's purpose is to
describe the interfaces; not the implementations of the interface.  It
is a list from most compatible to least compatible.  So, assuming no
silicon bugs, a chip down the road with the same device on it gets
it's devices supported 'for free' on systems that already support the
5200.  No code changes.  It also means the kernel doesn't have to
maintain the compatibility tables.

If there are too drivers (ie. mpc5200-psc-ac97 and mpc5200b-psc-ac97),
then the most compatible driver should match first.

If there *are* as-yet-unknown silicon bugs; it's a different matter,
but the addition of the model/revision properties on the soc node
gives the OS enough info to enable/disable workarounds.

>
> > > 2. known quirks/extra features will be reported with additional
> > > properties to the device.  ie. gpt0 will add a 'has-wdt' empty
> > > property
> > > 3. an /soc5200/model property will be added for last resort
> > > determination of chip version (The soc5200 node is called 'builtin' on
> > > the efika)
> > > 4. most of the 5200 drivers will be changed to bind on 5200-* instead
> > > of 52xx-*.  Drivers will not bind on 5200b-* unless truly incompatible
> > > with the 5200.
>
> There may be incompatibilities between 5200 and 5200b which we simply did
> not discover yet.

of course, but the driver should have enough info to make good
decisions about when to enable/disable them.

-- 
Grant Likely, B.Sc. P.Eng.
Secret Lab Technologies Ltd.
grant.likely@secretlab.ca
(403) 399-0195

Re: Discussion on SOC device tree bindings

[Segher Boessenkool]

> How about always specifying the exact name and only the exact name
> in the device tree, i.e. mpc5200-fec on mpc5200, mpc5200b-fec on
> mpc5200b and so on.

No :-)

> This way the driver can decide whether or not it's
> compatible to a device

It already can.

> and we can be sure not to overlook any
> incompatibilities. We could even decide in later kernel versions that
> two devices are too incompatible and split the driver into two.

You can already; say you have a driver that will only work
on 5200b, is will match on that, and the "plain" 5200 driver
won't get a chance to grab the device.  You have to match
for the most specific first, of course.

> There may be incompatibilities between 5200 and 5200b which we simply 
> did
> not discover yet.

If that is so, than such a 5200b-specific driver can be
created (possibly just as some special cases in the
existing 5200 driver).

Listing something in the "compatible" property doesn't mean
the device is 100% compatible, just that it's mostly compatible.
Earlier entries in there are "more compatible" ;-)


Segher

Re: Discussion on SOC device tree bindings

[Sascha Hauer]

On Mon, Jan 15, 2007 at 04:42:18PM +0100, Segher Boessenkool wrote:
> 
> If that is so, than such a 5200b-specific driver can be
> created (possibly just as some special cases in the
> existing 5200 driver).
> 
> Listing something in the "compatible" property doesn't mean
> the device is 100% compatible, just that it's mostly compatible.
> Earlier entries in there are "more compatible" ;-)
> 
> 

OK, I see ;)

  Sascha

-- 
 Dipl.-Ing. Sascha Hauer | http://www.pengutronix.de
  Pengutronix - Linux Solutions for Science and Industry
    Handelsregister: Amtsgericht Hildesheim, HRA 2686
      Hannoversche Str. 2, 31134 Hildesheim, Germany
    Phone: +49-5121-206917-0 |  Fax: +49-5121-206917-9

Re: Discussion on SOC device tree bindings

[Grant Likely]

Note: I had forgot to start this thread on the mailing list; but I'm
moving it there now.

On 1/15/07, Matt Sealey <matt@genesi-usa.com> wrote:
> Can someone summarise why we are talking about exposing clock controllers
> for anything more than informational purposes?

Isn't the whole device tree all about "informational purposes?"  :-)

>
> I seem to have missed some mails, had some spam filtered and deleted by
> automation this weekend, and I am not following the general discussion
> so well (from a "I don't understand" standpoint) as it is.
>
> I am not sure from my point of view that it is relevant to expose such
> details in the tree since the information is not useful or changable by
> Linux. What clock controls what device, the cascading down the tree and
> so on doesn't seem to give me any more information than no information
> at all when the clocks are relatively fixed at boot time (Linux should
> not be reconfiguring internal SoC bus clocks)

No, we're not talking about SoC bus clocks.  In fact, we're not
talking about clocks at all.  :-) Shared clock registers just happen
to be a convenient example for the topic we're really talking about.

The thread started with discussion about the 5200 device tree binding
conventions, but has moved to a specific issue.  Now we are talking
about how to deal with shared registers.  ie. There are 2 I2C
controllers on the 5200, but they share one register.  How is that
best represented in the device tree?

Here's the quick summary of the points so far:
1. We all agree that the device tree is about how best to describe the
hardware; not how Linux or anyone else intends to use it.  (ie.
provide as much relevant information as possible without building an
insanely large tree and regardless of whether or not Linux uses the
info.)
2. It is not reasonable to try to describe every chip register in the
device tree
3. It is reasonable to assume that the OS has SoC specific code to
deal with variations in implementation.
4. I think that the general consensus is that the device tree should
have a node for shared SoC registers and a node for each on chip
device.  One will point to the other (phandle?) to indicate which node
device drivers should look to for twiddling the shared bits.
5. The contentious issue is which direction those links should be
constructed.  Does the device node describe where to find it's SoC
parent node and what the device index is?  Or does the SoC node
describe which device nodes it provides shared register service for?
6. Paramount in this discussion is making sure that the device tree is
detailed enough that if any of the above information is missing
(because firmware is never going to have everything we want), the
information can still be determined and filled in.  For example, as
long as we know the processor is a mpc5200b; then the shared register
bindings can be filled in at fixup time.

>
> It may come in useful and this may be a bad example, for ATA drivers
> where I always see the message "assuming 33MHz bus lock for PIO" - rather
> than assume, it would be reported, but is this all that we are discussing
> here or is there something a lot more complicated coming off it that just
> went right over my head?

Cheers,
g.

-- 
Grant Likely, B.Sc. P.Eng.
Secret Lab Technologies Ltd.
grant.likely@secretlab.ca
(403) 399-0195

Re: Discussion on SOC device tree bindings

[Segher Boessenkool]

>> Can someone summarise why we are talking about exposing clock 
>> controllers
>> for anything more than informational purposes?
>
> Isn't the whole device tree all about "informational purposes?"  :-)

It is.

> 1. We all agree that the device tree is about how best to describe the
> hardware; not how Linux or anyone else intends to use it.  (ie.
> provide as much relevant information as possible without building an
> insanely large tree and regardless of whether or not Linux uses the
> info.)

It seems *not* everyone has got this firmly into his/her
head yet.  It is not something people have the "agree"
with at all though; it is just the way it is.

> 4. I think that the general consensus is that the device tree should
> have a node for shared SoC registers and a node for each on chip
> device.  One will point to the other (phandle?) to indicate which node
> device drivers should look to for twiddling the shared bits.

Erm, the way you state this, you're violating (1.) already ;-)

Implicit from the type of SoC control thing, we know what
registers control what devices; the only thing the device
tree needs to express what those devices (from the viewpoint
of the control device) are in the device tree.  i.e., like
you said, there need to be some links set up between the
controlled devices' nodes and the control node.

> 5. The contentious issue is which direction those links should be
> constructed.  Does the device node describe where to find it's SoC
> parent node and what the device index is?  Or does the SoC node
> describe which device nodes it provides shared register service for?
> 6. Paramount in this discussion is making sure that the device tree is
> detailed enough that if any of the above information is missing
> (because firmware is never going to have everything we want), the
> information can still be determined and filled in.  For example, as
> long as we know the processor is a mpc5200b; then the shared register
> bindings can be filled in at fixup time.

Much more importantly, a big consideration is making the
binding so simple and so close to the actual hardware
relations, that it becomes as future-proof as possible.
Requiring properties in many different device nodes that
cannot have those properties required by their own binding,
is not the way to go; having the same information wholly
self-contained in the device node that the binding is all
about, in only one property even, is so obviously a much
cleaner much simpler way to go about it that I don't know,
why the heck are we still talking about this?

We should never violate (1.), period.


Segher

Re: Discussion on SOC device tree bindings

[Benjamin Herrenschmidt]

> The thread started with discussion about the 5200 device tree binding
> conventions, but has moved to a specific issue.  Now we are talking
> about how to deal with shared registers.  ie. There are 2 I2C
> controllers on the 5200, but they share one register.  How is that
> best represented in the device tree?

  .../i2c-core/i2c-bus@0
              /i2c-bus@1

Or something like that. Make one device that encloses them all. Well,
that's of the top of my head, somebod might have a better idea.

Ben.

Re: Discussion on SOC device tree bindings

[Segher Boessenkool]

>> The thread started with discussion about the 5200 device tree binding
>> conventions, but has moved to a specific issue.  Now we are talking
>> about how to deal with shared registers.  ie. There are 2 I2C
>> controllers on the 5200, but they share one register.  How is that
>> best represented in the device tree?
>
>   .../i2c-core/i2c-bus@0
>               /i2c-bus@1

This describes two i2c buses under one i2c controller;
that's not the same thing.  OTOH, I suspect that's
closer to the real situation.  Grant?

> Or something like that. Make one device that encloses them all.

It's the only way to do it, the shared register can be
in the "reg" property for one device node only.


Segher

Re: Discussion on SOC device tree bindings

[Grant Likely]

(Added ML to the CC list)

On 1/15/07, Benjamin Herrenschmidt <benh@kernel.crashing.org> wrote:
> On Mon, 2007-01-15 at 16:37 +0100, Segher Boessenkool wrote:
> > > Same logic with interrupts.
> >
> > Interrupts go from a device to the interrupt controller, here
> > it is the other way around.

> That doesn't matter. The actual direction of the signal doesn't matter.
---snip---
> and at the end of the day it doesn't matter, It's up to Sylvain and Grant do decide
> what they want to do.

Well, I suppose I should stop sitting on the fence on this and
actually give my opinion.  I have to agree with Ben here, I don't
think the direction of the link matters.  One binding can be trivially
generated from the other no matter which way it is done.

I don't think the argument that the data should not be scattered about
in various device nodes holds a whole lot of water.  There is already
precedence for this with the interrupt binding.  I've already stated
that I don't think the signal direction matters, so I don't agree with
the argument that interrupts are different because that are connected
the other way around.

Putting the linkage in the device nodes does not bloat the tree, and
it does not duplicate information.  The device tree is just as
expressive either way around, so typical usage becomes the tie
breaker.  Typical usage is for the device driver to "call" the system
node; therefore put the linkage information in the device node where
it's most easily retrieved when needed.

Looking at the larger scope; we're talking about an SoC here.  While
most of the SoC device drivers don't need to know anything about the
SoC as a whole, the platform code should really know what SoC part it
is on.  SoC designers love to toss in special cases which don't really
slide nicely into our pretty device tree, and the OS almost always
needs chip specific support code to handle it.  I'm inclined to say
that the bindings from device node to shared soc registers may be
*recommended*, but not *required*.  As long as there is some form of
linkage between the soc and device nodes, and as long as the SoC node
describes exactly which SoC it is, then the OS has all the information
it needs to figure out which devices are connected to which bits of
which shared registers (based on register address).  Now, this might
be a bad precedence, but I'm hesitant to go down the path of trying to
describe something in the device tree which is inherent to the SoC
design.

Cheers,
g.

-- 
Grant Likely, B.Sc. P.Eng.
Secret Lab Technologies Ltd.
grant.likely@secretlab.ca
(403) 399-0195

Re: Discussion on SOC device tree bindings

[Segher Boessenkool]

> I don't think the argument that the data should not be scattered about
> in various device nodes holds a whole lot of water.

It's one of the main design principles behind the device
tree at all, how can it _not_ make sense.  If you just put
random pieces of data wherever you feel like putting them
you end up with ACPI instead.

> There is already
> precedence for this with the interrupt binding.

With interrupts it is unavoidable, since you often have cascaded
controllers.

> Putting the linkage in the device nodes does not bloat the tree, and
> it does not duplicate information.  The device tree is just as
> expressive either way around,

Except you have to parse the whole tree to determine the function
of the one controller node.

> so typical usage becomes the tie
> breaker.  Typical usage is for the device driver to "call" the system
> node; therefore put the linkage information in the device node where
> it's most easily retrieved when needed.

You don't normally use the device tree at runtime; typical usage
is to parse it at startup and initialise some internal kernel
data structures from that.  The device tree needs to express the
system in a clear, extensible way; it is not its purpose to "make
things easy" for the Linux kernel (although that can happen as a
side effect).

> Looking at the larger scope; we're talking about an SoC here.  While
> most of the SoC device drivers don't need to know anything about the
> SoC as a whole, the platform code should really know what SoC part it
> is on.  SoC designers love to toss in special cases which don't really
> slide nicely into our pretty device tree, and the OS almost always
> needs chip specific support code to handle it.

Yep.  Which is why IMHO the OF binding shouldn't even try to
model the functionality of such a SoC controller node.  It has
to show what it is that is controlled though.

> I'm inclined to say
> that the bindings from device node to shared soc registers may be
> *recommended*, but not *required*.

If they aren't required, you obviously have some other way to
get that information, so it shouldn't be recommended either.

>   As long as there is some form of
> linkage between the soc and device nodes, and as long as the SoC node
> describes exactly which SoC it is, then the OS has all the information
> it needs to figure out which devices are connected to which bits of
> which shared registers (based on register address).

Yes exactly.  And if we can express all this in a simple
self-contained way, like for example put this all in one
device node, why do something terribly complex and kludgy
instead?

> Now, this might
> be a bad precedence, but I'm hesitant to go down the path of trying to
> describe something in the device tree which is inherent to the SoC
> design.

You shouldn't try to.  Since the "controlled" devices are in
the device tree however, you have to list them in the "controller"
node so you can figure out what is what.


Segher

RE: Discussion on SOC device tree bindings

[Yoder Stuart-B08248]

Back in Grant's original summary of the problem he wrote:
> 4. I think that the general consensus is that the device tree should
> have a node for shared SoC registers and a node for each on chip
> device.  One will point to the other (phandle?) to indicate which node
> device drivers should look to for twiddling the shared bits.
>
> 5. The contentious issue is which direction those links should be
> constructed.  Does the device node describe where to find it's SoC
> parent node and what the device index is?  Or does the SoC node
> describe which device nodes it provides shared register service for?

How about linking in _both_ directions?

-The SOC node describes the shared register with links to the
 the device nodes it is associated with

-The device nodes link to the SOC parent shared register node
(_but_ don't necessarily specify the device index, since that
 could be determined by looking at the SOC node)

Doing both provides flexibility in the way the device tree
is used.   The SOC node in a single place describes the
shared register which conceptually makes sense.  The device
node has a pointer to an affiliated register which exists
outside the device itself.

Stuart Yoder
PowerPC Software Architecture, Freescale

Re: Discussion on SOC device tree bindings

[Grant Likely]

On 1/19/07, Yoder Stuart-B08248 <stuart.yoder@freescale.com> wrote:
>
> Back in Grant's original summary of the problem he wrote:
> >
> > 5. The contentious issue is which direction those links should be
> > constructed.  Does the device node describe where to find it's SoC
> > parent node and what the device index is?  Or does the SoC node
> > describe which device nodes it provides shared register service for?
>
> How about linking in _both_ directions?

I think that's a bad precedence.  Either representation can be
generated from the other.  Linking it in both directions means
duplicate information with no real benefit.

g.

-- 
Grant Likely, B.Sc. P.Eng.
Secret Lab Technologies Ltd.
grant.likely@secretlab.ca
(403) 399-0195

Re: Discussion on SOC device tree bindings

[Segher Boessenkool]

> How about linking in _both_ directions?
>
> -The SOC node describes the shared register with links to the
>  the device nodes it is associated with

This provides all the information you need.

> -The device nodes link to the SOC parent shared register node
> (_but_ don't necessarily specify the device index, since that
>  could be determined by looking at the SOC node)

This information, if handy for the kernel to have, can
be trivially constructed at initialisation time by the
kernel itself.

> Doing both provides flexibility in the way the device tree
> is used.

That flexibility is already there if you describe
everything in the controller node.

> The SOC node in a single place describes the
> shared register which conceptually makes sense.

Exactly.


Segher