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