[PATCH] [POWERPC] Add docs for Freescale DMA & DMA channel device tree nodes

[PATCH] [POWERPC] Add docs for Freescale DMA & DMA channel device tree nodes

[Kumar Gala]

Signed-off-by: Zhang Wei <wei.zhang@freescale.com>
Signed-off-by: Ebony Zhu <ebony.zhu@freescale.com>
Signed-off-by: Kumar Gala <galak@kernel.crashing.org>
---

Guys please review and make sure I got all your previous comments fixed
up.  I've added cell-index. and the examples should represent real HW.

 Documentation/powerpc/booting-without-of.txt |  128 ++++++++++++++++++++++++++
 1 files changed, 128 insertions(+), 0 deletions(-)

diff --git a/Documentation/powerpc/booting-without-of.txt b/Documentation/powerpc/booting-without-of.txt
index da98154..3584c33 100644
--- a/Documentation/powerpc/booting-without-of.txt
+++ b/Documentation/powerpc/booting-without-of.txt
@@ -2615,6 +2615,134 @@ platforms are moved over to use the flattened-device-tree model.
        - clock-frequency  : The frequency of the input clock, which typically
                             comes from an on-board dedicated oscillator.

+    * Freescale 83xx DMA Controller
+
+    Freescale PowerPC 83xx have on chip general purpose DMA controllers.
+
+    Required properties:
+
+    - compatible        : compatible list, contains 2 entries, first is
+			 "fsl,CHIP-dma", where CHIP is the processor
+			 (mpc8349, mpc8360, etc.) and the second is
+			 "fsl,elo-dma"
+    - reg               : <registers mapping for DMA general status reg>
+    - ranges 		: Should be defined as specified in 1) to describe the
+			  DMA controller channels.
+    - cell-index        : controller index.  0 for controller @ 0x8100
+    - interrupts        : <interrupt mapping for DMA IRQ>
+    - interrupt-parent  : optional, if needed for interrupt mapping
+
+
+    - DMA channel nodes:
+	    - compatible        : compatible list, contains 2 entries, first is
+				 "fsl,CHIP-dma-channel", where CHIP is the processor
+				 (mpc8349, mpc8350, etc.) and the second is
+				 "fsl,elo-dma-channel"
+	    - reg               : <registers mapping for channel>
+	    - cell-index        : dma channel index starts at 0.
+
+    Optional properties:
+	    - interrupts        : <interrupt mapping for DMA channel IRQ>
+				  (on 83xx this is expected to be identical to
+				   the interrupts property of the parent node)
+	    - interrupt-parent  : optional, if needed for interrupt mapping
+
+  Example:
+	dma@82a8 {
+		#address-cells = <1>;
+		#size-cells = <1>;
+		compatible = "fsl,mpc8349-dma", "fsl,elo-dma";
+		reg = <82a8 4>;
+		ranges = <0 8100 1a4>;
+		interrupt-parent = <&ipic>;
+		interrupts = <47 8>;
+		cell-index = <0>;
+		dma-channel@0 {
+			compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel";
+			cell-index = <0>;
+			reg = <0 80>;
+		};
+		dma-channel@80 {
+			compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel";
+			cell-index = <1>;
+			reg = <80 80>;
+		};
+		dma-channel@100 {
+			compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel";
+			cell-index = <2>;
+			reg = <100 80>;
+		};
+		dma-channel@180 {
+			compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel";
+			cell-index = <3>;
+			reg = <180 80>;
+		};
+	};
+
+   * Freescale 85xx/86xx DMA Controller
+
+    Freescale PowerPC 85xx/86xx have on chip general purpose DMA controllers.
+
+    Required properties:
+
+    - compatible        : compatible list, contains 2 entries, first is
+			 "fsl,CHIP-dma", where CHIP is the processor
+			 (mpc8540, mpc8540, etc.) and the second is
+			 "fsl,eloplus-dma"
+    - reg               : <registers mapping for DMA general status reg>
+    - cell-index        : controller index.  0 for controller @ 0x21000,
+                                             1 for controller @ 0xc000
+    - ranges 		: Should be defined as specified in 1) to describe the
+			  DMA controller channels.
+
+    - DMA channel nodes:
+	    - compatible        : compatible list, contains 2 entries, first is
+				 "fsl,CHIP-dma-channel", where CHIP is the processor
+				 (mpc8540, mpc8560, etc.) and the second is
+				 "fsl,eloplus-dma-channel"
+	    - cell-index        : dma channel index starts at 0.
+	    - reg               : <registers mapping for channel>
+	    - interrupts        : <interrupt mapping for DMA channel IRQ>
+	    - interrupt-parent  : optional, if needed for interrupt mapping
+
+  Example:
+	dma@21300 {
+		#address-cells = <1>;
+		#size-cells = <1>;
+		compatible = "fsl,mpc8540-dma", "fsl,eloplus-dma";
+		reg = <21300 4>;
+		ranges = <0 21100 200>;
+		cell-index = <0>;
+		dma-channel@0 {
+			compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel";
+			reg = <0 80>;
+			cell-index = <0>;
+			interrupt-parent = <&mpic>;
+			interrupts = <14 2>;
+		};
+		dma-channel@80 {
+			compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel";
+			reg = <80 80>;
+			cell-index = <1>;
+			interrupt-parent = <&mpic>;
+			interrupts = <15 2>;
+		};
+		dma-channel@100 {
+			compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel";
+			reg = <100 80>;
+			cell-index = <2>;
+			interrupt-parent = <&mpic>;
+			interrupts = <16 2>;
+		};
+		dma-channel@180 {
+			compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel";
+			reg = <180 80>;
+			cell-index = <3>;
+			interrupt-parent = <&mpic>;
+			interrupts = <17 2>;
+		};
+	};
+

    More devices will be defined as this spec matures.

