From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id E677FD64080 for ; Fri, 8 Nov 2024 19:34:28 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 7F7E56B00C3; Fri, 8 Nov 2024 14:34:28 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 780EC6B00CE; Fri, 8 Nov 2024 14:34:28 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 5FA3C6B00D2; Fri, 8 Nov 2024 14:34:28 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0015.hostedemail.com [216.40.44.15]) by kanga.kvack.org (Postfix) with ESMTP id 3DC466B00C3 for ; Fri, 8 Nov 2024 14:34:28 -0500 (EST) Received: from smtpin19.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay10.hostedemail.com (Postfix) with ESMTP id B2953C034A for ; Fri, 8 Nov 2024 19:34:27 +0000 (UTC) X-FDA: 82763927736.19.A14EDAC Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by imf09.hostedemail.com (Postfix) with ESMTP id 2AB3114001F for ; Fri, 8 Nov 2024 19:33:59 +0000 (UTC) Authentication-Results: imf09.hostedemail.com; dkim=pass header.d=lwn.net header.s=20201203 header.b=dnsz5YfG; spf=pass (imf09.hostedemail.com: domain of corbet@lwn.net designates 45.79.88.28 as permitted sender) smtp.mailfrom=corbet@lwn.net; dmarc=pass (policy=none) header.from=lwn.net ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1731094297; h=from:from:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=2mf7KL6RauZLJCGVMslddkfvUkwUMRQBSzo8JS8PbOo=; b=bAVhYOBueoQUp+ntKPntXXtxa8aP3zi/Jkq8j4lTlo3Qx+Rz5nB4AukYUBQXqntFI8SgAu sOPB/TY+ehxcb9C4jqsXPJhZthdXXwKNV1EpwFOJZjQ1FRxPFtprZtJMpiEUdHmSdL2mLD WvUqlTsubElktuDqh0U5vRo/2mhd2o4= ARC-Authentication-Results: i=1; imf09.hostedemail.com; dkim=pass header.d=lwn.net header.s=20201203 header.b=dnsz5YfG; spf=pass (imf09.hostedemail.com: domain of corbet@lwn.net designates 45.79.88.28 as permitted sender) smtp.mailfrom=corbet@lwn.net; dmarc=pass (policy=none) header.from=lwn.net ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1731094297; a=rsa-sha256; cv=none; b=RpHfNBrpOfTQ/OpKKH5YYOp4Su1lQGYIceGugTq4Z7pVfxeTqRhRmFIrOO2VaPF0axLw28 a1SfDli7pANSIXrvZIa5rkfb0ZUaRJoNbyPLkVWkLCS5NToRjIrRtvCWI0y8LBhr8ZCjrF pp6dvSq6jmLm5PJG9VkYaaADu5hS1sU= DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 443C842C17 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1731094462; bh=2mf7KL6RauZLJCGVMslddkfvUkwUMRQBSzo8JS8PbOo=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=dnsz5YfGWANp6sFnIUKjORH9aQENZDGixeRFgCKU+EHYtfew50seKAGvAytaFY9oj 05nxCVWbEfcD++04BAkjYS67T71ZQKhzyu6q3WZ8JM+Nq5axZuGUldvxslQ6IDBgXj 4TWkgRvZmPQDP4+rVCptcrXwBOfBXoMDeUZRH8Wp3ugkYqZvGKmWHOgN92MEiBDxr5 9u5STRUt+O2euSBwkgcMhfsaH0RnwMEO/iN2P0oM2sZd22f5AUcPoAVVdjXDvknK/o T3zwqzKkVrYA3KBU7u+ycHZvQ7dYicPF4vGfmge7fq9Ntn0IbVNJL2+Ng+Nux9U4bj j2d2WZj3WBcbQ== Received: from localhost (unknown [IPv6:2601:280:5e00:625::1fe]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by ms.lwn.net (Postfix) with ESMTPSA id 443C842C17; Fri, 8 Nov 2024 19:34:22 +0000 (UTC) From: Jonathan Corbet To: Leon Romanovsky , Jens Axboe , Jason Gunthorpe , Robin Murphy , Joerg Roedel , Will Deacon , Christoph Hellwig , Sagi Grimberg Cc: Keith Busch , Bjorn Helgaas , Logan Gunthorpe , Yishai Hadas , Shameer Kolothum , Kevin Tian , Alex Williamson , Marek Szyprowski , =?utf-8?B?SsOpcsO0bWU=?= Glisse , Andrew Morton , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, linux-block@vger.kernel.org, linux-rdma@vger.kernel.org, iommu@lists.linux.dev, linux-nvme@lists.infradead.org, linux-pci@vger.kernel.org, kvm@vger.kernel.org, linux-mm@kvack.org Subject: Re: [PATCH v1 09/17] docs: core-api: document the IOVA-based API In-Reply-To: <881ef0bcf9aa971e995fbdd00776c5140a7b5b3d.1730298502.git.leon@kernel.org> References: <881ef0bcf9aa971e995fbdd00776c5140a7b5b3d.1730298502.git.leon@kernel.org> Date: Fri, 08 Nov 2024 12:34:21 -0700 Message-ID: <87ttchwmde.fsf@trenco.lwn.net> MIME-Version: 1.0 Content-Type: text/plain X-Rspamd-Server: rspam09 X-Rspamd-Queue-Id: 2AB3114001F X-Stat-Signature: 8ht5eh9gdp1bahrnb8jcqxsnqo3w9543 X-Rspam-User: X-HE-Tag: 1731094439-692371 X-HE-Meta: U2FsdGVkX1/tpwsrjiiZWEnF9V4fT8XVIgrg9nY0bL0mq0/3cphcriUBj8hoZhJc+9Rn/njLNfyjBcVj5lukX9nXv95kI/zNVL/ovazgupUjRXSzf3va3naPdyo73MCd/ifpbGgdzhTNw+wZ+GV/WDAkCrjm5zxrhADCPgC6JXuJ8xw8+gDLitQ+gpvvJMylMSvwbp6tchDsloaeIXTZ0eHhuMoUTpk4PbQkZkJR9VtA5ygIQJ2r3cm5aTt8S0VwJZ1m5oXfLdJqIQ2+HJhWd1yiyIEUPGbcDyOFNpB65lFFVssnGollK7pxGdNnqMnI99gIJj6W5nin4Sjva2O5bw9cGfb4SB9yjLKsF87FZBmQIzcSwPd5vbhGUc5QCB4uc0UpokZumoo+fQQBmG7ww6ubigFJU4qhjG7cQqS6gJ/PkXw3ZhkcQ84G2d0WwQG4tTyN6JrUJwCR/ZYBM6qp+gnnm84Xk4yKFMFAOwDoYSid7UrNHSQis7k51BXuF30m2UEE0a+2cDyhIsG1toPk470ISobpXNK+RlqinoR109gu4OgErFsBB4b04wlwhp54/pd9lFGyKdMup5VJ/a3K4GOTVyC7Eh1q2/D9JRqbTkAsNhosaKJnt5UqpW1AE+EMvWoM2ahgAMjHBs5pc6noC5iNXFKiFSFawzbxh86nbtWQsorp+/7V68o50l59XVUdPVcgB2OfXtxoopEnVVjfNpoj6mLg8URJhenmLwiBRYvHcPblkuBZW5ubchmewYqFMKIJzwNEwDMlq15ulQ5oiHixun00kHcHtHw+xugZotAd6pr7Acxb5uhIqp7894fDOJ/8WR5XtfxDKRx+1DmlbO/QASM5p2qdz8B7H4PWUhwPy6RPe3izfFkZpdpgS9cQZEjx9NWWAFhS7MS1sIrDSNINe70QtTeeTZ1My3do0fGXne675SbAiDZAxeCkyb5HiS7F7WSmWH3mP/GW8td A7K54lGN l5Nx98L9LNNJV7wlG7HtCN7PwdZ4W0iKmw6IJO7yLBpLp0eSphm62IY1N5FJJZ/4JEOw76QlKS0HwS+fN0HAZFMPa2kUCndd7b3b3eZy+zRwPuodKkuD9qhLTJxiItWeLVQnsnhrirWoZYpjPmqJr5TFQk+2L+RgYcKk2of5TnMp94D4KaZfmbPo20t1ZkGrXFwd9mMzEzkVhH0KsKt8Dym4ittzA4M7PRvOIU5zfEiw1k2hnW71wmijRhHTkxFi27uQdms+ed1+xp0VD93Q6IU4KvbpJGyECQIKd X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: List-Subscribe: List-Unsubscribe: Leon Romanovsky writes: > From: Christoph Hellwig > > Add an explanation of the newly added IOVA-based mapping API. > > Signed-off-by: Christoph Hellwig > Signed-off-by: Leon Romanovsky > --- > Documentation/core-api/dma-api.rst | 70 ++++++++++++++++++++++++++++++ > 1 file changed, 70 insertions(+) > > diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst > index 8e3cce3d0a23..6095696a65a7 100644 > --- a/Documentation/core-api/dma-api.rst > +++ b/Documentation/core-api/dma-api.rst > @@ -530,6 +530,76 @@ routines, e.g.::: > .... > } > > +Part Ie - IOVA-based DMA mappings > +--------------------------------- > + > +These APIs allow a very efficient mapping when using an IOMMU. They are an > +optional path that requires extra code and are only recommended for drivers > +where DMA mapping performance, or the space usage for storing the DMA addresses > +matter. All the consideration from the previous section apply here as well. > + > +:: > + > + bool dma_iova_try_alloc(struct device *dev, struct dma_iova_state *state, > + phys_addr_t phys, size_t size); > + > +Is used to try to allocate IOVA space for mapping operation. If it returns > +false this API can't be used for the given device and the normal streaming > +DMA mapping API should be used. The ``struct dma_iova_state`` is allocated > +by the driver and must be kept around until unmap time. So, I see that you have nice kernel-doc comments for these; why not just pull them in here with a kernel-doc directive rather than duplicating the information? Thanks, jon