On Tue, Dec 24, 2013 at 16:06 +0400, Alexander Popov wrote: > > --- /dev/null > +++ b/Documentation/devicetree/bindings/dma/mpc512x-dma.txt > @@ -0,0 +1,55 @@ > +* Freescale MPC512x DMA Controller > + > +[ ... ] > + > +DMA controller node properties: > + > +Required properties: > +- compatible: should be "fsl,mpc5121-dma" > +- reg: address and size of the DMA controller's register set > +- interrupts: interrupt spec for the DMA controller > + > +Optional properties: > +- #dma-cells: must be <1>, describes the number of integer cells > + needed to specify the 'dmas' property in client nodes, > + strongly recommended since common client helper code > + uses this property Given how time has passed and that we learned something in the meantime, I guess the device tree documentation would look different today than what was written back then. - I'd reference the generic interrupt bindings as well, so DTS authors need not guess what an interrupt spec looks like - the #dma-cells would become less confusing is it referenced the generic DMA binding, and just say that the value is "the length of the DMA specifier" for this provider - the property's being recommended should not get hidden in the description but should reflect in the group's caption - the binding doc shold not reference implementation details of one specific user (common client helper code) [ device tree binding doc policy? ] That one Linux driver handles both MPC5121 and MPC8308 hardware and implements the same binding in both cases should get reflected in the documentation as well. But I'm not certain whether adding MPC8308 into an MPX5121 document is better than duplicating MPC5121 information in another MPC8308 document. But it might be the lesser evil. Are there opinions, established preferences? Is an exhaustive list of compatible strings good enough since text search will match regardless of the document's filename in this case? There must have been this situation before of a component being used in one SoC and getting re-used in another SoC later, too. What's the best document to "get inspired from", i.e. how to best put this into binding document wording as well as filenames? > +[ ... ] > +Client node properties: > + > +Required properties: > +- dmas: list of DMA specifiers, consisting each of a handle > + for the DMA controller and integer cells to specify > + the channel used within the DMA controller > +- dma-names: list of identifier strings for the DMA specifiers, > + client device driver code uses these strings to > + have DMA channels looked up at the controller This certainly is wrong (it was before, I just wasn't aware back then). The phandle is not part of the specifier. And the binding should not discuss what driver code does. Since the DMA controller implements the semantics of the common DMA binding, it's unwise to duplicate the information here. Let me see how I can improve this document. Alex, it may be useful to split the code update and the binding document into separate patches. The current status already mixes the code extension and the binding update with the introduction of the document which was missing in the first place. That's why the binding doc patch is that late in the series. (Yes, my RFC "template" was rather dirty, which is why I flagged it as "RFC" in the first place.) I guess that I may have to introduce a binding doc reflecting the given current status, and update it later as new features become available. Or -- given that the hardware remains, all the knowledge is there already, just the implementations' capabilities change -- I might as well introduce a binding document including OF based DMA lookup. virtually yours Gerhard Sittig -- DENX Software Engineering GmbH, MD: Wolfgang Denk & Detlev Zundel HRB 165235 Munich, Office: Kirchenstr. 5, D-82194 Groebenzell, Germany Phone: +49-8142-66989-0 Fax: +49-8142-66989-80 Email: office@xxxxxxx -- 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
