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

[Stephen Warren]

On 10/16/2013 11:16 PM, Vinod Koul wrote:
> 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!

Well, I obviously don't agreee, but I guess I won't bother pursuing this.