Re: New fsl device bindings file
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 ___ Linuxppc-dev mailing list Linuxppc-dev@ozlabs.org https://ozlabs.org/mailman/listinfo/linuxppc-dev
Re: New fsl device bindings file
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 ___ Linuxppc-dev mailing list Linuxppc-dev@ozlabs.org https://ozlabs.org/mailman/listinfo/linuxppc-dev
Re: New fsl device bindings file
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. ___ Linuxppc-dev mailing list Linuxppc-dev@ozlabs.org https://ozlabs.org/mailman/listinfo/linuxppc-dev
Re: New fsl device bindings file
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 ___ Linuxppc-dev mailing list Linuxppc-dev@ozlabs.org https://ozlabs.org/mailman/listinfo/linuxppc-dev
Re: New fsl device bindings file
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 [EMAIL PROTECTED] Genesi, Manager, Developer Relations ___ Linuxppc-dev mailing list Linuxppc-dev@ozlabs.org https://ozlabs.org/mailman/listinfo/linuxppc-dev
Re: New fsl device bindings file
Just curious... why we're maintaining documentation in the .txt file? Because it is human-readable text? Or is this too wild? :-) Yes :-) Segher ___ Linuxppc-dev mailing list Linuxppc-dev@ozlabs.org https://ozlabs.org/mailman/listinfo/linuxppc-dev
Re: New fsl device bindings file
/* 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. Segher ___ Linuxppc-dev mailing list Linuxppc-dev@ozlabs.org https://ozlabs.org/mailman/listinfo/linuxppc-dev
Re: New fsl device bindings file
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 ___ Linuxppc-dev mailing list Linuxppc-dev@ozlabs.org https://ozlabs.org/mailman/listinfo/linuxppc-dev
Re: New fsl device bindings file
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 ___ Linuxppc-dev mailing list Linuxppc-dev@ozlabs.org https://ozlabs.org/mailman/listinfo/linuxppc-dev
Re: New fsl device bindings file
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 ___ Linuxppc-dev mailing list Linuxppc-dev@ozlabs.org https://ozlabs.org/mailman/listinfo/linuxppc-dev
Re: New fsl device bindings file
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 ___ Linuxppc-dev mailing list Linuxppc-dev@ozlabs.org https://ozlabs.org/mailman/listinfo/linuxppc-dev
Re: New fsl device bindings file
On Thu, Jul 3, 2008 at 12:28 PM, Scott Wood [EMAIL PROTECTED] 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. ___ Linuxppc-dev mailing list Linuxppc-dev@ozlabs.org https://ozlabs.org/mailman/listinfo/linuxppc-dev
Re: New fsl device bindings file
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 ___ Linuxppc-dev mailing list Linuxppc-dev@ozlabs.org https://ozlabs.org/mailman/listinfo/linuxppc-dev
Re: New fsl device bindings file
On Jul 3, 2008, at 1:34 PM, Grant Likely wrote: On Thu, Jul 3, 2008 at 12:28 PM, Scott Wood [EMAIL PROTECTED] 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 ___ Linuxppc-dev mailing list Linuxppc-dev@ozlabs.org https://ozlabs.org/mailman/listinfo/linuxppc-dev
Re: New fsl device bindings file
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 :
[EMAIL PROTECTED] {
interrupt-parent = 4;
interrupts = 1b 3;
reg = 3000 18;
device_type = i2c;
compatible = fsl-i2c;
dfsrr;
};
- - - -
Turns into
- - - -
/* Freescale I2C controller */
[EMAIL PROTECTED] {
/* the phandle for the interrupt controller that services interrupts
* for this device. */
interrupt-parent = 4;
/* 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: [EMAIL PROTECTED]
irc://irc.freenode.net/bd2
___
Linuxppc-dev mailing list
Linuxppc-dev@ozlabs.org
https://ozlabs.org/mailman/listinfo/linuxppc-dev
Re: New fsl device bindings file
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. ___ Linuxppc-dev mailing list Linuxppc-dev@ozlabs.org https://ozlabs.org/mailman/listinfo/linuxppc-dev
Re: New fsl device bindings file
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 [EMAIL PROTECTED] 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. ___ Linuxppc-dev mailing list Linuxppc-dev@ozlabs.org https://ozlabs.org/mailman/listinfo/linuxppc-dev