-- 
1.5.3.7

Re: [PATCH] [POWERPC] Add docs for Freescale DMA & DMA channel device tree nodes

[Timur Tabi]

Kumar Gala wrote:
> Signed-off-by: Zhang Wei <wei.zhang@freescale.com>
> Signed-off-by: Ebony Zhu <ebony.zhu@freescale.com>
> Signed-off-by: Kumar Gala <galak@kernel.crashing.org>
> ---
> 
> Guys please review and make sure I got all your previous comments fixed
> up.  I've added cell-index. and the examples should represent real HW.
> 
>  Documentation/powerpc/booting-without-of.txt |  128 ++++++++++++++++++++++++++
>  1 files changed, 128 insertions(+), 0 deletions(-)
> 
> diff --git a/Documentation/powerpc/booting-without-of.txt b/Documentation/powerpc/booting-without-of.txt
> index da98154..3584c33 100644
> --- a/Documentation/powerpc/booting-without-of.txt
> +++ b/Documentation/powerpc/booting-without-of.txt
> @@ -2615,6 +2615,134 @@ platforms are moved over to use the flattened-device-tree model.
>         - clock-frequency  : The frequency of the input clock, which typically
>                              comes from an on-board dedicated oscillator.
> 
> +    * Freescale 83xx DMA Controller
> +
> +    Freescale PowerPC 83xx have on chip general purpose DMA controllers.
> +
> +    Required properties:
> +
> +    - compatible        : compatible list, contains 2 entries, first is
> +			 "fsl,CHIP-dma", where CHIP is the processor
> +			 (mpc8349, mpc8360, etc.) and the second is
> +			 "fsl,elo-dma"
> +    - reg               : <registers mapping for DMA general status reg>
> +    - ranges 		: Should be defined as specified in 1) to describe the
> +			  DMA controller channels.

What does "Should be defined as specified in 1)" mean?

> +    - cell-index        : controller index.  0 for controller @ 0x8100

This should be more generic.  I believe for each of our SoCs, we designation one 
DMA controller to be "DMA Controller 1", and that one should have a cell-index 
of "0".

> +    - interrupts        : <interrupt mapping for DMA IRQ>
> +    - interrupt-parent  : optional, if needed for interrupt mapping

On 83xx, all DMA channels share the same interrupt?  Couldn't we just specify 
the same IRQ in each channel's node, so that they look the same across 83xx, 
85xx, and 86xx?  My sound driver doesn't use Extended Mode, but it does check 
for "fsl,8610-dma-channel".  I'm thinking that maybe I should change to to look 
for "elo" or "eloplus", but it would be nice if we could make the DMA node for 
an 86xx SoC compatible with a driver that expects "fsl,elo-dma-channel".

-- 
Timur Tabi
Linux kernel developer at Freescale

Re: [PATCH] [POWERPC] Add docs for Freescale DMA & DMA channel device tree nodes

[Scott Wood]

Timur Tabi wrote:
> On 83xx, all DMA channels share the same interrupt?

Yes.

> Couldn't we just 
> specify the same IRQ in each channel's node, so that they look the same 
> across 83xx, 85xx, and 86xx?

