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@xxxxxxxxx> > --- > .../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
