DMA Engine Documentation: TX Descriptor and Submission

DMA Engine Documentation: TX Descriptor and Submission

[Federico Vaga]

Hi,

I have a new question concerning documentation.

https://www.kernel.org/doc/html/latest/driver-api/dmaengine/client.html

From this document it is not really clear, at least to me, if clients can 
consider valid the `struct dma_async_tx_descriptor` after submission to the 
DMA engine.

Clients get a TX descriptor from a DMA engine using things like 
`dmaengine_prep_*`. These calls - may - allocate new descriptors and return 
them to the caller; this may include other structures which are not visible to 
clients. So, if my understanding is correct, this means that it's the DMA 
engine that, on TX completion, releases any TX descriptor allocated by 
`dmaengine_prep_*`. This implies that the pointer that the client is using 
must be considered invalid right after `dmaengine_submit()`.

If what I understood by reading the documentation and the code is correct, 
then I think that this should be mentioned in the Documentation.
If I'm wrong, please tell me where :)

Thanks

Re: DMA Engine Documentation: TX Descriptor and Submission

[Vinod Koul]

On 28-01-19, 09:47, Federico Vaga wrote:
> Hi,
> 
> I have a new question concerning documentation.
> 
> https://www.kernel.org/doc/html/latest/driver-api/dmaengine/client.html
> 
> >From this document it is not really clear, at least to me, if clients can 
> consider valid the `struct dma_async_tx_descriptor` after submission to the 
> DMA engine.

Nope they can't and should not touch the descriptor after submission.
The client get cookie and that is supposed to be used
> 
> Clients get a TX descriptor from a DMA engine using things like 
> `dmaengine_prep_*`. These calls - may - allocate new descriptors and return 
> them to the caller; this may include other structures which are not visible to 
> clients. So, if my understanding is correct, this means that it's the DMA 
> engine that, on TX completion, releases any TX descriptor allocated by 
> `dmaengine_prep_*`. This implies that the pointer that the client is using 
> must be considered invalid right after `dmaengine_submit()`.
> If what I understood by reading the documentation and the code is correct, 
> then I think that this should be mentioned in the Documentation.
> If I'm wrong, please tell me where :)

And what exactly are you trying to do here..?

-- 
~Vinod

Re: DMA Engine Documentation: TX Descriptor and Submission

[Federico Vaga]

On February 1, 2019 4:17:50 AM UTC, Vinod Koul <vkoul@kernel.org> wrote:
>On 28-01-19, 09:47, Federico Vaga wrote:
>> Hi,
>> 
>> I have a new question concerning documentation.
>> 
>>
>https://www.kernel.org/doc/html/latest/driver-api/dmaengine/client.html
>> 
>> >From this document it is not really clear, at least to me, if
>clients can 
>> consider valid the `struct dma_async_tx_descriptor` after submission
>to the 
>> DMA engine.
>
>Nope they can't and should not touch the descriptor after submission.
>The client get cookie and that is supposed to be used

Good, thanks


>> 
>> Clients get a TX descriptor from a DMA engine using things like 
>> `dmaengine_prep_*`. These calls - may - allocate new descriptors and
>return 
>> them to the caller; this may include other structures which are not
>visible to 
>> clients. So, if my understanding is correct, this means that it's the
>DMA 
>> engine that, on TX completion, releases any TX descriptor allocated
>by 
>> `dmaengine_prep_*`. This implies that the pointer that the client is
>using 
>> must be considered invalid right after `dmaengine_submit()`.
>> If what I understood by reading the documentation and the code is
>correct, 
>> then I think that this should be mentioned in the Documentation.
>> If I'm wrong, please tell me where :)
>
>And what exactly are you trying to do here..?

What if I answer: "the right thing"? Joking. I just expressed my understanding of something which is not documented properly (my opinion). I wanted to be sure that the logic, the reasons behind are the ones that I understood. I will propose a patch to the documentation, unless you want to do it.
-- 
Inviato dal mio dispositivo Android con K-9 Mail. Perdonate la brevità.

Re: DMA Engine Documentation: TX Descriptor and Submission

[Vinod Koul]

On 01-02-19, 09:59, Federico Vaga wrote:
> 
> 
> On February 1, 2019 4:17:50 AM UTC, Vinod Koul <vkoul@kernel.org> wrote:
> >On 28-01-19, 09:47, Federico Vaga wrote:
> >> Hi,
> >> 
> >> I have a new question concerning documentation.
> >> 
> >>
> >https://www.kernel.org/doc/html/latest/driver-api/dmaengine/client.html
> >> 
> >> >From this document it is not really clear, at least to me, if
> >clients can 
> >> consider valid the `struct dma_async_tx_descriptor` after submission
> >to the 
> >> DMA engine.
> >
> >Nope they can't and should not touch the descriptor after submission.
> >The client get cookie and that is supposed to be used
> 
> Good, thanks
> 
> 
> >> 
> >> Clients get a TX descriptor from a DMA engine using things like 
> >> `dmaengine_prep_*`. These calls - may - allocate new descriptors and
> >return 
> >> them to the caller; this may include other structures which are not
> >visible to 
> >> clients. So, if my understanding is correct, this means that it's the
> >DMA 
> >> engine that, on TX completion, releases any TX descriptor allocated
> >by 
> >> `dmaengine_prep_*`. This implies that the pointer that the client is
> >using 
> >> must be considered invalid right after `dmaengine_submit()`.
> >> If what I understood by reading the documentation and the code is
> >correct, 
> >> then I think that this should be mentioned in the Documentation.
> >> If I'm wrong, please tell me where :)
> >
> >And what exactly are you trying to do here..?
> 

Please wrap your replies within 80chars

> What if I answer: "the right thing"? Joking. I just expressed my
> understanding of something which is not documented properly (my
> opinion). I wanted to be sure that the logic, the reasons behind are
> the ones that I understood. I will propose a patch to the
> documentation, unless you want to do it.  -- Inviato dal mio
> dispositivo Android con K-9 Mail. Perdonate la brevità.

Sure please feel free to send a patch :)

Mostly people ask these questions based on a driver they are working
off, and it makes sense to fix the assumptions by asking what they are
trying to achieve...

-- 
~Vinod