New fsl device bindings file

Guys,

I'm sure you'll hate for doing this, but I've asked Kim to create a  
new Documentation/powerpc/fsl-device-tree-bindings.txt as part of his  
SEC patch.

I'm going to move all the Freescale SoC related bindings into this new  
file.  One of the aspects of the new file is we will NOT having an  
ordinal heading index.

Once I accept his new patch that add bindings to the new file.

thanks

- k

Kumar Gala wrote:

I'm sure you'll hate for doing this, but I've asked Kim to create a new 
Documentation/powerpc/fsl-device-tree-bindings.txt as part of his SEC 
patch.

I'm going to move all the Freescale SoC related bindings into this new 
file.  One of the aspects of the new file is we will NOT having an 
ordinal heading index.

How about splitting up like this:

Documentation/powerpc/device-tree/fsl/cpm.txt
Documentation/powerpc/device-tree/fsl/cpm/uart.txt
Documentation/powerpc/device-tree/fsl/tsec.txt
Documentation/powerpc/device-tree/interrupts.txt
Documentation/powerpc/device-tree/dtb.txt

etc?

-Scott

On Thu, Jul 3, 2008 at 12:28 PM, Scott Wood [off-list ref] wrote:

Kumar Gala wrote:

quoted

I'm sure you'll hate for doing this, but I've asked Kim to create a new
Documentation/powerpc/fsl-device-tree-bindings.txt as part of his SEC patch.

I'm going to move all the Freescale SoC related bindings into this new
file.  One of the aspects of the new file is we will NOT having an ordinal
heading index.

Not at all.  This is much needed.  The current file is far to unwieldy

How about splitting up like this:

Documentation/powerpc/device-tree/fsl/cpm.txt
Documentation/powerpc/device-tree/fsl/cpm/uart.txt
Documentation/powerpc/device-tree/fsl/tsec.txt
Documentation/powerpc/device-tree/interrupts.txt
Documentation/powerpc/device-tree/dtb.txt

May I suggest moving it to Documentation/of-bindings/ instead?  Some
of these bindings (granted, not the fsl ones) will be used by
non-powerpc platforms (sparc, microblaze).

g.

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

On Jul 3, 2008, at 1:28 PM, Scott Wood wrote:

Kumar Gala wrote:

quoted

I'm sure you'll hate for doing this, but I've asked Kim to create a  
new Documentation/powerpc/fsl-device-tree-bindings.txt as part of  
his SEC patch.
I'm going to move all the Freescale SoC related bindings into this  
new file.  One of the aspects of the new file is we will NOT having  
an ordinal heading index.

How about splitting up like this:

Documentation/powerpc/device-tree/fsl/cpm.txt
Documentation/powerpc/device-tree/fsl/cpm/uart.txt
Documentation/powerpc/device-tree/fsl/tsec.txt
Documentation/powerpc/device-tree/interrupts.txt
Documentation/powerpc/device-tree/dtb.txt

etc?

I like this, we can start with just the fsl/ dirs for now and see if  
others feelings on the other higher level bits.

- k

On Jul 3, 2008, at 1:34 PM, Grant Likely wrote:

On Thu, Jul 3, 2008 at 12:28 PM, Scott Wood  
[off-list ref] wrote:

quoted

Kumar Gala wrote:

quoted

I'm sure you'll hate for doing this, but I've asked Kim to create  
a new
Documentation/powerpc/fsl-device-tree-bindings.txt as part of his  
SEC patch.

I'm going to move all the Freescale SoC related bindings into this  
new
file.  One of the aspects of the new file is we will NOT having an  
ordinal
heading index.

Not at all.  This is much needed.  The current file is far to unwieldy

quoted

How about splitting up like this:

Documentation/powerpc/device-tree/fsl/cpm.txt
Documentation/powerpc/device-tree/fsl/cpm/uart.txt
Documentation/powerpc/device-tree/fsl/tsec.txt
Documentation/powerpc/device-tree/interrupts.txt
Documentation/powerpc/device-tree/dtb.txt

May I suggest moving it to Documentation/of-bindings/ instead?  Some
of these bindings (granted, not the fsl ones) will be used by
non-powerpc platforms (sparc, microblaze).

I think the powerpc bindings should still be under Docs/powerpc/of- 
bindings/

It makes it cleaner in that each arch/sub-arch maintainer can maintain  
Docs/<arch>/of-bindings and we can all vet changes to Docs/of-bindings

- k

On Thu, Jul 03, 2008 at 01:20:18PM -0500, Kumar Gala wrote:

Guys,

I'm sure you'll hate for doing this, but I've asked Kim to create a new 
Documentation/powerpc/fsl-device-tree-bindings.txt as part of his SEC 
patch.

