From patchwork Sat Oct 5 17:36:20 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Guennadi Liakhovetski X-Patchwork-Id: 2991621 Return-Path: X-Original-To: patchwork-linux-arm@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.19.201]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 614B2BF924 for ; Sat, 5 Oct 2013 17:37:07 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 6BFCB201F4 for ; Sat, 5 Oct 2013 17:37:06 +0000 (UTC) Received: from casper.infradead.org (casper.infradead.org [85.118.1.10]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 55CCC201E4 for ; Sat, 5 Oct 2013 17:37:05 +0000 (UTC) Received: from merlin.infradead.org ([2001:4978:20e::2]) by casper.infradead.org with esmtps (Exim 4.80.1 #2 (Red Hat Linux)) id 1VSVmj-0007Z4-6V; Sat, 05 Oct 2013 17:36:57 +0000 Received: from localhost ([::1] helo=merlin.infradead.org) by merlin.infradead.org with esmtp (Exim 4.80.1 #2 (Red Hat Linux)) id 1VSVmg-0004JI-Pl; Sat, 05 Oct 2013 17:36:54 +0000 Received: from moutng.kundenserver.de ([212.227.17.9]) by merlin.infradead.org with esmtps (Exim 4.80.1 #2 (Red Hat Linux)) id 1VSVmd-0004Hx-Ip for linux-arm-kernel@lists.infradead.org; Sat, 05 Oct 2013 17:36:52 +0000 Received: from axis700.grange (dslb-094-221-109-176.pools.arcor-ip.net [94.221.109.176]) by mrelayeu.kundenserver.de (node=mreu3) with ESMTP (Nemesis) id 0M0XGM-1Vo0yI2jbq-00usI8; Sat, 05 Oct 2013 19:36:20 +0200 Received: by axis700.grange (Postfix, from userid 1000) id 1A36A40BB4; Sat, 5 Oct 2013 19:36:20 +0200 (CEST) Received: from localhost (localhost [127.0.0.1]) by axis700.grange (Postfix) with ESMTP id 12A0540BB3; Sat, 5 Oct 2013 19:36:20 +0200 (CEST) Date: Sat, 5 Oct 2013 19:36:20 +0200 (CEST) From: Guennadi Liakhovetski X-X-Sender: lyakh@axis700.grange To: linux-kernel@vger.kernel.org Subject: [PATCH] DMA: extend documentation to provide more API details Message-ID: MIME-Version: 1.0 X-Provags-ID: V02:K0:Lc4GRa4niWOQX2gGsoZe6EDsgDzF1tfHf62NeN1K29+ 2b6kqwRaGKijr70i//rU4937P4FSghAvD8C16pA8in68Czr9lK wGhyP1BkpAT1BzFrk+ONnJrIfUhWgKhreQJ4VREmkRkrtdDskd nmkHJ6pxY1EjC8aeu8Z4daIom8FBY30IFj0twpo3ki+YN3Gm4X 8HZx81GE9qk31y45aeU8uycPqgit4OTdoOPcN//QRBoKeGsHMe AXv3zJfQsZM/XtARS7j8DaviN2F8xdpZMlbXtSr7Qxi+lQqBev IM654+Qi0Jy4WQ4iQub1q3/GbVUGs4z2H3lxFgGqPBkcIazz2v kN4nrTyyYxgZWGC9+DO5jBO3H7v6DWCIKiKHaleq9beJ0nMLf0 cRQDWMFM6wEmA== X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20131005_133651_839333_07548D06 X-CRM114-Status: GOOD ( 22.87 ) X-Spam-Score: -2.6 (--) Cc: Vinod Koul , linux-arm-kernel@lists.infradead.org X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+patchwork-linux-arm=patchwork.kernel.org@lists.infradead.org X-Spam-Status: No, score=-4.8 required=5.0 tests=BAYES_00,FREEMAIL_FROM, RCVD_IN_DNSWL_MED, RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP This patch extends dmaengine documentation to provide more details on descriptor prepare stage, transaction completion requirements and DMA error processing. Signed-off-by: Guennadi Liakhovetski --- These extensions reflect my understanding of some aspects of the dmaengine API. If it is wrong, I'd be happy if someone could correct me. If or where I'm right, I think, those aspects might want an update. Once we understand exactly the situation we can think about improvements to the API. Documentation/dmaengine.txt | 58 ++++++++++++++++++++++++++++++++++++------ 1 files changed, 49 insertions(+), 9 deletions(-) diff --git a/Documentation/dmaengine.txt b/Documentation/dmaengine.txt index 879b6e3..21bb72d 100644 --- a/Documentation/dmaengine.txt +++ b/Documentation/dmaengine.txt @@ -133,8 +133,17 @@ The slave DMA usage consists of following steps: locks before calling the callback function which may cause a deadlock. - Note that callbacks will always be invoked from the DMA - engines tasklet, never from interrupt context. + Note that callbacks will always be invoked from the DMA engine's + interrupt processing bottom half, never from interrupt context. + + Note 2: + A DMA transaction descriptor, returned to the user by one of "prep" + methods is considered as belogning to the user until it is submitted + to the dmaengine driver for transfer. However, it is recommended, that + the dmaengine driver keeps references to prepared descriptors too, + because if dmaengine_terminate_all() is called at that time, the driver + will have to recycle all allocated descriptors for the respective + channel. 4. Submit the transaction @@ -150,15 +159,27 @@ The slave DMA usage consists of following steps: dmaengine_submit() will not start the DMA operation, it merely adds it to the pending queue. For this, see step 5, dma_async_issue_pending. -5. Issue pending DMA requests and wait for callback notification +5. Issue pending DMA requests and (optionally) request callback notification - The transactions in the pending queue can be activated by calling the - issue_pending API. If channel is idle then the first transaction in - queue is started and subsequent ones queued up. + Dmaengine drivers accumulate submitted transactions on a pending queue. + After this call all such pending transactions are activated. Transactions, + submitted after this call will be queued again in a deactivated state until + this function is called again. If at the time of this call the channel is + idle then the first transaction in queue is started and subsequent ones are + queued up. - On completion of each DMA operation, the next in queue is started and - a tasklet triggered. The tasklet will then call the client driver - completion callback routine for notification, if set. + On completion of each DMA operation, the next active transaction in queue is + started and the ISR bottom half, e.g. a tasklet or a kernel thread is + triggered. The tasklet will then call the client driver completion callback + routine for notification, if set. + + The dmaengine driver also has to check the DMA_CTRL_ACK flag by calling + async_tx_test_ack() on the transaction. If the function returns true, i.e. + if the transaction either has been flagged from the very beginning, or + the user has flagged it later, then the transaction descriptor can be + recycled immediately by the dmaengine driver. If the function returns + false, the descriptor cannot be recycled yet and the dmaengine driver has + to keep polling the descriptor until it is acknowledged by the user. Interface: void dma_async_issue_pending(struct dma_chan *chan); @@ -171,6 +192,14 @@ Further APIs: discard data in the DMA FIFO which hasn't been fully transferred. No callback functions will be called for any incomplete transfers. + Note: + Transactions, aborted by this call are considered as failed. However, + if the user requests their status, using dma_async_is_complete() / + dma_async_is_complete(), as described below, one of DMA_IN_PROGRESS and + DMA_SUCCESS will be returned. So, drivers are advised not to use those + calls on transactions, submitted before a call to + dmaengine_terminate_all(). + 2. int dmaengine_pause(struct dma_chan *chan) This pauses activity on the DMA channel without data loss. @@ -196,3 +225,14 @@ Further APIs: a running DMA channel. It is recommended that DMA engine users pause or stop (via dmaengine_terminate_all) the channel before using this API. + +DMA error handling + +1. If a DMA error occurs, usually the DMA driver has to abort the transaction in + progress. Since transactions, queued after the aborted one can depend on it, + they usually have to be dropped too. There is currently no way to notify + users about such a problem, so, users should normally start all DMA + transactions with a timeout handler. If a timeout occurs, the user shall + assume, that the DMA transaction failed. However, due to the same reason, as + described in a note to the dmaengine_terminate_all() description above, + enquiring status of timed out transactions is unreliable.