[v10,2/3] DMA: Freescale: Add new 8-channel DMA engine device tree nodes

From: Hongbo Zhang <hongbo.zhang@freescale.com>

Freescale QorIQ T4 and B4 introduce new 8-channel DMA engines, this patch adds
the device tree nodes for them.

Signed-off-by: Hongbo Zhang <hongbo.zhang@freescale.com>
---
 .../devicetree/bindings/powerpc/fsl/dma.txt        |   69 ++++++++++++++++
 arch/powerpc/boot/dts/fsl/b4si-post.dtsi           |    4 +-
 arch/powerpc/boot/dts/fsl/elo3-dma-0.dtsi          |   82 ++++++++++++++++++++
 arch/powerpc/boot/dts/fsl/elo3-dma-1.dtsi          |   82 ++++++++++++++++++++
 arch/powerpc/boot/dts/fsl/t4240si-post.dtsi        |    4 +-
 5 files changed, 237 insertions(+), 4 deletions(-)
 create mode 100644 arch/powerpc/boot/dts/fsl/elo3-dma-0.dtsi
 create mode 100644 arch/powerpc/boot/dts/fsl/elo3-dma-1.dtsi

On 09/18/2013 04:15 AM, hongbo.zhang@freescale.com wrote:
> From: Hongbo Zhang <hongbo.zhang@freescale.com>
> 
> Freescale QorIQ T4 and B4 introduce new 8-channel DMA engines, this patch adds
> the device tree nodes for them.

> diff --git a/Documentation/devicetree/bindings/powerpc/fsl/dma.txt b/Documentation/devicetree/bindings/powerpc/fsl/dma.txt

> +Required properties:
> +
> +- compatible        : must include "fsl,elo3-dma"
> +- reg               : DMA General Status Registers, i.e. DGSR0 which contains
> +                      status for channel 1~4, and DGSR1 for channel 5~8

Is that a single entry, which is large enough to cover both registers,
or a pair of entries, one per register? Reading the text, I might assume
the former, but looking at the examples, it's the latter.

...
 +Example:
