[PATCH] DMA: extend documentation to provide more API details

[Vinod Koul]

On Wed, Oct 16, 2013 at 01:33:44PM -0600, Stephen Warren wrote:
> On 10/08/2013 07:34 PM, Dan Williams wrote:
> > On Mon, Oct 7, 2013 at 3:39 AM, Vinod Koul <vinod.koul at intel.com> wrote:
> >> On Mon, Oct 07, 2013 at 12:17:28PM +0100, Russell King - ARM Linux wrote:
> ...
> >>> What may be better is to change the wording here: not DMA_SUCCESS but
> >>> DMA_COMPLETED.  That doesn't imply that it has been successful, merely
> >>> that the DMA engine has finished with the transaction.
> >>
> >> Agreed that its not indication of success but of DMA completetion. I have seen
> >> cases where slave perhiphral got stuck while sending last FIFO but since DMA
> >> finished transferiing to FIFO it says complete.
> 
> In that case, the DMA *has* completed. DMA is the transfer into the
> FIFO, not the handling of the FIFO content by the peripheral.
> 
> >> Dan do you agree?
> > 
> > Yes, it's an indication of completion, not necessarily success.
> 
> Surely by definition, a DMA can't *complete* without being successful.
> If the DMA failed, then it didn't complete, but rather must have been
> aborted or error'd out, without completing the whole transfer.
DMA means transferring of data, and that is what DMA compeletion would mean.
Once the data has left the DMA FIFO, we don't know if it filled up the memory
propery or get stuck in periphral FIFO, the dmaengine would have no knowledge or
control of it. So it can't claim the transfer was success from a data point of
view, hence the rename now!

~Vinod
--