Refactor booting-without-of.txt

Refactor booting-without-of.txt

[Grant Likely]

Adding the Linux expected device tree bindings to
booting-without-of.txt seems to be getting a little unwieldy.  Plus
with more than one arch using the device tree (powerpc, sparc &
microblaze) the device tree bindings aren't necessarily powerpc only
(the Xilinx devices certainly fall in this category).

Anyone have comments about splitting the expected device tree bindings
out of booting-without-of.txt into a separate directory?

Perhaps something like this; each file contains common bindings for
the type of device and device specific properties:

Documentation/of/
Documentation/of/README - Description of the purpose and layout of
this directory
Documentation/of/net.txt - network device bindings (eth, MDIO, phy, etc)
Documentation/of/serial.txt - serial device bindings
Documentation/of/misc.txt - anything that doesn't fit anywhere else yet.
Documentation/of/soc/* - System on chip stuff that doesn't fit will
into established device types; possibly a separate file for each chip.
Documentation/of/usb.txt - usb blah blah blah
Documentation/of/whatever - you get the picture.

Thoughts?
g.

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

Re: Refactor booting-without-of.txt

[Olof Johansson]

On Mon, Oct 15, 2007 at 10:08:44AM -0600, Grant Likely wrote:
> Adding the Linux expected device tree bindings to
> booting-without-of.txt seems to be getting a little unwieldy.  Plus
> with more than one arch using the device tree (powerpc, sparc &
> microblaze) the device tree bindings aren't necessarily powerpc only
> (the Xilinx devices certainly fall in this category).
> 
> Anyone have comments about splitting the expected device tree bindings
> out of booting-without-of.txt into a separate directory?

The flat device tree is, in spite of what some people would like it to be,
not open firmware, nor is it the same as their bindings. So I think we'd
be doing ourselves a disservice by continuing to associate them together.
All it would take is a rename of the directory, unfortunately i don't
have any suggestions on better names though.

> Perhaps something like this; each file contains common bindings for
> the type of device and device specific properties:
>
> Documentation/of/
> Documentation/of/README - Description of the purpose and layout of
> this directory
> Documentation/of/net.txt - network device bindings (eth, MDIO, phy, etc)
> Documentation/of/serial.txt - serial device bindings
> Documentation/of/misc.txt - anything that doesn't fit anywhere else yet.
> Documentation/of/soc/* - System on chip stuff that doesn't fit will
> into established device types; possibly a separate file for each chip.
> Documentation/of/usb.txt - usb blah blah blah
> Documentation/of/whatever - you get the picture.
> 
> Thoughts?

Looks reasonable. The other way to cut it would be to slice along vendor
boundaries, but I think I like the functional partitioning you suggested
better.


-Olof

Re: Refactor booting-without-of.txt

[Grant Likely]

On 10/15/07, Olof Johansson <olof@lixom.net> wrote:
> On Mon, Oct 15, 2007 at 10:08:44AM -0600, Grant Likely wrote:
> > Adding the Linux expected device tree bindings to
> > booting-without-of.txt seems to be getting a little unwieldy.  Plus
> > with more than one arch using the device tree (powerpc, sparc &
> > microblaze) the device tree bindings aren't necessarily powerpc only
> > (the Xilinx devices certainly fall in this category).
> >
> > Anyone have comments about splitting the expected device tree bindings
> > out of booting-without-of.txt into a separate directory?
>
> The flat device tree is, in spite of what some people would like it to be,
> not open firmware, nor is it the same as their bindings. So I think we'd
> be doing ourselves a disservice by continuing to associate them together.
> All it would take is a rename of the directory, unfortunately i don't
> have any suggestions on better names though.

I think I need to stick with the of prefix.  All the support API in
include/linux/of_* is prefixed with "of_" already, so convention is
established.

How about Documentation/of-device-tree?

>
> > Perhaps something like this; each file contains common bindings for
> > the type of device and device specific properties:
> >
> > Documentation/of/
> > Documentation/of/README - Description of the purpose and layout of
> > this directory
> > Documentation/of/net.txt - network device bindings (eth, MDIO, phy, etc)
> > Documentation/of/serial.txt - serial device bindings
> > Documentation/of/misc.txt - anything that doesn't fit anywhere else yet.
> > Documentation/of/soc/* - System on chip stuff that doesn't fit will
> > into established device types; possibly a separate file for each chip.
> > Documentation/of/usb.txt - usb blah blah blah
> > Documentation/of/whatever - you get the picture.
> >
> > Thoughts?
>
> Looks reasonable. The other way to cut it would be to slice along vendor
> boundaries, but I think I like the functional partitioning you suggested
> better.

I think vendor partitioning makes sense for non-common devices that
don't easily fit into a particular mold (soc glue nodes come to mind).
 Other than that, the functional partitioning
lets us start with defining common property usage for a given device
type and follow up with device specific properties.

Thanks for the feedback,
g.

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

Re: Refactor booting-without-of.txt

[Olof Johansson]

Hi,

On Mon, Oct 15, 2007 at 11:14:44AM -0600, Grant Likely wrote:
> On 10/15/07, Olof Johansson <olof@lixom.net> wrote:
> >
> > The flat device tree is, in spite of what some people would like it to be,
> > not open firmware, nor is it the same as their bindings. So I think we'd
> > be doing ourselves a disservice by continuing to associate them together.
> > All it would take is a rename of the directory, unfortunately i don't
> > have any suggestions on better names though.
> 
> I think I need to stick with the of prefix.  All the support API in
> include/linux/of_* is prefixed with "of_" already, so convention is
> established.
> 
> How about Documentation/of-device-tree?

Sounds good to me, even though it doesn't really address the original
OF separation comment. :)

Maybe it's enough to document the difference between the linux-specific
flat device tree bindings and classic 1275-style bindings in the top
readme in that directory. Either way, it's not worth arguing over,
your suggestion is good enough.

> > Looks reasonable. The other way to cut it would be to slice along vendor
> > boundaries, but I think I like the functional partitioning you suggested
> > better.
> 
> I think vendor partitioning makes sense for non-common devices that
> don't easily fit into a particular mold (soc glue nodes come to mind).
>  Other than that, the functional partitioning
> lets us start with defining common property usage for a given device
> type and follow up with device specific properties.

Yep, it could always be added down the road in case it's needed.


-Olof

Re: Refactor booting-without-of.txt

[David Gibson]

On Mon, Oct 15, 2007 at 11:14:44AM -0600, Grant Likely wrote:
> On 10/15/07, Olof Johansson <olof@lixom.net> wrote:
> > On Mon, Oct 15, 2007 at 10:08:44AM -0600, Grant Likely wrote:
> > > Adding the Linux expected device tree bindings to
> > > booting-without-of.txt seems to be getting a little unwieldy.  Plus
> > > with more than one arch using the device tree (powerpc, sparc &
> > > microblaze) the device tree bindings aren't necessarily powerpc only
> > > (the Xilinx devices certainly fall in this category).
> > >
> > > Anyone have comments about splitting the expected device tree bindings
> > > out of booting-without-of.txt into a separate directory?
> >
> > The flat device tree is, in spite of what some people would like it to be,
> > not open firmware, nor is it the same as their bindings. So I think we'd
> > be doing ourselves a disservice by continuing to associate them together.
> > All it would take is a rename of the directory, unfortunately i don't
> > have any suggestions on better names though.
> 
> I think I need to stick with the of prefix.  All the support API in
> include/linux/of_* is prefixed with "of_" already, so convention is
> established.
> 
> How about Documentation/of-device-tree?

It seems a little counterintuitive to change names from "booting
*without* of" to "of *"...

-- 
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: Refactor booting-without-of.txt

[Grant Likely]

On 10/15/07, David Gibson <david@gibson.dropbear.id.au> wrote:
> On Mon, Oct 15, 2007 at 11:14:44AM -0600, Grant Likely wrote:
> > On 10/15/07, Olof Johansson <olof@lixom.net> wrote:
> > > On Mon, Oct 15, 2007 at 10:08:44AM -0600, Grant Likely wrote:
> > > > Adding the Linux expected device tree bindings to
> > > > booting-without-of.txt seems to be getting a little unwieldy.  Plus
> > > > with more than one arch using the device tree (powerpc, sparc &
> > > > microblaze) the device tree bindings aren't necessarily powerpc only
> > > > (the Xilinx devices certainly fall in this category).
> > > >
> > > > Anyone have comments about splitting the expected device tree bindings
> > > > out of booting-without-of.txt into a separate directory?
> > >
> > > The flat device tree is, in spite of what some people would like it to be,
> > > not open firmware, nor is it the same as their bindings. So I think we'd
> > > be doing ourselves a disservice by continuing to associate them together.
> > > All it would take is a rename of the directory, unfortunately i don't
> > > have any suggestions on better names though.
> >
> > I think I need to stick with the of prefix.  All the support API in
> > include/linux/of_* is prefixed with "of_" already, so convention is
> > established.
> >
> > How about Documentation/of-device-tree?
>
> It seems a little counterintuitive to change names from "booting
> *without* of" to "of *"...

Heh; true.  The *only* reason I think it should be 'of-<anything>' is
because *all* the support APIs are named that way.  I'll happily use
another name if I get the impression that most of us in our little
group think it should be something else.

Cheers,
g.


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

Re: Refactor booting-without-of.txt

[David Gibson]

On Mon, Oct 15, 2007 at 09:02:09PM -0600, Grant Likely wrote:
> On 10/15/07, David Gibson <david@gibson.dropbear.id.au> wrote:
> > On Mon, Oct 15, 2007 at 11:14:44AM -0600, Grant Likely wrote:
> > > On 10/15/07, Olof Johansson <olof@lixom.net> wrote:
> > > > On Mon, Oct 15, 2007 at 10:08:44AM -0600, Grant Likely wrote:
> > > > > Adding the Linux expected device tree bindings to
> > > > > booting-without-of.txt seems to be getting a little unwieldy.  Plus
> > > > > with more than one arch using the device tree (powerpc, sparc &
> > > > > microblaze) the device tree bindings aren't necessarily powerpc only
> > > > > (the Xilinx devices certainly fall in this category).
> > > > >
> > > > > Anyone have comments about splitting the expected device tree bindings
> > > > > out of booting-without-of.txt into a separate directory?
> > > >
> > > > The flat device tree is, in spite of what some people would like it to be,
> > > > not open firmware, nor is it the same as their bindings. So I think we'd
> > > > be doing ourselves a disservice by continuing to associate them together.
> > > > All it would take is a rename of the directory, unfortunately i don't
> > > > have any suggestions on better names though.
> > >
> > > I think I need to stick with the of prefix.  All the support API in
> > > include/linux/of_* is prefixed with "of_" already, so convention is
> > > established.
> > >
> > > How about Documentation/of-device-tree?
> >
> > It seems a little counterintuitive to change names from "booting
> > *without* of" to "of *"...
> 
> Heh; true.  The *only* reason I think it should be 'of-<anything>' is
> because *all* the support APIs are named that way.  I'll happily use

No, not all, just most...

And do bear in mind that a lot of those accessor functions are at
least valid both on of and flat-tree systems.

> another name if I get the impression that most of us in our little
> group think it should be something else.
> 
> Cheers,
> g.
> 
> 

-- 
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: Refactor booting-without-of.txt

[Stephen Neuendorffer]

On a similar note, is there interest in actually factoring the device
tree code out from the different architectures into a common codebase?

Steve=20

> -----Original Message-----
> From:=20
> linuxppc-dev-bounces+stephen.neuendorffer=3Dxilinx.com@ozlabs.or
> g=20
> [mailto:linuxppc-dev-bounces+stephen.neuendorffer=3Dxilinx.com@o
zlabs.org] On Behalf Of Grant Likely
> Sent: Monday, October 15, 2007 9:09 AM
> To: linuxppc-dev; microblaze-uclinux@itee.uq.edu.au
> Subject: Refactor booting-without-of.txt
>=20
> Adding the Linux expected device tree bindings to
> booting-without-of.txt seems to be getting a little unwieldy.  Plus
> with more than one arch using the device tree (powerpc, sparc &
> microblaze) the device tree bindings aren't necessarily powerpc only
> (the Xilinx devices certainly fall in this category).
>=20
> Anyone have comments about splitting the expected device tree bindings
> out of booting-without-of.txt into a separate directory?
>=20
> Perhaps something like this; each file contains common bindings for
> the type of device and device specific properties:
>=20
> Documentation/of/
> Documentation/of/README - Description of the purpose and layout of
> this directory
> Documentation/of/net.txt - network device bindings (eth,=20
> MDIO, phy, etc)
> Documentation/of/serial.txt - serial device bindings
> Documentation/of/misc.txt - anything that doesn't fit=20
> anywhere else yet.
> Documentation/of/soc/* - System on chip stuff that doesn't fit will
> into established device types; possibly a separate file for each chip.
> Documentation/of/usb.txt - usb blah blah blah
> Documentation/of/whatever - you get the picture.
>=20
> Thoughts?
> g.
>=20
> --=20
> Grant Likely, B.Sc., P.Eng.
> Secret Lab Technologies Ltd.
> grant.likely@secretlab.ca
> (403) 399-0195
> _______________________________________________
> Linuxppc-dev mailing list
> Linuxppc-dev@ozlabs.org
> https://ozlabs.org/mailman/listinfo/linuxppc-dev
>=20
>=20

Re: Refactor booting-without-of.txt

[Grant Likely]

On 10/16/07, Stephen Neuendorffer <stephen.neuendorffer@xilinx.com> wrote:
> On a similar note, is there interest in actually factoring the device
> tree code out from the different architectures into a common codebase?

It's already happened somewhat.  (Look in drivers/of and include/linux/of*.h)

However, I don't think any of the stuff specific to flattened device
trees is being factored out of arch/powerpc yet.

Cheers,
g.

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

RE: Refactor booting-without-of.txt

[Stephen Neuendorffer]

=20
> -----Original Message-----
> From:=20
> linuxppc-dev-bounces+stephen.neuendorffer=3Dxilinx.com@ozlabs.or
> g=20
> [mailto:linuxppc-dev-bounces+stephen.neuendorffer=3Dxilinx.com@o
zlabs.org] On Behalf Of David Gibson
> Sent: Monday, October 15, 2007 8:24 PM
> To: Grant Likely
> Cc: Olof Johansson; linuxppc-dev; microblaze-uclinux@itee.uq.edu.au
> Subject: Re: Refactor booting-without-of.txt
>=20
> On Mon, Oct 15, 2007 at 09:02:09PM -0600, Grant Likely wrote:
> > On 10/15/07, David Gibson <david@gibson.dropbear.id.au> wrote:
> > > On Mon, Oct 15, 2007 at 11:14:44AM -0600, Grant Likely wrote:
> > > > On 10/15/07, Olof Johansson <olof@lixom.net> wrote:
> > > > > On Mon, Oct 15, 2007 at 10:08:44AM -0600, Grant Likely wrote:
> > > > > > Adding the Linux expected device tree bindings to
> > > > > > booting-without-of.txt seems to be getting a little=20
> unwieldy.  Plus
> > > > > > with more than one arch using the device tree=20
> (powerpc, sparc &
> > > > > > microblaze) the device tree bindings aren't=20
> necessarily powerpc only
> > > > > > (the Xilinx devices certainly fall in this category).
> > > > > >
> > > > > > Anyone have comments about splitting the expected=20
> device tree bindings
> > > > > > out of booting-without-of.txt into a separate directory?
> > > > >
> > > > > The flat device tree is, in spite of what some people=20
> would like it to be,
> > > > > not open firmware, nor is it the same as their=20
> bindings. So I think we'd
> > > > > be doing ourselves a disservice by continuing to=20
> associate them together.
> > > > > All it would take is a rename of the directory,=20
> unfortunately i don't
> > > > > have any suggestions on better names though.
> > > >
> > > > I think I need to stick with the of prefix.  All the=20
> support API in
> > > > include/linux/of_* is prefixed with "of_" already, so=20
> convention is
> > > > established.
> > > >
> > > > How about Documentation/of-device-tree?
> > >
> > > It seems a little counterintuitive to change names from "booting
> > > *without* of" to "of *"...
> >=20
> > Heh; true.  The *only* reason I think it should be=20
> 'of-<anything>' is
> > because *all* the support APIs are named that way.  I'll happily use
>=20
> No, not all, just most...
>=20
> And do bear in mind that a lot of those accessor functions are at
> least valid both on of and flat-tree systems.
>=20
> > another name if I get the impression that most of us in our little
> > group think it should be something else.
> >=20
> > Cheers,
> > g.
> >=20
> >=20
>

How about just 'device-tree', referring to any source, and then
of-device-tree and flat-device-tree to document how the device tree is
constructed.
The fact that the API is poorly named is something that can always be
fixed (and perhaps should be earlier rather than later).

Steve

Re: Refactor booting-without-of.txt

[Grant Likely]

On 10/16/07, Stephen Neuendorffer <stephen.neuendorffer@xilinx.com> wrote:
> How about just 'device-tree', referring to any source, and then
> of-device-tree and flat-device-tree to document how the device tree is
> constructed.
> The fact that the API is poorly named is something that can always be
> fixed (and perhaps should be earlier rather than later).

It's not so much that it's poorly named; it's just historically named.  :-)

g.

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

RE: Refactor booting-without-of.txt

[Yoder Stuart-B08248]

=20

> -----Original Message-----
> From: linuxppc-dev-bounces+b08248=3Dfreescale.com@ozlabs.org=20
> [mailto:linuxppc-dev-bounces+b08248=3Dfreescale.com@ozlabs.org]=20
> On Behalf Of Grant Likely
> Sent: Monday, October 15, 2007 11:09 AM
> To: linuxppc-dev; microblaze-uclinux@itee.uq.edu.au
> Subject: Refactor booting-without-of.txt
>=20
> Adding the Linux expected device tree bindings to
> booting-without-of.txt seems to be getting a little unwieldy.  Plus
> with more than one arch using the device tree (powerpc, sparc &
> microblaze) the device tree bindings aren't necessarily powerpc only
> (the Xilinx devices certainly fall in this category).
>=20
> Anyone have comments about splitting the expected device tree bindings
> out of booting-without-of.txt into a separate directory?
>=20
> Perhaps something like this; each file contains common bindings for
> the type of device and device specific properties:
>=20
> Documentation/of/
> Documentation/of/README - Description of the purpose and layout of
> this directory
> Documentation/of/net.txt - network device bindings (eth,=20
> MDIO, phy, etc)
> Documentation/of/serial.txt - serial device bindings
> Documentation/of/misc.txt - anything that doesn't fit=20
> anywhere else yet.
> Documentation/of/soc/* - System on chip stuff that doesn't fit will
> into established device types; possibly a separate file for each chip.
> Documentation/of/usb.txt - usb blah blah blah
> Documentation/of/whatever - you get the picture.
>=20

I agree in principle with what your are proposing.

One other thing to consider-- as has been publicly=20
announced in several forums, a committee in power.org
(including several folks on this thread) is working
on a standard called the ePAPR which in general is
attempting to standardize the base set of requirements
and boot conventions that apply to the flat device tree.
There will not be much device specific stuff to=20
start with.

The ePAPR document is actually quite far a long
and is well beyond the 'idea' stage.

The one point is that we hope that the device tree
with be useful for other embedded OSes beyond Linux.
So long term, I think this documentation should
be pulled out of the kernel source and put
on a public wiki that is not tied directly to Linux.
What you are proposing is a good start...

Stuart