Re: [PATCH v5 4/7] dmaengine: Add provider documentation on cookie assignment

[Vinod Koul <vkoul@kernel.org>]

On 29-08-22, 13:35, Ben Walker wrote:
> Clarify the rules on assigning cookies to DMA transactions.
> 
> Signed-off-by: Ben Walker <benjamin.walker@intel.com>
> ---
>  .../driver-api/dmaengine/provider.rst         | 45 +++++++++++++++----
>  1 file changed, 37 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst
> index 1d0da2777921d..a5539f816d125 100644
> --- a/Documentation/driver-api/dmaengine/provider.rst
> +++ b/Documentation/driver-api/dmaengine/provider.rst
> @@ -417,7 +417,9 @@ supported.
>  
>      - tx_submit: A pointer to a function you have to implement,
>        that is supposed to push the current transaction descriptor to a
> -      pending queue, waiting for issue_pending to be called.
> +      pending queue, waiting for issue_pending to be called. Each
> +      descriptor is given a cookie to identify it. See the section
> +      "Cookie Management" below.
>  
>    - In this structure the function pointer callback_result can be
>      initialized in order for the submitter to be notified that a
> @@ -522,6 +524,40 @@ supported.
>  
>    - May sleep.
>  
> +Cookie Management
> +------------------
> +
> +When a transaction is queued for submission via tx_submit(), the provider
> +must assign that transaction a cookie (dma_cookie_t) to uniquely identify it.
> +The provider is allowed to perform this assignment however it wants, but for

We assumes that we have monotonically increasing cookie and
if cookie 10 is marked complete cookie 8 is assumed complete too...

Completion is always in order unless we specify DMA_COMPLETION_NO_ORDER

> +convenience the following utility functions are available to create
> +monotonically increasing cookies
> +
> +  .. code-block:: c
> +
> +    void dma_cookie_init(struct dma_chan *chan);
> +
> +  Called once at channel creation
> +
> +  .. code-block:: c
> +
> +    dma_cookie_t dma_cookie_assign(struct dma_async_tx_descriptor *tx);
> +
> +  Assign a cookie to the given descriptor
> +
> +  .. code-block:: c
> +
> +    void dma_cookie_complete(struct dma_async_tx_descriptor *tx);
> +
> +  Mark the descriptor as complete and invalidate the cookie
> +
> +  .. code-block:: c
> +
> +    enum dma_status dma_cookie_status(struct dma_chan *chan,
> +      dma_cookie_t cookie, struct dma_tx_state *state);
> +
> +  Report the status of the cookie and filling in state, if not NULL.
> +
>  
>  Misc notes
>  ==========
> @@ -537,13 +573,6 @@ where to put them)
>  - Makes sure that dependent operations are run before marking it
>    as complete.
>  
> -dma_cookie_t
> -
> -- it's a DMA transaction ID.
> -
> -- The value can be chosen by the provider, or use the helper APIs
> -  such as dma_cookie_assign() and dma_cookie_complete().
> -
>  DMA_CTRL_ACK
>  
>  - If clear, the descriptor cannot be reused by provider until the
> -- 
> 2.37.1

-- 
~Vinod