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

[Vinod Koul <vkoul@kernel.org>]

On 19-10-22, 10:21, Walker, Benjamin wrote:
> On 10/19/2022 9:34 AM, Vinod Koul wrote:
> > 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...
> 
> That's exactly what this patch series is changing. The earlier patches make
> changes to no longer report to the client the "last" or "used" cookie (to
> compare against) in the client APIs, and it turns out that nothing in the
> kernel actually cares about this behavior. So it's simply a documentation
> change to indicate that the client no longer has any visibility into the
> cookie behavior.

Not really, there are some engines which will notify that descriptor X
completed which also implies that all descriptors before X have
completed as well...

If we change the default behaviour, we risk breaking those.
> 
> Immediately below here the documentation then says that there's some
> convenience functions that providers can use that do produce monotonically
> increasing cookies. These are now optional for providers to use, if they
> find them useful, rather than the required way to manage the cookies.
> 
> > 
> > Completion is always in order unless we specify DMA_COMPLETION_NO_ORDER
> 
> The final patch in this series eliminates DMA_COMPLETION_NO_ORDER entirely.
> It was only used by the IDXD driver, and the reason I'm doing these patches
> is so that we can poll the IDXD driver for completions even though it can
> complete out of order.
-- 
~Vinod