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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 




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@xxxxxxxxxxxxx wrote:
From: Hongbo Zhang <hongbo.zhang@xxxxxxxxxxxxx>

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.



--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html




[Index of Archives]     [Device Tree Compilter]     [Device Tree Spec]     [Linux Driver Backports]     [Video for Linux]     [Linux USB Devel]     [Linux PCI Devel]     [Linux Audio Users]     [Linux Kernel]     [Linux SCSI]     [XFree86]     [Yosemite Backpacking]
  Powered by Linux