[PATCH] docs: dmaengine: clarify ordering rules around cookie completion

[PATCH] docs: dmaengine: clarify ordering rules around cookie completion

[Vinod Koul]

Sashiko pointed in [1] about the cookie completion order. It is good to
Document that for ensuring that dma buffer is flushed and no stale data
is seeing by consumer, we need to make sure such action is taken before
drivers invoke dma cookie completion.

[1]: https://lore.kernel.org/r/20260917072507.5BDB61F000FF@smtp.kernel.org

Signed-off-by: Vinod Koul <vkoul@kernel.org>
---
 Documentation/driver-api/dmaengine/provider.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst
index 2897ade67b39..1bcbce705659 100644
--- a/Documentation/driver-api/dmaengine/provider.rst
+++ b/Documentation/driver-api/dmaengine/provider.rst
@@ -557,6 +557,11 @@ dma_cookie_t
 - Not really relevant any more since the introduction of ``virt-dma``
   that abstracts it away.
 
+- dmaengine drivers need to ensure buffers are flushed before invoking
+  vchan_cookie_complete() or dma_cookie_complete(). This would imply a call
+  to unmapping buffers or any such architcure calls to ensure caller seeing
+  buffers are flushed is done before invoking these calls.
+
 dma_vec
 
 - A small structure that contains a DMA address and length.
-- 
2.53.0

Re: [PATCH] docs: dmaengine: clarify ordering rules around cookie completion

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] docs: typo 'architcure' and grammatical errors in dmaengine provider documentation
--

commit 5e1e4fe7c0e4434abe23aff6f6d55d9b232ea575
Author: Vinod Koul <vkoul@kernel.org>

docs: dmaengine: clarify ordering rules around cookie completion

This commit adds documentation to clarify the ordering rules for DMA cookie
completion, ensuring buffers are flushed before drivers invoke the completion.

> diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst
> index f4ed98f701c91..073ba6c0f29dc 100644
> --- a/Documentation/driver-api/dmaengine/provider.rst
> +++ b/Documentation/driver-api/dmaengine/provider.rst
> @@ -555,6 +555,11 @@ dma_cookie_t
>  - Not really relevant any more since the introduction of ``virt-dma``
>    that abstracts it away.
>  
> +- dmaengine drivers need to ensure buffers are flushed before invoking
> +  vchan_cookie_complete() or dma_cookie_complete(). This would imply a call
> +  to unmapping buffers or any such architcure calls to ensure caller seeing
> +  buffers are flushed is done before invoking these calls.

[Severity: Low]
This isn't a bug, but there is a typo here ('architcure' instead of
'architecture'), and the phrasing "to ensure caller seeing buffers are
flushed is done before invoking these calls" is grammatically awkward.

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261009093745.539924-1-vkoul@kernel.org?part=1

Re: [PATCH] docs: dmaengine: clarify ordering rules around cookie completion

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 527 bytes --]

On Fri, Oct 09, 2026 at 11:37:44AM +0200, Vinod Koul wrote:
> Sashiko pointed in [1] about the cookie completion order. It is good to
> Document that for ensuring that dma buffer is flushed and no stale data
> is seeing by consumer, we need to make sure such action is taken before
> drivers invoke dma cookie completion.
> 
> [1]: https://lore.kernel.org/r/20260917072507.5BDB61F000FF@smtp.kernel.org
> 
> Signed-off-by: Vinod Koul <vkoul@kernel.org>

Reviewed-by: Wolfram Sang <wsa+renesas@sang-engineering.com>


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] docs: dmaengine: clarify ordering rules around cookie completion

[Dave Jiang]

On 10/9/26 2:37 AM, Vinod Koul wrote:
> Sashiko pointed in [1] about the cookie completion order. It is good to
> Document that for ensuring that dma buffer is flushed and no stale data
> is seeing by consumer, we need to make sure such action is taken before
> drivers invoke dma cookie completion.
> 
> [1]: https://lore.kernel.org/r/20260917072507.5BDB61F000FF@smtp.kernel.org
> 
> Signed-off-by: Vinod Koul <vkoul@kernel.org>

Reviewed-by: Dave Jiang <dave.jiang@intel.com>

> ---
>  Documentation/driver-api/dmaengine/provider.rst | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst
> index 2897ade67b39..1bcbce705659 100644
> --- a/Documentation/driver-api/dmaengine/provider.rst
> +++ b/Documentation/driver-api/dmaengine/provider.rst
> @@ -557,6 +557,11 @@ dma_cookie_t
>  - Not really relevant any more since the introduction of ``virt-dma``
>    that abstracts it away.
>  
> +- dmaengine drivers need to ensure buffers are flushed before invoking
> +  vchan_cookie_complete() or dma_cookie_complete(). This would imply a call
> +  to unmapping buffers or any such architcure calls to ensure caller seeing
> +  buffers are flushed is done before invoking these calls.
> +
>  dma_vec
>  
>  - A small structure that contains a DMA address and length.

