The usage of compatible 'simple-bus'

The usage of compatible 'simple-bus'

[Li Yang]

SGkgYWxsLA0KDQpJIGdvdCBhbiBhc3N1bXB0aW9uIGZyb20gdGhlIGV4aXN0aW5nIGRldmljZSB0
cmVlcyB0aGF0IGhhdmluZyAnc2ltcGxlLWJ1cycgaW4gdGhlIGNvbXBhdGlibGUgcHJvcGVydHkg
b2YgYSBub2RlIG1lYW5zIHRoYXQgYWxsIGNoaWxkIG5vZGVzIHNob3VsZCBiZSBhZGRlZCBhcyBv
Zl9wbGF0Zm9ybV9kZXZpY2UgaW4gcGxhdGZvcm0gaW5pdGlhbGl6YXRpb24gcGhhc2UuICBObyBt
YXR0ZXIgaXQgcmVwcmVzZW50cyBhIGJ1cyBpbiBjb21tb24gc2Vuc2Ugb3Igbm90LiAgSXMgdGhp
cyB0cnVseSB0aGUgY2FzZT8gIFNoYWxsIHdlIGRvY3VtZW50IHRoaXM/DQoNCi0gTGVvDQo=

Re: The usage of compatible 'simple-bus'

[Scott Wood]

On Mon, Jan 05, 2009 at 06:27:39PM +0800, Li Yang wrote:
> I got an assumption from the existing device trees that having
> 'simple-bus' in the compatible property of a node means that all child
> nodes should be added as of_platform_device in platform initialization
> phase.  No matter it represents a bus in common sense or not.  Is this
> truly the case? 

Yes, simple-bus indicates that the children can be driven standalone from
any knowledge of the parent bus.

> Shall we document this?

It is documented in ePAPR.

-Scott

Re: The usage of compatible 'simple-bus'

[David Gibson]

On Mon, Jan 05, 2009 at 01:20:53PM -0600, Scott Wood wrote:
> On Mon, Jan 05, 2009 at 06:27:39PM +0800, Li Yang wrote:
> > I got an assumption from the existing device trees that having
> > 'simple-bus' in the compatible property of a node means that all child
> > nodes should be added as of_platform_device in platform initialization
> > phase.  No matter it represents a bus in common sense or not.  Is this
> > truly the case? 
> 
> Yes, simple-bus indicates that the children can be driven standalone from
> any knowledge of the parent bus.

Erm, well, sort of.  Strictly it indicates that the only way to locate
the child devices of this bus is by using the address information in
the device tree - there's no way to dynamically probe the bus.

The fact that this causes of_platform_devices to be instantiated is a
Linux implementation specific detail (and one we might change in
future).

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

RE: The usage of compatible 'simple-bus'

[Li Yang]

> -----Original Message-----
> From:=20
> devicetree-discuss-bounces+leoli=3Dfreescale.com@ozlabs.org=20
> [mailto:devicetree-discuss-bounces+leoli=3Dfreescale.com@ozlabs.
> org] On Behalf Of David Gibson
> Sent: Tuesday, January 06, 2009 9:43 AM
> To: Wood Scott-B07421
> Cc: linuxppc-dev@ozlabs.org; Li Yang-R58472;=20
> devicetree-discuss@ozlabs.org
> Subject: Re: The usage of compatible 'simple-bus'
>=20
> On Mon, Jan 05, 2009 at 01:20:53PM -0600, Scott Wood wrote:
> > On Mon, Jan 05, 2009 at 06:27:39PM +0800, Li Yang wrote:
> > > I got an assumption from the existing device trees that having=20
> > > 'simple-bus' in the compatible property of a node means that all=20
> > > child nodes should be added as of_platform_device in platform=20
> > > initialization phase.  No matter it represents a bus in=20
> common sense=20
> > > or not.  Is this truly the case?
> >=20
> > Yes, simple-bus indicates that the children can be driven=20
> standalone=20
> > from any knowledge of the parent bus.
>=20
> Erm, well, sort of.  Strictly it indicates that the only way=20
> to locate the child devices of this bus is by using the=20
> address information in the device tree - there's no way to=20
> dynamically probe the bus.

