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

[Guennadi Liakhovetski]

Hi Vinod,

On Tue, 8 Oct 2013, Vinod Koul wrote:

> On Mon, Oct 07, 2013 at 10:55:56PM +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
> > > > > > > > > discarded using terminate_all right?
> > > > > > > > 
> > > > > > > > No, by the dmaengine driver as a part of the error processing.
> > > > > > > And how will that be done...?
> > > > > > 
> > > > > > Sorry, I meant - DMA descriptors with cookies #2 and #3 will be cancelled 
> > > > > > and recycled by the dmaengine driver. That's what you have to do, when 
> > > > > > processing DMA error IRQ.
> > > > > Well how do you that?
> > > > 
> > > > Mmmh, maybe I'm missing something, but isn't it a part of the common DMA 
> > > > processing? You get an error IRQ; on some DMAC types this means, that you 
> > > > have to reset the hardware, so, you perform whatever actions you have to 
> > > > do to reset the controller; you remove any descriptors from the pending 
> > > > queue; reinsert them into the free queue and let any clients run on a 
> > > > timeout. I don't think it would be a good idea to do anything more smart 
> > > > like trying to restart the current transfer or drop it and continue with 
> > > > the queue, because we don't know in what state the client hardware is, so, 
> > > > we can only let the client driver try to recover.
> > > No that would be very wrong thing to do behind clients back. Suppose you got a
> > > trasaction which returned error irq and it was generated one half of the
> > > requested transfer was done. Redoing the entrie transaction wont be right!
> > > 
> > > So I think you need to let client know the error status.
> > > 
> > > But again, is this usage fiarly common?
> > 
> > Hm, I think, the question is different: is this possible and realistic? If 
> > there's just one DMAC and one platform, I think, there should be a way to 
> > support it? There are controllers, that actually have separate error IRQ 
> > outputs and special status bits for them. Actually, see commit
> Fair enough, if this is something you commonly need to deal with then lets add a
> new callback for error reporting. I think this would be simpler and then client
> will know about the failure
> 
> On failure reporting the client should query the status to know what is pending
> for this transaction then recover accordingly

Yes, this should help, thanks!

> Will send patch for this and moving to DMA_COMPLETE as status

As for statuses: AFAICS in a non-cyclic case a dmaengine driver can 
distinguish between the following states:

1. queued: after .tx_submit(), before .device_issue_pending()
2. active: after .device_issue_pending(), before actually sending to the 
   hardware
3. in progress: sent to the hardware, waiting for completion
4. waiting for ack: completed successfully, waiting for async_tx_ack()
5. unknown: the cookie cannot be found in any of the driver's lists

Makes sense?

Thanks
Guennadi
---
Guennadi Liakhovetski, Ph.D.
Freelance Open-Source Software Developer
http://www.open-technology.de/