Re: New fsl device bindings file

[Anton Vorontsov <avorontsov@ru.mvista.com>]

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