| Message ID | 1431626006-1708-6-git-send-email-robert.jarzmik@free.fr (mailing list archive) |
|---|---|
| State | Changes Requested |
| Headers | show |
Hi Robert, On Thu, May 14, 2015 at 07:53:26PM +0200, Robert Jarzmik wrote: > Add documentation about acking the transfers, and their > reusability. > > Signed-off-by: Robert Jarzmik <robert.jarzmik@free.fr> > --- > Documentation/dmaengine/provider.txt | 11 ++++++----- > 1 file changed, 6 insertions(+), 5 deletions(-) > > diff --git a/Documentation/dmaengine/provider.txt b/Documentation/dmaengine/provider.txt > index 05d2280..33a81ce 100644 > --- a/Documentation/dmaengine/provider.txt > +++ b/Documentation/dmaengine/provider.txt > @@ -345,11 +345,12 @@ where to put them) > that abstracts it away. > > * DMA_CTRL_ACK > - - Undocumented feature > - - No one really has an idea of what it's about, besides being > - related to reusing the DMA transaction descriptors or having > - additional transactions added to it in the async-tx API > - - Useless in the case of the slave API > + - if set, the TX transfer can be reused after being completed. Your sentences should start with an upper-case letter. > + - there is a guarantee the TX won't be freed until it is acked > + by async_tx_ack() We never talked about what a "TX transfer" is in the documentation. That should be documented. > + - as a consequence, if a device driver wants to skip the dma_map_sg() and > + dma_unmap_sg() because the DMA'd data wasn't used, it can resubmit the > + transfer right after its completion. From a provider PoV, the data should always be mapped and / or allocated in coherent way, so I'm not sure how does that's relevant in the provider doc. Also, we should still mention that it's !slave API only. Maxime
Maxime Ripard <maxime.ripard@free-electrons.com> writes: > Hi Robert, > >> * DMA_CTRL_ACK >> - - Undocumented feature >> - - No one really has an idea of what it's about, besides being >> - related to reusing the DMA transaction descriptors or having >> - additional transactions added to it in the async-tx API >> - - Useless in the case of the slave API >> + - if set, the TX transfer can be reused after being completed. > > Your sentences should start with an upper-case letter. Ack. >> + - there is a guarantee the TX won't be freed until it is acked >> + by async_tx_ack() > > We never talked about what a "TX transfer" is in the > documentation. That should be documented. I'll remove the "TX", the transfer is widely used in this documentation. > >> + - as a consequence, if a device driver wants to skip the dma_map_sg() and >> + dma_unmap_sg() because the DMA'd data wasn't used, it can resubmit the >> + transfer right after its completion. > > From a provider PoV, the data should always be mapped and / or > allocated in coherent way, so I'm not sure how does that's relevant in > the provider doc. It's relevant because it says the mapping/unmapping is not necessary _between_ 2 submission of a transfer. This implies it is mapped, as it is a requirement for the very first submission. > Also, we should still mention that it's !slave API only. Certainly not, it's fully slave API, that's the purpose of this patch.
On Thu, May 14, 2015 at 10:31:39PM +0200, Robert Jarzmik wrote: > Maxime Ripard <maxime.ripard@free-electrons.com> writes: > > > Hi Robert, > > > >> * DMA_CTRL_ACK > >> - - Undocumented feature > >> - - No one really has an idea of what it's about, besides being > >> - related to reusing the DMA transaction descriptors or having > >> - additional transactions added to it in the async-tx API > >> - - Useless in the case of the slave API > >> + - if set, the TX transfer can be reused after being completed. > > > > Your sentences should start with an upper-case letter. > Ack. > > >> + - there is a guarantee the TX won't be freed until it is acked > >> + by async_tx_ack() > > > > We never talked about what a "TX transfer" is in the > > documentation. That should be documented. > I'll remove the "TX", the transfer is widely used in this documentation. > > > > >> + - as a consequence, if a device driver wants to skip the dma_map_sg() and > >> + dma_unmap_sg() because the DMA'd data wasn't used, it can resubmit the > >> + transfer right after its completion. > > > > From a provider PoV, the data should always be mapped and / or > > allocated in coherent way, so I'm not sure how does that's relevant in > > the provider doc. > It's relevant because it says the mapping/unmapping is not necessary _between_ 2 > submission of a transfer. This implies it is mapped, as it is a requirement for > the very first submission. > > > Also, we should still mention that it's !slave API only. > Certainly not, it's fully slave API, that's the purpose of this patch. Its is not dependent on slave, it cna be used by slave as well as other users
Vinod Koul <vinod.koul@intel.com> writes: >> > Also, we should still mention that it's !slave API only. >> Certainly not, it's fully slave API, that's the purpose of this patch. > Its is not dependent on slave, it cna be used by slave as well as other > users You're right Vinod. I will rephrase that : this applies for both slave and !slave. Cheers.
diff --git a/Documentation/dmaengine/provider.txt b/Documentation/dmaengine/provider.txt index 05d2280..33a81ce 100644 --- a/Documentation/dmaengine/provider.txt +++ b/Documentation/dmaengine/provider.txt @@ -345,11 +345,12 @@ where to put them) that abstracts it away. * DMA_CTRL_ACK - - Undocumented feature - - No one really has an idea of what it's about, besides being - related to reusing the DMA transaction descriptors or having - additional transactions added to it in the async-tx API - - Useless in the case of the slave API + - if set, the TX transfer can be reused after being completed. + - there is a guarantee the TX won't be freed until it is acked + by async_tx_ack() + - as a consequence, if a device driver wants to skip the dma_map_sg() and + dma_unmap_sg() because the DMA'd data wasn't used, it can resubmit the + transfer right after its completion. General Design Notes --------------------
Add documentation about acking the transfers, and their reusability. Signed-off-by: Robert Jarzmik <robert.jarzmik@free.fr> --- Documentation/dmaengine/provider.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-)