So if I understand correctly, "simple-bus" is intended to be used for
true buses.

>=20
> The fact that this causes of_platform_devices to be=20
> instantiated is a Linux implementation specific detail (and=20
> one we might change in future).

Here we have a common case for SoC that part of a device has its
separate driver besides the driver for the main feature of the whole
device.  The resources used by the sub-device is usually part of the
resources of the parent device.  So it makes sense to put the node of
sub-device beneathe the node of main device.  Shall we have a convention
to mark such devices in device tree so that the sub-device can be
scanned and probed as a standalone of_platform_device?

If "simple-bus" may cause confusion to do this job as it's not a bus
actually, I propose to use "has-subdevice".

- Leo

Re: The usage of compatible 'simple-bus'

[Grant Likely]

On Mon, Jan 5, 2009 at 10:46 PM, Li Yang <LeoLi@freescale.com> wrote:
>> -----Original Message-----
>> From:
>> devicetree-discuss-bounces+leoli=freescale.com@ozlabs.org
>> [mailto:devicetree-discuss-bounces+leoli=freescale.com@ozlabs.
>> org] On Behalf Of David Gibson
>> Sent: Tuesday, January 06, 2009 9:43 AM
>> To: Wood Scott-B07421
>> Cc: linuxppc-dev@ozlabs.org; Li Yang-R58472;
>> devicetree-discuss@ozlabs.org
>> Subject: Re: The usage of compatible 'simple-bus'
>>
>> On Mon, Jan 05, 2009 at 01:20:53PM -0600, Scott Wood wrote:
>> > On Mon, Jan 05, 2009 at 06:27:39PM +0800, Li Yang wrote:
>> > > I got an assumption from the existing device trees that having
>> > > 'simple-bus' in the compatible property of a node means that all
>> > > child nodes should be added as of_platform_device in platform
>> > > initialization phase.  No matter it represents a bus in
>> common sense
>> > > or not.  Is this truly the case?
>> >
>> > Yes, simple-bus indicates that the children can be driven
>> standalone
>> > from any knowledge of the parent bus.
>>
>> Erm, well, sort of.  Strictly it indicates that the only way
>> to locate the child devices of this bus is by using the
>> address information in the device tree - there's no way to
>> dynamically probe the bus.
>
> So if I understand correctly, "simple-bus" is intended to be used for
> true buses.
>
>>
>> The fact that this causes of_platform_devices to be
>> instantiated is a Linux implementation specific detail (and
>> one we might change in future).
>
> Here we have a common case for SoC that part of a device has its
> separate driver besides the driver for the main feature of the whole
> device.  The resources used by the sub-device is usually part of the
> resources of the parent device.  So it makes sense to put the node of
> sub-device beneathe the node of main device.

First, repeat the following to yourself 10 times: "The device tree
describes the hardware; not the way Linux uses it".

Avoid thinking about how the of_platform bus works for a minute and
ask yourself this question.  If you're talking about several devices
which share the same set of resources; then are they really separate
devices, or is it a single device with more than one channel or slice?

If it is really just a single device, then I would avoid adding a
separate compatible value to each sub node and define the device
binding against the parent node compatible value and specify in the
binding documentation that the node needs to have one or more child
nodes to describe the channels.

If it is really multiple devices which share limited resources; then
it is fine for each sub node to have a compatible property; and the
binding documentation for that sub node must state that the parent
node describes the shared resources for the set.

In your specific case, you happen to have 2 drivers; but that is a
Linux internal implementation detail.  The driver that binds against
the parent node can just as easily instantiate the sub-device devices
instead of using the of_platform infrastructure.  In fact, it may even
be better if it does so; but this is not the kind of information that
you try to describe in the device tree.

Once again; describe the hardware; not the way Linux uses it.