Just curious... why we're maintaining documentation in the .txt file?
We could just create Documentation/powerpc/fsl-device-tree-bindings.dts
file, that will be:

1. True device tree source file;
2. With a lots of comments for documentation purposes;
3. Could be compiled (via imaginable dts-doxygen) into .txt or nice .pdf
   file and printed :-), exactly as we do with kerneldoc.

For example, this

- - - -
   e) I2C

   Required properties :

    - device_type : Should be "i2c"
    - reg : Offset and length of the register set for the device

   Recommended properties :

    - compatible : Should be "fsl-i2c" for parts compatible with
      Freescale I2C specifications.
    - interrupts : <a b> where a is the interrupt number and b is a
      field that represents an encoding of the sense and level
      information for the interrupt.  This should be encoded based on
      the information in section 2) depending on the type of interrupt
      controller you have.
    - interrupt-parent : the phandle for the interrupt controller that
      services interrupts for this device.
    - dfsrr : boolean; if defined, indicates that this I2C device has
      a digital filter sampling rate register
    - fsl5200-clocking : boolean; if defined, indicated that this device
      uses the FSL 5200 clocking mechanism.

   Example :

	i2c@3000 {
		interrupt-parent = <40000>;
		interrupts = <1b 3>;
		reg = <3000 18>;
		device_type = "i2c";
		compatible  = "fsl-i2c";
		dfsrr;
	};
- - - -

Turns into

- - - -
/* Freescale I2C controller */
i2c@3000 {
	/* the phandle for the interrupt controller that services interrupts
	 * for this device. */
	interrupt-parent = <40000>;

	/* interrupts: <a b> where a is the interrupt number and b is a
	 * field that represents an encoding of the sense and level
	 * information for the interrupt.  This should be encoded based on
	 * the information in section 2) depending on the type of interrupt
	 * controller you have. */
	interrupts = <1b 3>;

	/* offset and length of the register set for the device */
	reg = <3000 18>;

	/* deprecated; */
	device_type = "i2c";

	/* should be "fsl-i2c" for parts compatible with Freescale I2C
	 * specifications. */
	compatible  = "fsl-i2c";

	/* optional; boolean; if defined, indicates that this I2C device has
 	 * a digital filter sampling rate register */
	dfsrr;

	/* optional; boolean; if defined, indicated that this device
	 * uses the FSL 5200 clocking mechanism. */
	fsl5200-clocking;
};
- - - -

Or is this too wild? :-)

-- 
Anton Vorontsov
email: cbouatmailru@gmail.com
irc://irc.freenode.net/bd2

Anton Vorontsov writes:

Just curious... why we're maintaining documentation in the .txt file?
We could just create Documentation/powerpc/fsl-device-tree-bindings.dts
file, that will be:

1. True device tree source file;
2. With a lots of comments for documentation purposes;
3. Could be compiled (via imaginable dts-doxygen) into .txt or nice .pdf
   file and printed :-), exactly as we do with kerneldoc.

I suspect that will be harder to follow for people that are unfamiliar
with device trees...

Paul.

On Thu, Jul 03, 2008 at 01:38:17PM -0500, Kumar Gala wrote:

On Jul 3, 2008, at 1:34 PM, Grant Likely wrote:

quoted

On Thu, Jul 3, 2008 at 12:28 PM, Scott Wood [off-list ref] 
wrote:

quoted

Documentation/powerpc/device-tree/fsl/cpm.txt
Documentation/powerpc/device-tree/fsl/cpm/uart.txt
Documentation/powerpc/device-tree/fsl/tsec.txt
Documentation/powerpc/device-tree/interrupts.txt
Documentation/powerpc/device-tree/dtb.txt

May I suggest moving it to Documentation/of-bindings/ instead?  Some
of these bindings (granted, not the fsl ones) will be used by
non-powerpc platforms (sparc, microblaze).

I think the powerpc bindings should still be under Docs/powerpc/of- 
bindings/

It makes it cleaner in that each arch/sub-arch maintainer can maintain  
Docs/<arch>/of-bindings and we can all vet changes to Docs/of-bindings

Personally, I think it would still be better to keep everything in one
place, even if large parts of it are arch specific.  I think it would
encourage people to look across architecture boundaries when looking for
examples of how to document device tree bindings.  It would also
discourage accidental duplication for parts that end up being used in
more than one architectures (ie. spi and i2c devices).  Not everyone is
going to be well versed on the rules of what bindings should be arch
specific and what should go in the common dir.  It will make everyone's
life easier if there is only one place to look.

(oh, and I think the subdirectories by manufacturer is a good layout).

g.

