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

[Russell King - ARM Linux]

On Mon, Oct 07, 2013 at 12:45:33PM +0200, Guennadi Liakhovetski wrote:
> No, not something in the middle. I was thinking about
> 
> (1) cookie 1-3 are submitted
> (2) cookie 1 succeeds
> (3) a DMA error occurs, cookies 2-3 are discarded
> (4) cookie 4 is submitted and succeeds
> (5) the user requests status of cookie 2 and gets success back, AFAICS

This is a side effect of using a sequential cookie based system to indicate
whether a descriptor has succeeded or not.

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.

How a transaction gets to notify that it's been in error is a problem -
there is no mechanism to do that (part of that is because DMA engine slave
support grew out of the async_tx stuff which doesn't really have the
notion of failure.)

We can't fetch the descriptor after it has been completed, because it will
have been freed or recycled depending on the implementation.

If we want to have some way to report errors against descriptors, I think
we should augment the descriptor with another callback which gets called
(again from tasklet context) so that drivers which care about this can be
notified of errors.