> Shall we have a convention
> to mark such devices in device tree so that the sub-device can be
> scanned and probed as a standalone of_platform_device?

No.  Instead, document the binding; what properties it expects and
what it means.  So; if you want to give the child nodes a 'compatible'
value, then document what describes.  If you give the parent node a
compatible value, then in the same way document what it means.  Only
use simple-bus if it really is a simple bus translation to a child
node.

Then, adapt Linux to do what it must to bind a driver to the device.
One option is for the parent node driver to instantiate the child node
device.  Another is to explicitly add the parent node compatible
property to the list of probable of_platform busses in the board setup
code.

> If "simple-bus" may cause confusion to do this job as it's not a bus
> actually, I propose to use "has-subdevice".

It seems to me like the meaning of 'has-subdevice' will end up being
very open to interpretation and thus result in confusion and odd
workarounds in the future.  I don't think this is a very good idea.

g.

-- 
Grant Likely, B.Sc., P.Eng.
Secret Lab Technologies Ltd.

Re: The usage of compatible 'simple-bus'

[Li Yang]

On Tue, Jan 6, 2009 at 2:35 PM, Grant Likely <grant.likely@secretlab.ca> wrote:
> On Mon, Jan 5, 2009 at 10:46 PM, Li Yang <LeoLi@freescale.com> wrote:
>>> -----Original Message-----
>>> From:
>>> devicetree-discuss-bounces+leoli=freescale.com@ozlabs.org
>>> [mailto:devicetree-discuss-bounces+leoli=freescale.com@ozlabs.
>>> org] On Behalf Of David Gibson
>>> Sent: Tuesday, January 06, 2009 9:43 AM
>>> To: Wood Scott-B07421
>>> Cc: linuxppc-dev@ozlabs.org; Li Yang-R58472;
>>> devicetree-discuss@ozlabs.org
>>> Subject: Re: The usage of compatible 'simple-bus'
>>>
>>> On Mon, Jan 05, 2009 at 01:20:53PM -0600, Scott Wood wrote:
>>> > On Mon, Jan 05, 2009 at 06:27:39PM +0800, Li Yang wrote:
>>> > > I got an assumption from the existing device trees that having
>>> > > 'simple-bus' in the compatible property of a node means that all
>>> > > child nodes should be added as of_platform_device in platform
>>> > > initialization phase.  No matter it represents a bus in
>>> common sense
>>> > > or not.  Is this truly the case?
>>> >
>>> > Yes, simple-bus indicates that the children can be driven
>>> standalone
>>> > from any knowledge of the parent bus.
>>>
>>> Erm, well, sort of.  Strictly it indicates that the only way
>>> to locate the child devices of this bus is by using the
>>> address information in the device tree - there's no way to
>>> dynamically probe the bus.
>>
>> So if I understand correctly, "simple-bus" is intended to be used for
>> true buses.
>>
>>>
>>> The fact that this causes of_platform_devices to be
>>> instantiated is a Linux implementation specific detail (and
>>> one we might change in future).
>>
>> Here we have a common case for SoC that part of a device has its
>> separate driver besides the driver for the main feature of the whole
>> device.  The resources used by the sub-device is usually part of the
>> resources of the parent device.  So it makes sense to put the node of
>> sub-device beneathe the node of main device.
>
> First, repeat the following to yourself 10 times: "The device tree
> describes the hardware; not the way Linux uses it".
>
> Avoid thinking about how the of_platform bus works for a minute and
> ask yourself this question.  If you're talking about several devices
> which share the same set of resources; then are they really separate
> devices, or is it a single device with more than one channel or slice?

For off-chip devices you can easily separate devices by it's physical
appearance, different chips or cards are explicitly separate devices.
But for on-chip devices one can easily get two different answers if
they are looked in different ways.  The example at hand is TSEC
Ethernet controller and the MDIO part of it.  Logically it is one
controller and MDIO is one of its functions.  But they work rather
independently and can be regarded as different controllers.

- Leo

Re: The usage of compatible 'simple-bus'