Anton Vorontsov wrote:

On Thu, Jul 03, 2008 at 01:20:18PM -0500, Kumar Gala wrote:

quoted

Guys,

	/* deprecated; */
	device_type = "i2c";

How about "deprecated but kept for compatibility with true Open Firmware
implementations"?

Seriously, you can't have a binding for "OF" and then cut out that part of the
standard at a whim. It should be there (at least for those parts which are
governed by a client interface API, like display, serial etc. but cutting it
off takes away all it's meaning, plus Linux implementations STILL keep searching
that property along with "compatible", and probably will for all time that
real IEEE1275 bindings are in use), and if it's not, then what used to go into
there needs to be in compatible.

As a nit, I don't think making it into an example makes the documentation any better
to read at all, in fact I found it harder to read. You may as well throw away all
the docs altogether and produce a well-commented example set if that is the route
this is going down. I think having everything as a plaintext file, while nice and
accessible for everyone, might have something to do with that though.

-- 
Matt Sealey [off-list ref]
Genesi, Manager, Developer Relations

Just curious... why we're maintaining documentation in the .txt file?

Because it is human-readable text?

Or is this too wild? :-)

Yes :-)


Segher

quoted

	/* deprecated; */
	device_type =3D "i2c";

How about "deprecated but kept for compatibility with true Open=20
Firmware
implementations"?

Well, except a flat tree isn't compatible with OF at all here.
A "device_type" promises a certain interface; a flat tree doesn't
even have the "open" method.  =46rom the OF base spec:

	=93device_type=94 S

	Standard property name to specify the implemented interface.

	prop-encoded-array: Text string encoded with encode-string.

	Specifies the =93device type=94 of this package, thus implying a
	specific set of package class methods implemented by this
	package.

Seriously, you can't have a binding for "OF" and then cut out that=20
part of the
standard at a whim.

Nothing is cut out.  There never was a device binding for device_type
i2c; creating one would be a considerable effort, and since flat tree
users wouldn't use it anyway, you can't be seriously suggesting they
should do this.

