[PATCH] dmaengine: rcar-dmac: Document SoC specific bindings

[PATCH] dmaengine: rcar-dmac: Document SoC specific bindings

[Simon Horman]

In general Renesas hardware is not documented to the extent where the
relationship between IP blocks on different SoCs can be assumed although
they may appear to operate the same way. Furthermore the documentation
typically does not specify a version for individual IP blocks. For these
reasons a convention of using the SoC name in place of a version and
providing SoC-specific compat strings has been adopted.

Although not universally liked this convention is used in the bindings for
most drivers for Renesas hardware. The purpose of this patch is to
update the Renesas R-Car DMA Controller driver to follow this convention.

Cc: devicetree@vger.kernel.org
Cc: Magnus Damm <magnus.damm@gmail.com>
Cc: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Signed-off-by: Simon Horman <horms+renesas@verge.net.au>
---
 Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

Once this has been merged I intend to provide follow-up patches
to use these new compat strings in the relevant dtsi files.

diff --git a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt
index 09daeef1ff22..5b902ac8d97e 100644
--- a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt
+++ b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt
@@ -14,7 +14,14 @@ not described in these device tree bindings.
 
 Required Properties:
 
-- compatible: must contain "renesas,rcar-dmac"
+- compatible: "renesas,dmac-<soctype>", "renesas,rcar-dmac" as fallback.
+	      Examples with soctypes are:
+		- "renesas,dmac-r8a7790" (R-Car H2)
+		- "renesas,dmac-r8a7791" (R-Car M2-W)
+		- "renesas,dmac-r8a7792" (R-Car V2H)
+		- "renesas,dmac-r8a7793" (R-Car M2-N)
+		- "renesas,dmac-r8a7794" (R-Car E2)
+		- "renesas,dmac-r8a7795" (R-Car H3)
 
 - reg: base address and length of the registers block for the DMAC
 
@@ -35,7 +42,7 @@ Required Properties:
 Example: R8A7790 (R-Car H2) SYS-DMACs
 
 	dmac0: dma-controller@e6700000 {
-		compatible = "renesas,rcar-dmac";
+		compatible = "renesas,dmac-r8a7790", "renesas,rcar-dmac";
 		reg = <0 0xe6700000 0 0x20000>;
 		interrupts = <0 197 IRQ_TYPE_LEVEL_HIGH
 			      0 200 IRQ_TYPE_LEVEL_HIGH
@@ -65,7 +72,7 @@ Example: R8A7790 (R-Car H2) SYS-DMACs
 	};
 
 	dmac1: dma-controller@e6720000 {
-		compatible = "renesas,rcar-dmac";
+		compatible = "renesas,dmac-r8a7790", "renesas,rcar-dmac";
 		reg = <0 0xe6720000 0 0x20000>;
 		interrupts = <0 220 IRQ_TYPE_LEVEL_HIGH
 			      0 216 IRQ_TYPE_LEVEL_HIGH
-- 
2.1.4

Re: [PATCH] dmaengine: rcar-dmac: Document SoC specific bindings

[Geert Uytterhoeven]

Hi Simon,

On Thu, Nov 12, 2015 at 2:53 AM, Simon Horman
<horms+renesas@verge.net.au> wrote:
> In general Renesas hardware is not documented to the extent where the
> relationship between IP blocks on different SoCs can be assumed although
> they may appear to operate the same way. Furthermore the documentation
> typically does not specify a version for individual IP blocks. For these
> reasons a convention of using the SoC name in place of a version and
> providing SoC-specific compat strings has been adopted.
>
> Although not universally liked this convention is used in the bindings for
> most drivers for Renesas hardware. The purpose of this patch is to
> update the Renesas R-Car DMA Controller driver to follow this convention.

Thanks for tackling this!

> Cc: devicetree@vger.kernel.org
> Cc: Magnus Damm <magnus.damm@gmail.com>
> Cc: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
> Signed-off-by: Simon Horman <horms+renesas@verge.net.au>

Acked-by: Geert Uytterhoeven <geert+renesas@glider.be>

Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

Re: [PATCH] dmaengine: rcar-dmac: Document SoC specific bindings

[Rob Herring]

On Thu, Nov 12, 2015 at 10:53:59AM +0900, Simon Horman wrote:
> In general Renesas hardware is not documented to the extent where the
> relationship between IP blocks on different SoCs can be assumed although
> they may appear to operate the same way. Furthermore the documentation
> typically does not specify a version for individual IP blocks. For these
> reasons a convention of using the SoC name in place of a version and
> providing SoC-specific compat strings has been adopted.

Everyone learns this the hard way. :)

> Although not universally liked this convention is used in the bindings for
> most drivers for Renesas hardware. The purpose of this patch is to
> update the Renesas R-Car DMA Controller driver to follow this convention.
> 
> Cc: devicetree@vger.kernel.org
> Cc: Magnus Damm <magnus.damm@gmail.com>
> Cc: Laurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
> Signed-off-by: Simon Horman <horms+renesas@verge.net.au>
> ---
>  Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt | 13 ++++++++++---
>  1 file changed, 10 insertions(+), 3 deletions(-)
> 
> Once this has been merged I intend to provide follow-up patches
> to use these new compat strings in the relevant dtsi files.
> 
> diff --git a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt
> index 09daeef1ff22..5b902ac8d97e 100644
> --- a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt
> +++ b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt
> @@ -14,7 +14,14 @@ not described in these device tree bindings.
>  
>  Required Properties:
>  
> -- compatible: must contain "renesas,rcar-dmac"
> +- compatible: "renesas,dmac-<soctype>", "renesas,rcar-dmac" as fallback.