[David Gibson]

On Tue, Jan 06, 2009 at 01:46:21PM +0800, Li Yang wrote:
> > -----Original Message-----
> > From: 
> > devicetree-discuss-bounces+leoli=freescale.com@ozlabs.org 
> > [mailto:devicetree-discuss-bounces+leoli=freescale.com@ozlabs.
> > org] On Behalf Of David Gibson
> > Sent: Tuesday, January 06, 2009 9:43 AM
> > To: Wood Scott-B07421
> > Cc: linuxppc-dev@ozlabs.org; Li Yang-R58472; 
> > devicetree-discuss@ozlabs.org
> > Subject: Re: The usage of compatible 'simple-bus'
> > 
> > On Mon, Jan 05, 2009 at 01:20:53PM -0600, Scott Wood wrote:
> > > On Mon, Jan 05, 2009 at 06:27:39PM +0800, Li Yang wrote:
> > > > I got an assumption from the existing device trees that having 
> > > > 'simple-bus' in the compatible property of a node means that all 
> > > > child nodes should be added as of_platform_device in platform 
> > > > initialization phase.  No matter it represents a bus in 
> > common sense 
> > > > or not.  Is this truly the case?
> > > 
> > > Yes, simple-bus indicates that the children can be driven 
> > standalone 
> > > from any knowledge of the parent bus.
> > 
> > Erm, well, sort of.  Strictly it indicates that the only way 
> > to locate the child devices of this bus is by using the 
> > address information in the device tree - there's no way to 
> > dynamically probe the bus.
> 
> So if I understand correctly, "simple-bus" is intended to be used for
> true buses.

Generally, yes, although there may be some situations where it's
appropriate for other things.  So, for example, in some cases it's
used (correctly) for compound devices .  I don't think this particular
case is a sensible situation for it, though.

> > The fact that this causes of_platform_devices to be 
> > instantiated is a Linux implementation specific detail (and 
> > one we might change in future).
> 
> Here we have a common case for SoC that part of a device has its
> separate driver besides the driver for the main feature of the whole
> device.  The resources used by the sub-device is usually part of the
> resources of the parent device.  So it makes sense to put the node of
> sub-device beneathe the node of main device.  Shall we have a convention
> to mark such devices in device tree so that the sub-device can be
> scanned and probed as a standalone of_platform_device?
> 
> If "simple-bus" may cause confusion to do this job as it's not a bus
> actually, I propose to use "has-subdevice".

As Grant says, you're thinking about what drivers will do with things
rather than what the actual hardware setup is, which is what the
device tree should describe.

I see two sensible options for this situation:
	- Move the MDIO node to outside the gianfar MAC node.  I think
this is already done on some boards with gianfar?
	- Explicitly add the gianfar device to the list of things to
scan for of_platform subdevices.

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

Re: The usage of compatible 'simple-bus'

[Grant Likely]

On Tue, Jan 6, 2009 at 7:00 PM, David Gibson
<david@gibson.dropbear.id.au> wrote:
> As Grant says, you're thinking about what drivers will do with things
> rather than what the actual hardware setup is, which is what the
> device tree should describe.
>
> I see two sensible options for this situation:
>        - Move the MDIO node to outside the gianfar MAC node.  I think
> this is already done on some boards with gianfar?

mpc5200 FEC is another example of this.

>        - Explicitly add the gianfar device to the list of things to
> scan for of_platform subdevices.

Ack.  I 100% agree.

g.

-- 
Grant Likely, B.Sc., P.Eng.
Secret Lab Technologies Ltd.

Re: The usage of compatible 'simple-bus'

[Li Yang]

