[1/7] dmaengine: st_fdma: Add STMicroelectronics FDMA DT binding documentation

Message ID 1436371888-27863-2-git-send-email-peter.griffin@linaro.org
State New
Headers show

Commit Message

Peter Griffin July 8, 2015, 4:11 p.m.
This patch adds the DT binding documentation for the FDMA constroller
found on STi based chipsets from STMicroelectronics.

Signed-off-by: Ludovic Barre <ludovic.barre@st.com>
Signed-off-by: Peter Griffin <peter.griffin@linaro.org>
---
 Documentation/devicetree/bindings/dma/st_fdma.txt | 76 +++++++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/dma/st_fdma.txt

Comments

Peter Griffin Aug. 25, 2015, 5:08 p.m. | #1
Hi Vinod,

Thanks for reviewing.

On Wed, 19 Aug 2015, Vinod Koul wrote:

> On Wed, Jul 08, 2015 at 05:11:22PM +0100, Peter Griffin wrote:
> > This patch adds the DT binding documentation for the FDMA constroller
> > found on STi based chipsets from STMicroelectronics.
> > 
> > Signed-off-by: Ludovic Barre <ludovic.barre@st.com>
> > Signed-off-by: Peter Griffin <peter.griffin@linaro.org>
> > ---
> >  Documentation/devicetree/bindings/dma/st_fdma.txt | 76 +++++++++++++++++++++++
> >  1 file changed, 76 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/dma/st_fdma.txt
> > 
> > diff --git a/Documentation/devicetree/bindings/dma/st_fdma.txt b/Documentation/devicetree/bindings/dma/st_fdma.txt
> > new file mode 100644
> > index 0000000..1ec7470
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/dma/st_fdma.txt
> > @@ -0,0 +1,76 @@
> > +* STMicroelectronics Flexible Direct Memory Access Device Tree bindings
> > +
> > +The FDMA is a general-purpose direct memory access controller capable of
> > +supporting 16 independent DMA channels. It accepts up to 32 DMA requests.
> > +The FDMA is based on a Slim processor which require a firmware.
> > +
> > +* FDMA Controller
> > +
> > +Required properties:
> > +- compatible	: Should be "st,fdma_mpe31"
> > +- reg		: Should contain DMA registers location and length
> > +- interrupts	: Should contain one interrupt shared by all channel
> 
> s/channel/channels

Will fix in v2.

> 
> > +- dma-channels	: Number of channels supported by the controller
> > +- #dma-cells	: Must be <3>.
> 
> any reason three?

Yes, it is documented further down in the file under DMA Client.

To make it clearer in V2 I could change to

"- #dma-cells	: Must be <3>. See DMA client section below"?

regards,

Peter.
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Lee Jones Aug. 26, 2015, 7:12 a.m. | #2
On Tue, 25 Aug 2015, Peter Griffin wrote:

> Hi Vinod,
> 
> Thanks for reviewing.
> 
> On Wed, 19 Aug 2015, Vinod Koul wrote:
> 
> > On Wed, Jul 08, 2015 at 05:11:22PM +0100, Peter Griffin wrote:
> > > This patch adds the DT binding documentation for the FDMA constroller
> > > found on STi based chipsets from STMicroelectronics.
> > > 
> > > Signed-off-by: Ludovic Barre <ludovic.barre@st.com>
> > > Signed-off-by: Peter Griffin <peter.griffin@linaro.org>
> > > ---
> > >  Documentation/devicetree/bindings/dma/st_fdma.txt | 76 +++++++++++++++++++++++
> > >  1 file changed, 76 insertions(+)
> > >  create mode 100644 Documentation/devicetree/bindings/dma/st_fdma.txt
> > > 
> > > diff --git a/Documentation/devicetree/bindings/dma/st_fdma.txt b/Documentation/devicetree/bindings/dma/st_fdma.txt
> > > new file mode 100644
> > > index 0000000..1ec7470
> > > --- /dev/null
> > > +++ b/Documentation/devicetree/bindings/dma/st_fdma.txt
> > > @@ -0,0 +1,76 @@
> > > +* STMicroelectronics Flexible Direct Memory Access Device Tree bindings
> > > +
> > > +The FDMA is a general-purpose direct memory access controller capable of
> > > +supporting 16 independent DMA channels. It accepts up to 32 DMA requests.
> > > +The FDMA is based on a Slim processor which require a firmware.
> > > +
> > > +* FDMA Controller
> > > +
> > > +Required properties:
> > > +- compatible	: Should be "st,fdma_mpe31"
> > > +- reg		: Should contain DMA registers location and length
> > > +- interrupts	: Should contain one interrupt shared by all channel
> > 
> > s/channel/channels
> 
> Will fix in v2.
> 
> > 
> > > +- dma-channels	: Number of channels supported by the controller
> > > +- #dma-cells	: Must be <3>.
> > 
> > any reason three?
> 
> Yes, it is documented further down in the file under DMA Client.
> 
> To make it clearer in V2 I could change to
> 
> "- #dma-cells	: Must be <3>. See DMA client section below"?

