From: Ben Walker <benjamin.walker@intel.com>
To: vkoul@kernel.org
Cc: dmaengine@vger.kernel.org, herbert@gondor.apana.org.au,
davem@davemloft.net, mchehab@kernel.org,
mporter@kernel.crashing.org, alex.bou9@gmail.com,
Ben Walker <benjamin.walker@intel.com>
Subject: [PATCH v2 12/15] dmaengine: Add provider documentation on cookie assignment
Date: Tue, 3 May 2022 13:07:25 -0700 [thread overview]
Message-ID: <20220503200728.2321188-13-benjamin.walker@intel.com> (raw)
In-Reply-To: <20220503200728.2321188-1-benjamin.walker@intel.com>
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 e9e9de18d6b02..7c8ace703c96f 100644
--- a/Documentation/driver-api/dmaengine/provider.rst
+++ b/Documentation/driver-api/dmaengine/provider.rst
@@ -421,7 +421,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
@@ -526,6 +528,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
==========
@@ -541,13 +577,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.35.1
next prev parent reply other threads:[~2022-05-03 20:09 UTC|newest]
Thread overview: 59+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-05-03 20:07 [PATCH v2 00/15] dmaengine: Support polling for out of order completions Ben Walker
2022-05-03 20:07 ` [PATCH v2 01/15] dmaengine: Remove dma_async_is_complete from client API Ben Walker
2022-05-03 20:07 ` [PATCH v2 02/15] dmaengine: Move dma_set_tx_state to the provider API header Ben Walker
2022-05-03 20:07 ` [PATCH v2 03/15] dmaengine: Add dmaengine_async_is_tx_complete Ben Walker
2022-05-03 20:07 ` [PATCH v2 04/15] crypto: stm32/hash: Use dmaengine_async_is_tx_complete Ben Walker
2022-05-03 20:07 ` [PATCH v2 05/15] media: omap_vout: " Ben Walker
2022-05-03 20:07 ` [PATCH v2 06/15] rapidio: " Ben Walker
2022-05-03 20:07 ` [PATCH v2 07/15] media: pxa_camera: " Ben Walker
2022-05-03 20:07 ` [PATCH v2 08/15] dmaengine: Remove dma_async_is_tx_complete Ben Walker
2022-05-03 20:07 ` [PATCH v2 09/15] dmaengine: Remove last, used from dma_tx_state Ben Walker
2022-05-03 20:07 ` [PATCH v2 10/15] dmaengine: Providers should prefer dma_set_residue over dma_set_tx_state Ben Walker
2022-05-03 20:07 ` [PATCH v2 11/15] dmaengine: Remove dma_set_tx_state Ben Walker
2022-05-03 20:07 ` Ben Walker [this message]
2022-05-03 20:07 ` [PATCH v2 13/15] dmaengine: idxd: idxd_desc.id is now a u16 Ben Walker
2022-05-03 20:07 ` [PATCH v2 14/15] dmaengine: idxd: Support device_tx_status Ben Walker
2022-05-03 20:07 ` [PATCH v2 15/15] dmaengine: Revert "cookie bypass for out of order completion" Ben Walker
2022-06-09 6:53 ` [PATCH v2 00/15] dmaengine: Support polling for out of order completions Vinod Koul
2022-06-22 6:29 ` Mauro Carvalho Chehab
2022-06-22 19:37 ` [PATCH v4 " Ben Walker
2022-06-22 19:37 ` [PATCH v4 01/15] dmaengine: Remove dma_async_is_complete from client API Ben Walker
2022-06-22 19:37 ` [PATCH v4 02/15] dmaengine: Move dma_set_tx_state to the provider API header Ben Walker
2022-06-22 19:37 ` [PATCH v4 03/15] dmaengine: Add dmaengine_async_is_tx_complete Ben Walker
2022-06-22 19:37 ` [PATCH v4 04/15] crypto: stm32/hash: Use dmaengine_async_is_tx_complete Ben Walker
2022-06-22 19:37 ` [PATCH v4 05/15] media: omap_vout: " Ben Walker
2022-06-22 19:37 ` [PATCH v4 06/15] rapidio: " Ben Walker
2022-06-22 19:37 ` [PATCH v4 07/15] media: pxa_camera: " Ben Walker
2022-06-22 19:37 ` [PATCH v4 08/15] dmaengine: Remove dma_async_is_tx_complete Ben Walker
2022-06-22 19:37 ` [PATCH v4 09/15] dmaengine: Remove last, used from dma_tx_state Ben Walker
2022-06-22 19:37 ` [PATCH v4 10/15] dmaengine: Providers should prefer dma_set_residue over dma_set_tx_state Ben Walker
2022-06-22 19:37 ` [PATCH v4 11/15] dmaengine: Remove dma_set_tx_state Ben Walker
2022-06-22 19:37 ` [PATCH v4 12/15] dmaengine: Add provider documentation on cookie assignment Ben Walker
2022-06-22 19:37 ` [PATCH v4 13/15] dmaengine: idxd: idxd_desc.id is now a u16 Ben Walker
2022-06-22 19:37 ` [PATCH v4 14/15] dmaengine: idxd: Support device_tx_status Ben Walker
2022-06-22 19:37 ` [PATCH v4 15/15] dmaengine: Revert "cookie bypass for out of order completion" Ben Walker
2022-06-27 6:29 ` [PATCH v4 00/15] dmaengine: Support polling for out of order completions Vinod Koul
2022-08-29 20:35 ` [PATCH v5 0/7] " Ben Walker
2022-08-29 20:35 ` [PATCH v5 1/7] dmaengine: Remove dma_async_is_complete from client API Ben Walker
2022-08-29 20:35 ` [PATCH v5 2/7] dmaengine: Move dma_set_tx_state to the provider API header Ben Walker
2022-08-29 20:35 ` [PATCH v5 3/7] dmaengine: Add dmaengine_async_is_tx_complete Ben Walker
2022-10-19 16:31 ` Vinod Koul
2022-10-19 17:08 ` Walker, Benjamin
2022-08-29 20:35 ` [PATCH v5 4/7] dmaengine: Add provider documentation on cookie assignment Ben Walker
2022-10-19 16:34 ` Vinod Koul
2022-10-19 17:21 ` Walker, Benjamin
2022-10-20 4:12 ` Vinod Koul
2022-10-21 17:33 ` Walker, Benjamin
2022-08-29 20:35 ` [PATCH v5 5/7] dmaengine: idxd: idxd_desc.id is now a u16 Ben Walker
2022-08-29 20:35 ` [PATCH v5 6/7] dmaengine: idxd: Support device_tx_status Ben Walker
2022-09-01 17:24 ` Dave Jiang
2022-08-29 20:35 ` [PATCH v5 7/7] dmaengine: Revert "cookie bypass for out of order completion" Ben Walker
2022-09-01 17:25 ` [PATCH v5 0/7] dmaengine: Support polling for out of order completions Dave Jiang
2022-10-28 20:48 ` [PATCH v6 " Ben Walker
2022-10-28 20:48 ` [PATCH v6 1/7] dmaengine: Remove dma_async_is_complete from client API Ben Walker
2022-10-28 20:48 ` [PATCH v6 2/7] dmaengine: Move dma_set_tx_state to the provider API header Ben Walker
2022-10-28 20:48 ` [PATCH v6 3/7] dmaengine: Add dmaengine_is_tx_complete Ben Walker
2022-10-28 20:48 ` [PATCH v6 4/7] dmaengine: Add provider documentation on cookie assignment Ben Walker
2022-10-28 20:48 ` [PATCH v6 5/7] dmaengine: idxd: idxd_desc.id is now a u16 Ben Walker
2022-10-28 20:48 ` [PATCH v6 6/7] dmaengine: idxd: Support device_tx_status Ben Walker
2022-10-28 20:48 ` [PATCH v6 7/7] dmaengine: Revert "cookie bypass for out of order completion" Ben Walker
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20220503200728.2321188-13-benjamin.walker@intel.com \
--to=benjamin.walker@intel.com \
--cc=alex.bou9@gmail.com \
--cc=davem@davemloft.net \
--cc=dmaengine@vger.kernel.org \
--cc=herbert@gondor.apana.org.au \
--cc=mchehab@kernel.org \
--cc=mporter@kernel.crashing.org \
--cc=vkoul@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).