New fsl device bindings file

New fsl device bindings file

[Kumar Gala]

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

Re: New fsl device bindings file

[Scott Wood]

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

Re: New fsl device bindings file

[Grant Likely]

On Thu, Jul 3, 2008 at 12:28 PM, Scott Wood <scottwood@freescale.com> wrote:
> 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.

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.

Re: New fsl device bindings file

[Kumar Gala]

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

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

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

Re: New fsl device bindings file

[Kumar Gala]

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

> On Thu, Jul 3, 2008 at 12:28 PM, Scott Wood  
> <scottwood@freescale.com> wrote:
>> 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.
>
> 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).

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

Re: New fsl device bindings file

[Anton Vorontsov]

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

Re: New fsl device bindings file

[Paul Mackerras]

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.

Re: New fsl device bindings file

[Grant Likely]

On Thu, Jul 03, 2008 at 01:38:17PM -0500, Kumar Gala wrote:
>
> On Jul 3, 2008, at 1:34 PM, Grant Likely wrote:
>
>> On Thu, Jul 3, 2008 at 12:28 PM, Scott Wood <scottwood@freescale.com> 
>> wrote:
>>> 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.

Re: New fsl device bindings file

[Matt Sealey]

Anton Vorontsov wrote:
> On Thu, Jul 03, 2008 at 01:20:18PM -0500, Kumar Gala wrote:
>> 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 <matt@genesi-usa.com>
Genesi, Manager, Developer Relations

Re: New fsl device bindings file

[Segher Boessenkool]

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

Because it is human-readable text?

> Or is this too wild? :-)

Yes :-)


Segher

Re: New fsl device bindings file

[Segher Boessenkool]

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

Re: New fsl device bindings file

[Segher Boessenkool]

> 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

Re: New fsl device bindings file

[David Gibson]

On Sat, Jul 05, 2008 at 01:12:31AM +0200, Segher Boessenkool wrote:
>>> 	/* 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.
>
>> 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.
>
>> 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.

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

Re: New fsl device bindings file

[Olof Johansson]

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

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

Re: New fsl device bindings file

[Grant Likely]

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:
> >>> 	/* 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.
> >
> >> 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.
> >
> >> 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.
> 
> Thank you Segher, you saved me the trouble of saying exactly all that.

Ditto.

g.

Re: New fsl device bindings file

[Jochen Friedrich]

Hi Scott,

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

Re: New fsl device bindings file

[David Gibson]

On Sat, Jul 05, 2008 at 12:24:56AM -0500, Olof Johansson wrote:
>
> On Jul 3, 2008, at 1:34 PM, Grant Likely wrote:
>
>>> 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

Re: New fsl device bindings file

[Olof Johansson]

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

Re: New fsl device bindings file

[Kumar Gala]

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

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

I agree With Olof and plain on calling it:

Documentation/powerpc/dts-bindings/fsl/

- k