It should be there (at least for those parts which are
governed by a client interface API, like display, serial etc.

Huh?  Nothing in the client interface mentions display or serial
as far as I know.

but cutting it off takes away all it's meaning,

So what?  There _is_ no "real" device interface, when a flat tree is
used.

plus Linux implementations STILL keep searching
that property along with "compatible",

That's a bug.


Segher

I'm sure you'll hate for doing this,

No, it's an excellent move :-)

but I've asked Kim to create a new 
Documentation/powerpc/fsl-device-tree-bindings.txt as part of his SEC 
patch.

As a separate patch, that (at first) _only_ moves the content into 
separate
files, please.


Segher

On Sat, Jul 05, 2008 at 01:12:31AM +0200, Segher Boessenkool wrote:

quoted

quoted

	/* deprecated; */
	device_type = "i2c";

How about "deprecated but kept for compatibility with true Open  
Firmware
implementations"?

Well, except a flat tree isn't compatible with OF at all here.
A "device_type" promises a certain interface; a flat tree doesn't
even have the "open" method.  From the OF base spec:

	“device_type” S

	Standard property name to specify the implemented interface.

	prop-encoded-array: Text string encoded with encode-string.

	Specifies the “device type” of this package, thus implying a
	specific set of package class methods implemented by this
	package.

quoted

Seriously, you can't have a binding for "OF" and then cut out that  
part of the
standard at a whim.

Nothing is cut out.  There never was a device binding for device_type
i2c; creating one would be a considerable effort, and since flat tree
users wouldn't use it anyway, you can't be seriously suggesting they
should do this.

quoted

It should be there (at least for those parts which are
governed by a client interface API, like display, serial etc.

Huh?  Nothing in the client interface mentions display or serial
as far as I know.

quoted

but cutting it off takes away all it's meaning,

So what?  There _is_ no "real" device interface, when a flat tree is
used.

quoted

plus Linux implementations STILL keep searching
that property along with "compatible",

That's a bug.

Thank you Segher, you saved me the trouble of saying exactly all that.

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

On Jul 3, 2008, at 1:34 PM, Grant Likely wrote:

quoted

How about splitting up like this:

Documentation/powerpc/device-tree/fsl/cpm.txt
Documentation/powerpc/device-tree/fsl/cpm/uart.txt
Documentation/powerpc/device-tree/fsl/tsec.txt
Documentation/powerpc/device-tree/interrupts.txt
Documentation/powerpc/device-tree/dtb.txt

May I suggest moving it to Documentation/of-bindings/ instead?  Some
of these bindings (granted, not the fsl ones) will be used by
non-powerpc platforms (sparc, microblaze).

Good idea, but:

Don't call the bindings OF. They're not.

They are a linux-specific binding that happens to use the same data  
structures and representation that OF does.

Call them dts-bindings or something else, just to avoid confusion.


-Olof

On Sat, Jul 05, 2008 at 11:26:24AM +1000, David Gibson wrote:

On Sat, Jul 05, 2008 at 01:12:31AM +0200, Segher Boessenkool wrote:

quoted

quoted

quoted

	/* deprecated; */
	device_type = "i2c";

How about "deprecated but kept for compatibility with true Open  
Firmware
implementations"?

Well, except a flat tree isn't compatible with OF at all here.
A "device_type" promises a certain interface; a flat tree doesn't
even have the "open" method.  From the OF base spec:

	“device_type” S

	Standard property name to specify the implemented interface.

	prop-encoded-array: Text string encoded with encode-string.

	Specifies the “device type” of this package, thus implying a
	specific set of package class methods implemented by this
	package.

quoted

Seriously, you can't have a binding for "OF" and then cut out that  
part of the
standard at a whim.

Nothing is cut out.  There never was a device binding for device_type
i2c; creating one would be a considerable effort, and since flat tree
users wouldn't use it anyway, you can't be seriously suggesting they
should do this.

quoted

It should be there (at least for those parts which are
governed by a client interface API, like display, serial etc.

Huh?  Nothing in the client interface mentions display or serial
as far as I know.

quoted

but cutting it off takes away all it's meaning,

So what?  There _is_ no "real" device interface, when a flat tree is
used.

quoted

plus Linux implementations STILL keep searching
that property along with "compatible",

That's a bug.

Thank you Segher, you saved me the trouble of saying exactly all that.

Ditto.

g.

Hi Scott,

quoted

I'm going to move all the Freescale SoC related bindings into this new 
file.  One of the aspects of the new file is we will NOT having an 
ordinal heading index.

How about splitting up like this:

Documentation/powerpc/device-tree/fsl/cpm.txt
Documentation/powerpc/device-tree/fsl/cpm/uart.txt
Documentation/powerpc/device-tree/fsl/tsec.txt
Documentation/powerpc/device-tree/interrupts.txt
Documentation/powerpc/device-tree/dtb.txt

Sounds reasonable.

Thanks,
Jochen

On Sat, Jul 05, 2008 at 12:24:56AM -0500, Olof Johansson wrote:

On Jul 3, 2008, at 1:34 PM, Grant Likely wrote:

quoted

quoted

How about splitting up like this:

Documentation/powerpc/device-tree/fsl/cpm.txt
Documentation/powerpc/device-tree/fsl/cpm/uart.txt
Documentation/powerpc/device-tree/fsl/tsec.txt
Documentation/powerpc/device-tree/interrupts.txt
Documentation/powerpc/device-tree/dtb.txt

May I suggest moving it to Documentation/of-bindings/ instead?  Some
of these bindings (granted, not the fsl ones) will be used by
non-powerpc platforms (sparc, microblaze).

Good idea, but:

Don't call the bindings OF. They're not.

They are a linux-specific binding that happens to use the same data  
structures and representation that OF does.

Well... they may be Linux specific by default, but they're supposed to
be general enough that they (or at least, very small extensions)
*could* become official OF bindings, if there was still an OF group to
make them so.  It certainly should be possible to use these bindings
in a firmware which provides an OF client interface as well as in
flat-tree-only firmwares which don't.

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

On Jul 6, 2008, at 8:39 PM, David Gibson wrote:

Well... they may be Linux specific by default, but they're supposed to
be general enough that they (or at least, very small extensions)
*could* become official OF bindings, if there was still an OF group to
make them so.  It certainly should be possible to use these bindings
in a firmware which provides an OF client interface as well as in
flat-tree-only firmwares which don't.

Right, it's a classic case of embrace and extend. Calling it OF is  
just plain misleading, especially since the original document was  
called booting _WITHOUT_ OF.


-Olof

On Jul 6, 2008, at 8:45 PM, Olof Johansson wrote:

On Jul 6, 2008, at 8:39 PM, David Gibson wrote:

quoted

Well... they may be Linux specific by default, but they're supposed  
to
be general enough that they (or at least, very small extensions)
*could* become official OF bindings, if there was still an OF group  
to
make them so.  It certainly should be possible to use these bindings
in a firmware which provides an OF client interface as well as in
flat-tree-only firmwares which don't.

Right, it's a classic case of embrace and extend. Calling it OF is  
just plain misleading, especially since the original document was  
called booting _WITHOUT_ OF.

I agree With Olof and plain on calling it:

Documentation/powerpc/dts-bindings/fsl/

- k