Re: [PATCH] docs: dmaengine: clarify ordering rules around cookie completion

[Frank Li]

On Fri, Oct 09, 2026 at 11:37:44AM +0200, Vinod Koul wrote:
> Sashiko pointed in [1] about the cookie completion order. It is good to
> Document that for ensuring that dma buffer is flushed and no stale data
> is seeing by consumer, we need to make sure such action is taken before
> drivers invoke dma cookie completion.
>
> [1]: https://lore.kernel.org/r/20260917072507.5BDB61F000FF@smtp.kernel.org
>
> Signed-off-by: Vinod Koul <vkoul@kernel.org>
> ---
>  Documentation/driver-api/dmaengine/provider.rst | 5 +++++
>  1 file changed, 5 insertions(+)
>
> diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst
> index 2897ade67b39..1bcbce705659 100644
> --- a/Documentation/driver-api/dmaengine/provider.rst
> +++ b/Documentation/driver-api/dmaengine/provider.rst
> @@ -557,6 +557,11 @@ dma_cookie_t
>  - Not really relevant any more since the introduction of ``virt-dma``
>    that abstracts it away.
>
> +- dmaengine drivers need to ensure buffers are flushed before invoking
> +  vchan_cookie_complete() or dma_cookie_complete(). This would imply a call
> +  to unmapping buffers or any such architcure calls to ensure caller seeing

Sashiko report a typo architcure

Reviewed-by: Frank Li <Frank.Li@nxp.com>

> +  buffers are flushed is done before invoking these calls.
> +
>  dma_vec
>
>  - A small structure that contains a DMA address and length.
> --
> 2.53.0
>

Re: [PATCH] docs: dmaengine: clarify ordering rules around cookie completion

[Vinod Koul]

On 09-10-26, 14:05, Frank Li wrote:
> On Fri, Oct 09, 2026 at 11:37:44AM +0200, Vinod Koul wrote:
> > Sashiko pointed in [1] about the cookie completion order. It is good to
> > Document that for ensuring that dma buffer is flushed and no stale data
> > is seeing by consumer, we need to make sure such action is taken before
> > drivers invoke dma cookie completion.
> >
> > [1]: https://lore.kernel.org/r/20260917072507.5BDB61F000FF@smtp.kernel.org
> >
> > Signed-off-by: Vinod Koul <vkoul@kernel.org>
> > ---
> >  Documentation/driver-api/dmaengine/provider.rst | 5 +++++
> >  1 file changed, 5 insertions(+)
> >
> > diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst
> > index 2897ade67b39..1bcbce705659 100644
> > --- a/Documentation/driver-api/dmaengine/provider.rst
> > +++ b/Documentation/driver-api/dmaengine/provider.rst
> > @@ -557,6 +557,11 @@ dma_cookie_t
> >  - Not really relevant any more since the introduction of ``virt-dma``
> >    that abstracts it away.
> >
> > +- dmaengine drivers need to ensure buffers are flushed before invoking
> > +  vchan_cookie_complete() or dma_cookie_complete(). This would imply a call
> > +  to unmapping buffers or any such architcure calls to ensure caller seeing
> 
> Sashiko report a typo architcure

Yeah looks like my spell checker didnt caught it, I will apply now with
that fixed

> 
> Reviewed-by: Frank Li <Frank.Li@nxp.com>
> 
> > +  buffers are flushed is done before invoking these calls.
> > +
> >  dma_vec
> >
> >  - A small structure that contains a DMA address and length.
> > --
> > 2.53.0
> >

-- 
~Vinod

Re: [PATCH] docs: dmaengine: clarify ordering rules around cookie completion

[Vinod Koul]

On Fri, 09 Oct 2026 11:37:44 +0200, Vinod Koul wrote:
> Sashiko pointed in [1] about the cookie completion order. It is good to
> Document that for ensuring that dma buffer is flushed and no stale data
> is seeing by consumer, we need to make sure such action is taken before
> drivers invoke dma cookie completion.
> 
> [1]: https://lore.kernel.org/r/20260917072507.5BDB61F000FF@smtp.kernel.org
> 
> [...]

Applied, thanks!

[1/1] docs: dmaengine: clarify ordering rules around cookie completion
      commit: fa89be96e845de705eed6edd01ecb79d46ee21c7

Best regards,
-- 
~Vinod