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 90D07D12D63 for ; Mon, 11 Nov 2024 02:58:44 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id DA0796B0085; Sun, 10 Nov 2024 21:58:43 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id D50356B0088; Sun, 10 Nov 2024 21:58:43 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id C17F26B0089; Sun, 10 Nov 2024 21:58:43 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0011.hostedemail.com [216.40.44.11]) by kanga.kvack.org (Postfix) with ESMTP id 9D33E6B0085 for ; Sun, 10 Nov 2024 21:58:43 -0500 (EST) Received: from smtpin08.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay04.hostedemail.com (Postfix) with ESMTP id 217E11A16DB for ; Mon, 11 Nov 2024 02:58:43 +0000 (UTC) X-FDA: 82772304720.08.D035012 Received: from ms.lwn.net (ms.lwn.net [45.79.88.28]) by imf04.hostedemail.com (Postfix) with ESMTP id 98BF240013 for ; Mon, 11 Nov 2024 02:57:50 +0000 (UTC) Authentication-Results: imf04.hostedemail.com; dkim=pass header.d=lwn.net header.s=20201203 header.b=P6ZlMDKu; spf=pass (imf04.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=1731293834; 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:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=LZzQtmhOW2A0Cbau7zJcHxp+bCIY31NKdrMFpZxwDXo=; b=GHovS6scMtAMxDMylsd0Ogs5wHit0NGr0n+ZXChQAhxZ6ZCgB3hGVGkkdIKQtC/XEjIy2V KXOkAOZVcmGABWhmQAbZCxzpGX0LPtzca6HXtwMhjavUC9XGuDBuLQ10KrPsW8EioqtOMA tQwoJOpDMK1dFZIuHA7iiI0SeZGbwnU= ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1731293834; a=rsa-sha256; cv=none; b=7nxMFWOi889ZvJbnnJJBvcQkGmAJbtt+V3yAswLhdboEj18ToLFfgVZ9N2MIMcJMrP0V3Q MRjVOHToy1x0wwPjknzQ3VNvgXePlxgAqTvaokyehRP03zcmy6QXfsfJzrfqpNsI3tWBMi Rw0wL36piZWT8/q/SL07u6NxuT+p8+o= ARC-Authentication-Results: i=1; imf04.hostedemail.com; dkim=pass header.d=lwn.net header.s=20201203 header.b=P6ZlMDKu; spf=pass (imf04.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 DKIM-Filter: OpenDKIM Filter v2.11.0 ms.lwn.net 04194403E9 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lwn.net; s=20201203; t=1731293919; bh=LZzQtmhOW2A0Cbau7zJcHxp+bCIY31NKdrMFpZxwDXo=; h=From:To:Cc:Subject:In-Reply-To:References:Date:From; b=P6ZlMDKuMAATbHo1fiGbEgO4Fdf7nPT7SqDPMzQuradyDOv6suOb6fxutsindrE+7 YAqe/nrrvIXe19T+BoIJr/MCECgPllblWRKx8hLHqgoYKi4NLzXbeUsRzQpHT46Apk 16WvyKjjWECdMAXfC++MoWNfnbZX+wQ26rLDNJXwPHBBonUUml1zP30i+yuASAkjfu vyYGpz9zJfCirLY0C0kPoVZJ2DwCt1B305HCUxe1W4/wxWkSW8SGY7ATGH6Tlu1/oF bK8Iuk+1i1x1IgiBH4F39RZX0SXtnRWWPHBQU2Di1gdMOpHExP/t+4A4PrTP3krfc3 mdt6p5c5a5xeg== 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 04194403E9; Mon, 11 Nov 2024 02:58:39 +0000 (UTC) From: Jonathan Corbet To: anish kumar , Leon Romanovsky Cc: Jens Axboe , Jason Gunthorpe , Robin Murphy , Joerg Roedel , Will Deacon , Christoph Hellwig , Sagi Grimberg , 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, Randy Dunlap Subject: Re: [PATCH v3 09/17] docs: core-api: document the IOVA-based API In-Reply-To: References: Date: Sun, 10 Nov 2024 19:58:38 -0700 Message-ID: <875xouv5lt.fsf@trenco.lwn.net> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Rspamd-Server: rspam10 X-Stat-Signature: 1sx989jm9ac8bswf65zrkr35wdg3pyzz X-Rspamd-Queue-Id: 98BF240013 X-Rspam-User: X-HE-Tag: 1731293870-532062 X-HE-Meta: U2FsdGVkX18u7tCTwqLvdmDe7NOIzPgz+JsNQCqNKsGhySschWxuarRx7T0xnUYFeJZWM4HRnzDjcq9ZKA0HmJ0wqrNCe1DNQgXvxI19ieS2CgrdKBLl/Fa9bSMH6ZrV1F02HyIET+T0pJvpotb3cSLG/x/XotXnyLSIYcOIA+Js4+All7Wi1o36rfkjdSgcU+aWKowVKLuF+fYQCrozY+YYLGlJPbmTS8m13Zhdl70XuLn1X/Yj8lszP/SnwcU9K0B1Ll120U+Ha9sW5w/HU/S2gPDUot09i/LunREZLj9hAkNpwi79N0dcru1pPHUt4tu8VyyfgiSy9Z9keF3UqG+cu8VH+Xq0LuT7UIJy2NfjcIbHTg7Hzrg375Fg3sUwzAHzIsxoGFDuFYxfCXDUUngn79K99RyjhWOzOQ6C55Eq3fzL/HpjuhAh8ILmDJzTg00a3T/IzBGhemd1VQArDAOE9bS9r/ezg5LTonIEpJTyYNxI3xA9Gua4OoFILFKha4lOFLunmTSKS9pppZxJo7ExQ7UR2zQSxvCreuHgebDeAljhyDEJWgvT8zapQ53lmCN1USGng6PYlmlD3bnHuxWynIgdMRI+uhf1iomnpR9PfpFOwskuoRMF9fRT8uewzqjJC+DuwxxMgwiLLM7rwi5UzLbbGiFyCgaQjLUFiXJL+OCKDpK0aRf4BrIzmprHx0NQIiBeApcoiswkXl4q6mmwtr57wsIHyACzSfHQGuwaAVHfkBHCF8u2eO7BpAwc1jOZM0S49ldMNv/gqiELGcbI+KwULNo2+NuGoIbMd0ikwJB/Pj0uD9O/3TWJnvvs8KvciDIQOlKd/LwMZT1ITYKJSOHxNtAWdwFTNbdxrULOSBsP1lsGjj6/FaL57XI5v9/X+qyXOIR/OJTt+qgZNjkUdY6Y/8+a180pngPazwCqJSsYPXcxN+7vEExZsIgXsPq4eVm6EvhFqxsnyN4 AQ9IPQ+z n2xEWW1KTynpzC0HQOQkYXkhcfaF9+n8AD45TEpwuwsOHX8hwTX5CVCovPOJ+AS2s5WZYlt7PkoANOU+lt29GiH3VbjoexfQbLI9lwYto7zvWZ9Pt4UfsxPFYYKGGpb0qayupNEiT5ZbT7wTP/4ockAM3/3XN7UFJ+zqj5cF98dKgRk0Wbqe7CXWK+PlViDNLGDQCIqE930ly7aoUuGEzwCWsZO+gEyDogYXEp9GNCpZ8wG/MLr9XqqXAVqw4t9IsuWDIH6ZvMX14j7SEYtplSCFY81X5ZbhBMzQ6cUb/20KGhw4CzYtb8DnoPWQlz6JlbzSeI9tovQA0yi/DUO47ToTjk8Ajy6lIJiarZPrD8N8+270= 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: anish kumar writes: > On Sun, Nov 10, 2024 at 5:50=E2=80=AFAM Leon Romanovsky = wrote: >> >> 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..61d6f4fe3d88 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 ar= e an > > "They" doesn't sound nice. >> +optional path that requires extra code and are only recommended for dri= vers >> +where DMA mapping performance, or the space usage for storing the DMA a= ddresses >> +matter. All the considerations from the previous section apply here as= well. > > These APIs provide an efficient mapping when using an IOMMU. However, they > are optional and require additional code. They are recommended primarily = for > drivers where performance in DMA mapping or the storage space for DMA > addresses are critical. All the considerations discussed in the previous = section > also apply in this case. > > You can disregard this comment, as anyone reading this paragraph will > understand the intended message. I don't understand the comment, honestly. You say "they" doesn't "sound nice", whatever that means, but your suggestion retains the "they"...? I'm all for reviews that improve our documentation, but it is *incredibly* easy to fall into the trivial bikeshed mode. I've certainly done it myself. The end result is less documentation as people decide, understandably, that it's not worth the pain. Hopefully we can all try to do a bit less of that. FWIW, I think the paragraph is fine as written. Thanks, jon