Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
Received-SPF: Pass (protection.outlook.com: domain of cern.ch designates
 188.184.36.46 as permitted sender) receiver=protection.outlook.com;
 client-ip=188.184.36.46; helo=cernmxgwlb4.cern.ch;
From:   Federico Vaga <federico.vaga@cern.ch>
To:     Vinod Koul <vkoul@kernel.org>
Reply-To: <federico.vaga@cern.ch>
CC:     <dmaengine@vger.kernel.org>, <linux-kernel@vger.kernel.org>,
        <linux-doc@vger.kernel.org>
Subject: DMA Engine Documentation: TX Descriptor and Submission
Date:   Mon, 28 Jan 2019 09:47:50 +0100
Message-ID: <1655406.8MLMLfCWyH@pcbe13614>
MIME-Version: 1.0
Content-Transfer-Encoding: 7Bit
Content-Type: text/plain; charset="us-ascii"
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 28 Jan 2019 08:47:51.4518
 (UTC)
X-MS-Exchange-CrossTenant-Network-Message-Id: 574a7355-db8f-441a-7bc6-08d684fd49a9
X-MS-Exchange-CrossTenant-Id: c80d3499-4a40-4a8c-986e-abce017d6b19
X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=c80d3499-4a40-4a8c-986e-abce017d6b19;Ip=[188.184.36.46];Helo=[cernmxgwlb4.cern.ch]
X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem
X-MS-Exchange-Transport-CrossTenantHeadersStamped: VI1PR0601MB2271
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

Hi,

I have a new question concerning documentation.

https://www.kernel.org/doc/html/latest/driver-api/dmaengine/client.html

From this document it is not really clear, at least to me, if clients can 
consider valid the `struct dma_async_tx_descriptor` after submission to the 
DMA engine.

Clients get a TX descriptor from a DMA engine using things like 
`dmaengine_prep_*`. These calls - may - allocate new descriptors and return 
them to the caller; this may include other structures which are not visible to 
clients. So, if my understanding is correct, this means that it's the DMA 
engine that, on TX completion, releases any TX descriptor allocated by 
`dmaengine_prep_*`. This implies that the pointer that the client is using 
must be considered invalid right after `dmaengine_submit()`.

If what I understood by reading the documentation and the code is correct, 
then I think that this should be mentioned in the Documentation.
If I'm wrong, please tell me where :)

Thanks