The consensus that I thought we had reached was to let 83xx specify the 
interrupt in the controller node (to make things simple for a driver 
using the shared summary register rather than registering four handlers 
for the same IRQ), but require that it also be in the channel node, and 
that if there is an interrupt in the controller node, that it be the 
same as in all the channels.

> My sound driver doesn't use Extended Mode, 
> but it does check for "fsl,8610-dma-channel".  I'm thinking that maybe I 
> should change to to look for "elo" or "eloplus", but it would be nice if 
> we could make the DMA node for an 86xx SoC compatible with a driver that 
> expects "fsl,elo-dma-channel".

Sure it'd be nice, but it's not possible without going back in time and 
convincing the hardware people to make them 100% compatible.

-Scott

Re: [PATCH] [POWERPC] Add docs for Freescale DMA & DMA channel device tree nodes

[Kumar Gala]

On Jan 22, 2008, at 3:48 PM, Scott Wood wrote:

> Timur Tabi wrote:
>> On 83xx, all DMA channels share the same interrupt?
>
> Yes.
>
>> Couldn't we just specify the same IRQ in each channel's node, so  
>> that they look the same across 83xx, 85xx, and 86xx?
>
> The consensus that I thought we had reached was to let 83xx specify  
> the interrupt in the controller node (to make things simple for a  
> driver using the shared summary register rather than registering  
> four handlers for the same IRQ), but require that it also be in the  
> channel node, and that if there is an interrupt in the controller  
> node, that it be the same as in all the channels.

This was my understanding.. however we might not be documentation that  
clearly at this point.

>> My sound driver doesn't use Extended Mode, but it does check for  
>> "fsl,8610-dma-channel".  I'm thinking that maybe I should change to  
>> to look for "elo" or "eloplus", but it would be nice if we could  
>> make the DMA node for an 86xx SoC compatible with a driver that  
>> expects "fsl,elo-dma-channel".
>
> Sure it'd be nice, but it's not possible without going back in time  
> and convincing the hardware people to make them 100% compatible.

exactly.  You forget minor things like 83xx reg set is little endian  
and 85xx/86xx is big endian.

- k

Re: [PATCH] [POWERPC] Add docs for Freescale DMA & DMA channel device tree nodes

[Kumar Gala]

On Jan 22, 2008, at 3:30 PM, Timur Tabi wrote:

> Kumar Gala wrote:
>> Signed-off-by: Zhang Wei <wei.zhang@freescale.com>
>> Signed-off-by: Ebony Zhu <ebony.zhu@freescale.com>
>> Signed-off-by: Kumar Gala <galak@kernel.crashing.org>
>> ---
>> Guys please review and make sure I got all your previous comments  
>> fixed
>> up.  I've added cell-index. and the examples should represent real  
>> HW.
>> Documentation/powerpc/booting-without-of.txt |  128 ++++++++++++++++ 
>> ++++++++++
>> 1 files changed, 128 insertions(+), 0 deletions(-)
>> diff --git a/Documentation/powerpc/booting-without-of.txt b/ 
>> Documentation/powerpc/booting-without-of.txt
>> index da98154..3584c33 100644
>> --- a/Documentation/powerpc/booting-without-of.txt
>> +++ b/Documentation/powerpc/booting-without-of.txt
>> @@ -2615,6 +2615,134 @@ platforms are moved over to use the  
>> flattened-device-tree model.
>>        - clock-frequency  : The frequency of the input clock, which  
>> typically
>>                             comes from an on-board dedicated  
>> oscillator.
>> +    * Freescale 83xx DMA Controller
>> +
>> +    Freescale PowerPC 83xx have on chip general purpose DMA  
>> controllers.
>> +
>> +    Required properties:
>> +
>> +    - compatible        : compatible list, contains 2 entries,  
>> first is
>> +			 "fsl,CHIP-dma", where CHIP is the processor
>> +			 (mpc8349, mpc8360, etc.) and the second is
>> +			 "fsl,elo-dma"
>> +    - reg               : <registers mapping for DMA general  
>> status reg>
>> +    - ranges 		: Should be defined as specified in 1) to describe  
>> the
>> +			  DMA controller channels.
>
> What does "Should be defined as specified in 1)" mean?

Its referring to section 1 of the doc on ranges.  Other nodes use this  
description for ranges. (soc, muram)

>> +    - cell-index        : controller index.  0 for controller @  
>> 0x8100
>
> This should be more generic.  I believe for each of our SoCs, we  
> designation one DMA controller to be "DMA Controller 1", and that  
> one should have a cell-index of "0".

Ok, on 83xx that controller is always at offset 0x8100.

- k