On Wed, Jan 7, 2009 at 10:00 AM, David Gibson
<david@gibson.dropbear.id.au> wrote:
> On Tue, Jan 06, 2009 at 01:46:21PM +0800, Li Yang wrote:
>> > -----Original Message-----
>> > From:
>> > devicetree-discuss-bounces+leoli=freescale.com@ozlabs.org
>> > [mailto:devicetree-discuss-bounces+leoli=freescale.com@ozlabs.
>> > org] On Behalf Of David Gibson
>> > Sent: Tuesday, January 06, 2009 9:43 AM
>> > To: Wood Scott-B07421
>> > Cc: linuxppc-dev@ozlabs.org; Li Yang-R58472;
>> > devicetree-discuss@ozlabs.org
>> > Subject: Re: The usage of compatible 'simple-bus'
>> >
>> > On Mon, Jan 05, 2009 at 01:20:53PM -0600, Scott Wood wrote:
>> > > On Mon, Jan 05, 2009 at 06:27:39PM +0800, Li Yang wrote:
>> > > > I got an assumption from the existing device trees that having
>> > > > 'simple-bus' in the compatible property of a node means that all
>> > > > child nodes should be added as of_platform_device in platform
>> > > > initialization phase.  No matter it represents a bus in
>> > common sense
>> > > > or not.  Is this truly the case?
>> > >
>> > > Yes, simple-bus indicates that the children can be driven
>> > standalone
>> > > from any knowledge of the parent bus.
>> >
>> > Erm, well, sort of.  Strictly it indicates that the only way
>> > to locate the child devices of this bus is by using the
>> > address information in the device tree - there's no way to
>> > dynamically probe the bus.
>>
>> So if I understand correctly, "simple-bus" is intended to be used for
>> true buses.
>
> Generally, yes, although there may be some situations where it's
> appropriate for other things.  So, for example, in some cases it's
> used (correctly) for compound devices .  I don't think this particular
> case is a sensible situation for it, though.
>
>> > The fact that this causes of_platform_devices to be
>> > instantiated is a Linux implementation specific detail (and
>> > one we might change in future).
>>
>> Here we have a common case for SoC that part of a device has its
>> separate driver besides the driver for the main feature of the whole
>> device.  The resources used by the sub-device is usually part of the
>> resources of the parent device.  So it makes sense to put the node of
>> sub-device beneathe the node of main device.  Shall we have a convention
>> to mark such devices in device tree so that the sub-device can be
>> scanned and probed as a standalone of_platform_device?
>>
>> If "simple-bus" may cause confusion to do this job as it's not a bus
>> actually, I propose to use "has-subdevice".
>
> As Grant says, you're thinking about what drivers will do with things
> rather than what the actual hardware setup is, which is what the
> device tree should describe.
>
> I see two sensible options for this situation:
>        - Move the MDIO node to outside the gianfar MAC node.  I think
> this is already done on some boards with gianfar?

Yes, we can use good old way.  But as Scott has moved the MDIO into
the gianfar node on MPC8313, maybe it's a better way to describe the
relationship of the two parts.

>        - Explicitly add the gianfar device to the list of things to
> scan for of_platform subdevices.

I'm not against this solution.  However, the situation is kind of
common for SoC.  So I was just wondering if we can get to a new
convention in device tree than maintain a list in the code.  It will
be easier to figure the situation out by just reading the dts than
combining with the code.

- Leo

Re: The usage of compatible 'simple-bus'

[Scott Wood]

On Wed, Jan 07, 2009 at 11:51:12AM +0800, Li Yang wrote:
> > I see two sensible options for this situation:
> >        - Move the MDIO node to outside the gianfar MAC node.  I think
> > this is already done on some boards with gianfar?
> 
> Yes, we can use good old way.  But as Scott has moved the MDIO into
> the gianfar node on MPC8313, maybe it's a better way to describe the
> relationship of the two parts.

Ah, right, that was to reflect the clock domain situation so that someday
when I get time to do device power management the kernel can know that by
shutting down ethernet@25000 it's also shutting down mdio@24520, which is
also used by ethernet@26000.

Adding simple-bus was a bit of a hack, but it preserves the existing
binding whereby mdio sits under a simple-bus.  Ideally, the mdio node
would simply be a container for PHY nodes, and would simply be a part of
gianfar rather than a separate entity.

-Scott