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

[Stephen Warren <swarren@wwwdotorg.org>]

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.