Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Thu, 20 Oct 2022 09:42:22 +0530
From:   Vinod Koul <vkoul@kernel.org>
To:     "Walker, Benjamin" <benjamin.walker@intel.com>
Cc:     dmaengine@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: Re: [PATCH v5 4/7] dmaengine: Add provider documentation on cookie
 assignment
Message-ID: <Y1DKpnOdP5MbSGeO@matsya>
References: <20220622193753.3044206-1-benjamin.walker@intel.com>
 <20220829203537.30676-1-benjamin.walker@intel.com>
 <20220829203537.30676-5-benjamin.walker@intel.com>
 <Y1Am/RpgWv3PAVaU@matsya>
 <297dff63-e199-d14b-7148-916888030740@intel.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <297dff63-e199-d14b-7148-916888030740@intel.com>
Precedence: bulk

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