- #dma-cells	: Must be <3>
			1st cell: Phandle to       ... <blah>
			2nd cell: DMA channel      ... <blah>
			3rd cell: Flags describing ... <blah>
Peter Griffin Sept. 3, 2015, 9:18 a.m. | #3
Hi Lee,

On Wed, 26 Aug 2015, Lee Jones wrote:

> On Tue, 25 Aug 2015, Peter Griffin wrote:
> 
> > Hi Vinod,
> > 
> > Thanks for reviewing.
> > 
> > On Wed, 19 Aug 2015, Vinod Koul wrote:
> > 
> > > On Wed, Jul 08, 2015 at 05:11:22PM +0100, Peter Griffin wrote:
> > > > This patch adds the DT binding documentation for the FDMA constroller
> > > > found on STi based chipsets from STMicroelectronics.
> > > > 
> > > > Signed-off-by: Ludovic Barre <ludovic.barre@st.com>
> > > > Signed-off-by: Peter Griffin <peter.griffin@linaro.org>
> > > > ---
> > > >  Documentation/devicetree/bindings/dma/st_fdma.txt | 76 +++++++++++++++++++++++
> > > >  1 file changed, 76 insertions(+)
> > > >  create mode 100644 Documentation/devicetree/bindings/dma/st_fdma.txt
> > > > 
> > > > diff --git a/Documentation/devicetree/bindings/dma/st_fdma.txt b/Documentation/devicetree/bindings/dma/st_fdma.txt
> > > > new file mode 100644
> > > > index 0000000..1ec7470
> > > > --- /dev/null
> > > > +++ b/Documentation/devicetree/bindings/dma/st_fdma.txt
> > > > @@ -0,0 +1,76 @@
> > > > +* STMicroelectronics Flexible Direct Memory Access Device Tree bindings
> > > > +
> > > > +The FDMA is a general-purpose direct memory access controller capable of
> > > > +supporting 16 independent DMA channels. It accepts up to 32 DMA requests.
> > > > +The FDMA is based on a Slim processor which require a firmware.
> > > > +
> > > > +* FDMA Controller
> > > > +
> > > > +Required properties:
> > > > +- compatible	: Should be "st,fdma_mpe31"
> > > > +- reg		: Should contain DMA registers location and length
> > > > +- interrupts	: Should contain one interrupt shared by all channel
> > > 
> > > s/channel/channels
> > 
> > Will fix in v2.
> > 
> > > 
> > > > +- dma-channels	: Number of channels supported by the controller
> > > > +- #dma-cells	: Must be <3>.
> > > 
> > > any reason three?
> > 
> > Yes, it is documented further down in the file under DMA Client.
> > 
> > To make it clearer in V2 I could change to
> > 
> > "- #dma-cells	: Must be <3>. See DMA client section below"?
> 
> - #dma-cells	: Must be <3>
> 			1st cell: Phandle to       ... <blah>
> 			2nd cell: DMA channel      ... <blah>
> 			3rd cell: Flags describing ... <blah>  