> +dma@100300 {
> +	#address-cells = <1>;
> +	#size-cells = <1>;
> +	compatible = "fsl,elo3-dma";
> +	reg = <0x100300 0x4>,
> +	      <0x100600 0x4>;

On 09/24/2013 01:04 AM, Stephen Warren wrote:
> On 09/18/2013 04:15 AM, hongbo.zhang@freescale.com wrote:
>> From: Hongbo Zhang <hongbo.zhang@freescale.com>
>>
>> Freescale QorIQ T4 and B4 introduce new 8-channel DMA engines, this patch adds
>> the device tree nodes for them.
>> diff --git a/Documentation/devicetree/bindings/powerpc/fsl/dma.txt b/Documentation/devicetree/bindings/powerpc/fsl/dma.txt
>> +Required properties:
>> +
>> +- compatible        : must include "fsl,elo3-dma"
>> +- reg               : DMA General Status Registers, i.e. DGSR0 which contains
>> +                      status for channel 1~4, and DGSR1 for channel 5~8
> Is that a single entry, which is large enough to cover both registers,
> or a pair of entries, one per register? Reading the text, I might assume
> the former, but looking at the examples, it's the latter.
My impression is that I cannot tell it is one larger entry or two 
entries by reading the description text, but the example gives the answer.
Is it so important to specify it is only one entry or entries list?
I prefer language as concise as possible, especially for the common 
properties such as reg and interrupt (eg the reg is implicitly offset 
and length of registers, can be continuous or not), it is difficult or 
unnecessary or impossible to describe much details, the example can also 
work as a complementary description, otherwise no need to put an example 
in the binding document.

> ...
>   +Example:
>> +dma@100300 {
>> +	#address-cells = <1>;
>> +	#size-cells = <1>;
>> +	compatible = "fsl,elo3-dma";
>> +	reg = <0x100300 0x4>,
>> +	      <0x100600 0x4>;
>

On 09/24/2013 04:30 AM, Hongbo Zhang wrote:
> On 09/24/2013 01:04 AM, Stephen Warren wrote:
>> On 09/18/2013 04:15 AM, hongbo.zhang@freescale.com wrote:
>>> From: Hongbo Zhang <hongbo.zhang@freescale.com>
>>>
>>> Freescale QorIQ T4 and B4 introduce new 8-channel DMA engines, this
>>> patch adds
>>> the device tree nodes for them.
>>> diff --git a/Documentation/devicetree/bindings/powerpc/fsl/dma.txt
>>> b/Documentation/devicetree/bindings/powerpc/fsl/dma.txt
>>> +Required properties:
>>> +
>>> +- compatible        : must include "fsl,elo3-dma"
>>> +- reg               : DMA General Status Registers, i.e. DGSR0 which
>>> contains
>>> +                      status for channel 1~4, and DGSR1 for channel 5~8
>> Is that a single entry, which is large enough to cover both registers,
>> or a pair of entries, one per register? Reading the text, I might assume
>> the former, but looking at the examples, it's the latter.
> My impression is that I cannot tell it is one larger entry or two
> entries by reading the description text, but the example gives the answer.
> Is it so important to specify it is only one entry or entries list?
> I prefer language as concise as possible, especially for the common
> properties such as reg and interrupt (eg the reg is implicitly offset
> and length of registers, can be continuous or not), it is difficult or
> unnecessary or impossible to describe much details, the example can also
> work as a complementary description, otherwise no need to put an example
> in the binding document.

The description of the properties should fully describe them. The
example is just an example, not a specification of the properties.

On 09/25/2013 01:31 AM, Stephen Warren wrote:
> On 09/24/2013 04:30 AM, Hongbo Zhang wrote:
>> On 09/24/2013 01:04 AM, Stephen Warren wrote:
>>> On 09/18/2013 04:15 AM, hongbo.zhang@freescale.com wrote:
>>>> From: Hongbo Zhang <hongbo.zhang@freescale.com>
>>>>
>>>> Freescale QorIQ T4 and B4 introduce new 8-channel DMA engines, this
>>>> patch adds
>>>> the device tree nodes for them.
>>>> diff --git a/Documentation/devicetree/bindings/powerpc/fsl/dma.txt
>>>> b/Documentation/devicetree/bindings/powerpc/fsl/dma.txt
>>>> +Required properties:
>>>> +
>>>> +- compatible        : must include "fsl,elo3-dma"
>>>> +- reg               : DMA General Status Registers, i.e. DGSR0 which
>>>> contains
>>>> +                      status for channel 1~4, and DGSR1 for channel 5~8
>>> Is that a single entry, which is large enough to cover both registers,
>>> or a pair of entries, one per register? Reading the text, I might assume
>>> the former, but looking at the examples, it's the latter.
>> My impression is that I cannot tell it is one larger entry or two
>> entries by reading the description text, but the example gives the answer.
>> Is it so important to specify it is only one entry or entries list?
>> I prefer language as concise as possible, especially for the common
>> properties such as reg and interrupt (eg the reg is implicitly offset
>> and length of registers, can be continuous or not), it is difficult or
>> unnecessary or impossible to describe much details, the example can also
>> work as a complementary description, otherwise no need to put an example
>> in the binding document.
> The description of the properties should fully describe them. The
> example is just an example, not a specification of the properties.
>
It is OK for me to update the description like this:
reg:    containing two entries for DMA General Status Registers, i.e. 
DGSR0 which contains + status for channel 1~4, and DGSR1 for channel 5~8

and let me wait one or more days to see if other reviewers/maintainers 
have further comments before I send our another iteration.

By the way, I know maybe it is difficult, but why not introduce a 
document of maintaining rules for the dt binding docs? we have dedicated 
maintainers for this part now. Description language from one submitter 
cannot satisfy every reviewer/maintainer, for a reg property, is it 
necessary to say "offset and length", to say "how many entries", to say 
"register functions and even names"? If there is specific rules (even 
with good examples), it will be convenient for both submitter and 
reviewers. Without rules/guidelines, new submitter would like to follow 
old bad samples.

On Wed, 2013-09-25 at 15:35 +0800, Hongbo Zhang wrote:
> By the way, I know maybe it is difficult, but why not introduce a 
> document of maintaining rules for the dt binding docs? we have dedicated 
> maintainers for this part now. Description language from one submitter 
> cannot satisfy every reviewer/maintainer, for a reg property, is it 
> necessary to say "offset and length",

Don't say "offset and length".  It's both redundant with the base
definition of the reg property, and overly specific because it makes
assumptions about how the parent node's ranges are set up (sometimes we
want to be that specific, but usually not).

> to say "how many entries", to say "register functions and even names"?

If there's more than one
entry/resource/whatever-we-decide-to-call-it-but-let's-pick-something-canonical, then say how many there are and what each one means.

-Scott

On Wed, Sep 25, 2013 at 08:46:32PM -0500, Scott Wood wrote:
> On Wed, 2013-09-25 at 15:35 +0800, Hongbo Zhang wrote:
> > By the way, I know maybe it is difficult, but why not introduce a 
> > document of maintaining rules for the dt binding docs? we have dedicated 
> > maintainers for this part now. Description language from one submitter 
> > cannot satisfy every reviewer/maintainer, for a reg property, is it 
> > necessary to say "offset and length",
> 
> Don't say "offset and length".  It's both redundant with the base
> definition of the reg property, and overly specific because it makes
> assumptions about how the parent node's ranges are set up (sometimes we
> want to be that specific, but usually not).

To look at it another way, the format of the 'reg' property is defined
by the parent bus's binding, not the binding of the node itself.

On 09/26/2013 10:28 AM, David Gibson wrote:
> On Wed, Sep 25, 2013 at 08:46:32PM -0500, Scott Wood wrote:
>> On Wed, 2013-09-25 at 15:35 +0800, Hongbo Zhang wrote:
>>> By the way, I know maybe it is difficult, but why not introduce a
>>> document of maintaining rules for the dt binding docs? we have dedicated
>>> maintainers for this part now. Description language from one submitter
>>> cannot satisfy every reviewer/maintainer, for a reg property, is it
>>> necessary to say "offset and length",
>> Don't say "offset and length".  It's both redundant with the base
>> definition of the reg property, and overly specific because it makes
>> assumptions about how the parent node's ranges are set up (sometimes we
>> want to be that specific, but usually not).

Thanks for your answer Scott.
In fact my questions are mainly sample questions to file the necessary 
rules of dt binding.
> To look at it another way, the format of the 'reg' property is defined
> by the parent bus's binding, not the binding of the node itself.
>
Whatever the rule is, if it is reasonable and accepted, just as I said, 
we need to file it.