lkml.org 
[lkml]   [2022]   [Aug]   [29]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
From
Subject[PATCH v5 4/7] dmaengine: Add provider documentation on cookie assignment
Date
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
+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
\
 
 \ /
  Last update: 2022-08-29 22:36    [W:2.206 / U:0.024 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site