I'd prefer not to document it twice in the same file as it is
almost 20 lines long. IMHO it makes more sense to document it under
the dma-client section like it is done presently, because when writing a
dma-client node you need to know what these things mean.

When writing a controller node all you only need to know is
"Must be <3>". A more avid reader now has a nice pointer to scroll
down if they wish to find out more.

regards,

Peter.
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

Patch

diff --git a/Documentation/devicetree/bindings/dma/st_fdma.txt b/Documentation/devicetree/bindings/dma/st_fdma.txt
new file mode 100644
index 0000000..1ec7470
--- /dev/null
+++ b/Documentation/devicetree/bindings/dma/st_fdma.txt
@@ -0,0 +1,76 @@ 
+* STMicroelectronics Flexible Direct Memory Access Device Tree bindings
+
+The FDMA is a general-purpose direct memory access controller capable of
+supporting 16 independent DMA channels. It accepts up to 32 DMA requests.
+The FDMA is based on a Slim processor which require a firmware.
+
+* FDMA Controller
+
+Required properties:
+- compatible	: Should be "st,fdma_mpe31"
+- reg		: Should contain DMA registers location and length
+- interrupts	: Should contain one interrupt shared by all channel
+- dma-channels	: Number of channels supported by the controller
+- #dma-cells	: Must be <3>.
+- st,fw-name	: Should contain the name of the firmware to be loaded
+- clocks	: Must contain an entry for each name in clock-names
+- clock-names	: Must contain "fdma_slim, fdma_hi, fdma_low, fdma_ic" entries
+See: Documentation/devicetree/bindings/clock/clock-bindings.txt
+
+
+Example:
+
+	fdma1: fdma-app@1 {
+		compatible = "st,fdma_mpe31";
+		reg = <0x8e40000 0x20000>;
+		interrupts = <GIC_SPI 7 IRQ_TYPE_NONE>;
+		dma-channels = <16>;
+		#dma-cells = <3>;
+		st,fw-name = "fdma_STiH407_1.elf";
+		clocks = <&CLK_S_C0_FLEXGEN CLK_FDMA>,
+			 <&CLK_S_C0_FLEXGEN CLK_TX_ICN_DMU>,
+			 <&CLK_S_C0_FLEXGEN CLK_TX_ICN_DMU>,
+			 <&CLK_S_C0_FLEXGEN CLK_EXT2F_A9>;
+		clock-names = "fdma_slim",
+			      "fdma_hi",
+			      "fdma_low",
+			      "fdma_ic";
+
+* DMA client
+
+Required properties:
+- dmas: Comma separated list of dma channel requests
+- dma-names: Names of the aforementioned requested channels
+
+Each dmas request consists of 4 cells:
+1. A phandle pointing to the FDMA controller
+2. The request line number
+3. A 32bit mask specifying (see include/linux/platform_data/dma-st-fdma.h)
+ -bit 2-0: Holdoff value, dreq will be masked for
+	0x0: 0-0.5us
+	0x1: 0.5-1us
+	0x2: 1-1.5us
+ -bit 17: data swap
+	0x0: disabled
+	0x1: enabled
+ -bit 21: Increment Address
+	0x0: no address increment between transfers
+	0x1: increment address between transfers
+ -bit 22: 2 STBus Initiator Coprocessor interface
+	0x0: high priority port
+	0x1: low priority port
+4. transfers type
+ 0 free running
+ 1 paced
+
+Example:
+
+	snd_uni_player2: snd-uni-player@2 {
+		compatible = "st,snd_uni_player";
+		status = "okay";
+		reg = <0x8D82000  0x158>;
+		interrupts = <GIC_SPI 86 IRQ_TYPE_NONE>;
+		version = <5>;
+		dmas = <&fdma0 4 0 1>;
+		dma-names = "tx";
+		description = "Uni Player #2 (DAC)";