Somehow Renesas has ended up being backwards from everyone else that 
does <vendor>,<chip>-<block>. Oh well...

Acked-by: Rob Herring <robh@kernel.org>

Rob

Re: [PATCH] dmaengine: rcar-dmac: Document SoC specific bindings

[Geert Uytterhoeven]

Hi Rob,

On Fri, Nov 13, 2015 at 12:28 AM, Rob Herring <robh@kernel.org> wrote:
>> diff --git a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt
>> index 09daeef1ff22..5b902ac8d97e 100644
>> --- a/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt
>> +++ b/Documentation/devicetree/bindings/dma/renesas,rcar-dmac.txt
>> @@ -14,7 +14,14 @@ not described in these device tree bindings.
>>
>>  Required Properties:
>>
>> -- compatible: must contain "renesas,rcar-dmac"
>> +- compatible: "renesas,dmac-<soctype>", "renesas,rcar-dmac" as fallback.
>
> Somehow Renesas has ended up being backwards from everyone else that
> does <vendor>,<chip>-<block>. Oh well...

I know. Renesas has a mix of both :-(

As in this case the generic one does follow the "<vendor>,<family>-<block>"
pattern ("renesas,rcar-dmac"), it may make sense to use
"renesas,<soctype>-dmac", to avoid having a mix in the bindings for the same
block.

Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

Re: [PATCH] dmaengine: rcar-dmac: Document SoC specific bindings

[Vinod Koul]

On Thu, Nov 12, 2015 at 10:53:59AM +0900, Simon Horman wrote:
> In general Renesas hardware is not documented to the extent where the
> relationship between IP blocks on different SoCs can be assumed although
> they may appear to operate the same way. Furthermore the documentation
> typically does not specify a version for individual IP blocks. For these
> reasons a convention of using the SoC name in place of a version and
> providing SoC-specific compat strings has been adopted.
> 
> Although not universally liked this convention is used in the bindings for
> most drivers for Renesas hardware. The purpose of this patch is to
> update the Renesas R-Car DMA Controller driver to follow this convention.

Applied, thanks

-- 
~Vinod

Re: [PATCH] dmaengine: rcar-dmac: Document SoC specific bindings

[Geert Uytterhoeven]

Hi Vinod,

On Mon, Nov 16, 2015 at 4:55 AM, Vinod Koul <vinod.koul@intel.com> wrote:
> On Thu, Nov 12, 2015 at 10:53:59AM +0900, Simon Horman wrote:
>> In general Renesas hardware is not documented to the extent where the
>> relationship between IP blocks on different SoCs can be assumed although
>> they may appear to operate the same way. Furthermore the documentation
>> typically does not specify a version for individual IP blocks. For these
>> reasons a convention of using the SoC name in place of a version and
>> providing SoC-specific compat strings has been adopted.
>>
>> Although not universally liked this convention is used in the bindings for
>> most drivers for Renesas hardware. The purpose of this patch is to
>> update the Renesas R-Car DMA Controller driver to follow this convention.
>
> Applied, thanks

This patch (and this patch only) has disappeared from your next branch between
January 6 and 7, and thus wasn't included in your pull request for v4.5.

Was there a specific reason for that, or was it just an oversight?

Note that the added compatible values in in use (in arm-soc/for-next).

Thanks!

Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

Re: [PATCH] dmaengine: rcar-dmac: Document SoC specific bindings

[Vinod Koul]

On Thu, Jan 14, 2016 at 11:09:47AM +0100, Geert Uytterhoeven wrote:
> Hi Vinod,
> 
> On Mon, Nov 16, 2015 at 4:55 AM, Vinod Koul <vinod.koul@intel.com> wrote:
> > On Thu, Nov 12, 2015 at 10:53:59AM +0900, Simon Horman wrote:
> >> In general Renesas hardware is not documented to the extent where the
> >> relationship between IP blocks on different SoCs can be assumed although
> >> they may appear to operate the same way. Furthermore the documentation
> >> typically does not specify a version for individual IP blocks. For these
> >> reasons a convention of using the SoC name in place of a version and
> >> providing SoC-specific compat strings has been adopted.
> >>
> >> Although not universally liked this convention is used in the bindings for
> >> most drivers for Renesas hardware. The purpose of this patch is to
> >> update the Renesas R-Car DMA Controller driver to follow this convention.
> >
> > Applied, thanks
> 
> This patch (and this patch only) has disappeared from your next branch between
> January 6 and 7, and thus wasn't included in your pull request for v4.5.
> 
> Was there a specific reason for that, or was it just an oversight?
> 
> Note that the added compatible values in in use (in arm-soc/for-next).


Hi Geert,

That only means I messed up. I apply patches to for-linus or topic branches
and then merge all topics to for-linus and send that to Linus.

In this case I didn't see this in any of the topics or for-linus which means
I applied to next which I usually trash and keep rebuiling on latest -rc.

Now git helped me track this commit on a deleted branch (which reminds us
what a wonderful thing git is... screwed up, dont worrry git is our
superhero to rescue).

I have cherry-picked this patch and applied to for-4.5 branch and will
send to Linus in few days along with few more fixes.

Thanks for reporting
-- 
~Vinod