Cyclic DMA - callback properties and tx_status residue

[Russell King - ARM Linux]

On Fri, May 11, 2012 at 02:24:10PM +0200, Linus Walleij wrote:
> > + * @residue: is defined as:
> > + *   - for completed descriptor: 0
> > + *   - for descriptors which are in DMA_PAUSED, DMA_IN_PROGRESS:
> > + *     length - (current_addr - start_addr), where:
> > + *             length = descriptor dma length
> > + *             current_addr = current dma pointer queried for dma channel
> > + *             start_addr: starting address of this descriptor
> > + *   This is mandatory and needs to be correctly filled by driver
> >  */
> > Does this make it clear?
> 
> Looks good to me.

There's a problem with defining it that way.  Consider a scatterlist.
What does 'current address' and 'start address' mean with respect to
those transfers?

Rather than trying to define this in terms of mathematics, which will
always lead to this kind of confusion, use English instead.

- for descriptors which are in progress or paused:
  the number of bytes yet to be transferred to or from the memory for
  MEM2DEV or DEV2MEM transfers.

This leaves MEM2MEM and DEV2DEV transfers ambiguous - both suffer from
the problem of whether you use the source or destination pointers/lengths
to calculate the residue.

For MEM2MEM, I would suggest these should either be reported as complete
or not-complete in their entirety.  (In other words, either their full
transfer size or zero.)  It's racy to try to do anything else with an
in-progress transfer...

DEV2DEV I've not thought about, and I'm rather wishing we didn't have
that transfer type...