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 F0DF8D12D5E for ; Mon, 11 Nov 2024 02:05:52 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id F1F6B6B0083; Sun, 10 Nov 2024 21:05:51 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id ECE606B0088; Sun, 10 Nov 2024 21:05:51 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id D6F2B6B0089; Sun, 10 Nov 2024 21:05:51 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0016.hostedemail.com [216.40.44.16]) by kanga.kvack.org (Postfix) with ESMTP id B7E146B0083 for ; Sun, 10 Nov 2024 21:05:51 -0500 (EST) Received: from smtpin11.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay04.hostedemail.com (Postfix) with ESMTP id 208B31A1695 for ; Mon, 11 Nov 2024 02:05:51 +0000 (UTC) X-FDA: 82772172588.11.34647E5 Received: from mail-lj1-f173.google.com (mail-lj1-f173.google.com [209.85.208.173]) by imf22.hostedemail.com (Postfix) with ESMTP id 97737C0007 for ; Mon, 11 Nov 2024 02:04:59 +0000 (UTC) Authentication-Results: imf22.hostedemail.com; dkim=pass header.d=gmail.com header.s=20230601 header.b="U+/DXugr"; spf=pass (imf22.hostedemail.com: domain of yesanishhere@gmail.com designates 209.85.208.173 as permitted sender) smtp.mailfrom=yesanishhere@gmail.com; dmarc=pass (policy=none) header.from=gmail.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1731290577; 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=GdEkfAJOsElSV+ujZ/1dK2DOAkU54yl3So/8rs20Jag=; b=vVbVkaTUdXpXOESa/gZvl0Mor7/kat/2w7j+OtOguPlYKjg9FDcEPJ3OpSftLL+xUrtsCx qdyh3LSpZ9UR1QvAyDjQHJQ92vWXNZohlGwQ1RrY5ggc0an/MuUHJLhD6LQxr7jCWzfr5I KiYXR8rLpZMSlSAUxk/l7Rj2hEqyEIY= ARC-Authentication-Results: i=1; imf22.hostedemail.com; dkim=pass header.d=gmail.com header.s=20230601 header.b="U+/DXugr"; spf=pass (imf22.hostedemail.com: domain of yesanishhere@gmail.com designates 209.85.208.173 as permitted sender) smtp.mailfrom=yesanishhere@gmail.com; dmarc=pass (policy=none) header.from=gmail.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1731290577; a=rsa-sha256; cv=none; b=n6syaL9CjElveNKUtUDdDisuENafCn0FW/Sd1qWMIza66ZASrP7fhkcZ3K6p5gzA46JXmR YVrFHr5TvTPxXZIxmeWKbtjZCciqqesn0SFH25m9ifNbAvdDHEGdYfhIzEV71mVuNVd3JE sI+LGH9Y5FYjtMh02osbbb7xQOh/6Kk= Received: by mail-lj1-f173.google.com with SMTP id 38308e7fff4ca-2fb3debdc09so29403291fa.3 for ; Sun, 10 Nov 2024 18:05:48 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1731290747; x=1731895547; darn=kvack.org; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:from:to:cc:subject:date :message-id:reply-to; bh=GdEkfAJOsElSV+ujZ/1dK2DOAkU54yl3So/8rs20Jag=; b=U+/DXugrKOzpj3xG6tr5AtOkHncBktrel8heooywY85815WkSCV+DeWAELuEriyVur LQoN23MfQ+Fe8oak/0bZorcBX5pgLxFU1e+lTJDQZg1eIrGXxSPvKODmfgdMJbvwoiTT Kajlu3Tkv8wuDatxFM6kIe2qX8bwyw0XgXi86SpfACMXhI+VU+9sYsGdaI0hfIDwEgT2 Uc6kNYYPj6Aaxyeybk8Gt+8Dc7mvTjYrrhq0z5V0OSHL0StzLd6peWTumFwQ6xAHvF+e U8wf3/Q1KdCwmCprIxk6h/WDqeHASd5ZetyrOH1RQ/qbSEcuzXHV9k984YunHvN4uhc8 4R8w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1731290747; x=1731895547; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=GdEkfAJOsElSV+ujZ/1dK2DOAkU54yl3So/8rs20Jag=; b=rkZ3MSqzoEApoiSBeRMAdIsA2R+od/pgONzpx2hCa0jnfPfAH3PD6FfcOY9E3S4rAM OPec/8C/JFJ0Afyql0y5DdVx350AXZFASpUdh2DWUvss4f+Co9FCQb4qZaqmBw5DbuBu qP+ExMn1aTb1FpkPZDsgoYT99BwXo791Uur36hN4+VRehF09bTkt+tBBn8M7vO8c8NOL R+N/6u1GdIjoxfhuF9xSuNvRNwPryCjqURKwar9wR8pKHN/DehMkJaymPZ5gtU4Bfv++ zToJ0LRqv47OTSthKG+s5dizxhVBwrDBwio/li2Lk1l68sKoyRUDAIXLib+XF+jul2bH StQg== X-Forwarded-Encrypted: i=1; AJvYcCUh59RMfgU3K08lAnFBSOB10Y5LjL2vz00r6n579j0lm45HmGTZA+xlqWczu23iYTjSJirXqooSaA==@kvack.org X-Gm-Message-State: AOJu0YyBlm3blkKxQtk1sIUJHLJdGizb5mdogi10Gn+FEYY4/28sJtZG fY0rfc5QU+fxXKqfvt25lTONDBQ0JWukyq/IVME9BNdkVH+N2y1AJJWwi0yhAe/Pzf86tmlBxqS 4BfTtTAgu2WjKqyw6QaRP8Phny2A= X-Google-Smtp-Source: AGHT+IF0tJPIolZyNYPTT2b/MpCJe82Fg/iZslXB6gzAqlmjhMUqVGRF2M5H+UaSiVlIP433HQ0w2T+2CyxfkrVJL68= X-Received: by 2002:a2e:bc1d:0:b0:2fb:5014:8eb9 with SMTP id 38308e7fff4ca-2ff2014ec60mr46592301fa.10.1731290746959; Sun, 10 Nov 2024 18:05:46 -0800 (PST) MIME-Version: 1.0 References: In-Reply-To: From: anish kumar Date: Sun, 10 Nov 2024 18:05:35 -0800 Message-ID: Subject: Re: [PATCH v3 09/17] docs: core-api: document the IOVA-based API To: 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?SsOpcsO0bWUgR2xpc3Nl?= , Andrew Morton , Jonathan Corbet , 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 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Rspamd-Server: rspam09 X-Rspamd-Queue-Id: 97737C0007 X-Stat-Signature: bjox5keejcw6b5tcnjjdg1somb8nt6c3 X-Rspam-User: X-HE-Tag: 1731290699-665139 X-HE-Meta: U2FsdGVkX18cSMTZxWGl37fD1nqQ3CnHUXW6Ymp1DXu58se+s1kV3bIn2yy/hQGvc9yPb3q+ews+R4sEAT4gUZ8rfOEeVF8hmtGO26g5tEetVNsEl5VLitrkiNahEcWA30Foxn7YL4b3iFeyBXlRQE1VvpwoKGO20nOv7b3w7BclYZC/4yTI56hH1i1bF89znObn5JayEcvYQ0XH3xd4PilS4vpaDnauQN61mZyZGJgPRT3DtmXupypbuNvRR03YrotnTyG2nWJQ10Li9Yr5G0i1R8+KnqtfBoGW5VkM1r4WwDDteu3HpIYRagF8tvF4v23+k6Udo36Pu5wZZsDi89Z/4p4ciTEnGs/WXml6/sR6iThALJL3EY1Scyz3VXUZa1N4gYrRthn34SJN6074DdHXI9kQjLFheqxfxrUc48rIEqQm6siYMMdLgTywESy7ihAh4ABXm7RjT2VkNQO0ID38mv2moomcxBgZX2+MPoP9wADjw8fBXeIzoA2iewau+C1rxRAoIKso7QvY3h7rP+ysTdYQdezFfQiCrVEU+MvaD1tcwKTcWGA//+11cSW4DawDdPVy3MAH+wK8cCS60ZLv5c3TNzQ9OG5Ycevz5fJ28DpDmFmAbmiep0vYN9vZ02KMHooE+Jgb3pRkFCEVX3knOvPFVnXJz3CNM0nBO6s64zUZEh+tVEAQyBGOcSVR6sX+ggo95FGdXhc8yGJxFq9xR2M0GCjhQhazsYAbuWmdPdVeEf7rStPmcmYM/csrtxmfc+KXTP7tjpfKjzoBjssTNRsukBkNgsQruRg0iNd6DlVHh+JACaq+sti0UDMvORQSpC6gYhWBGpQprnYAooRCDd0my/MyPXsnxz1IgfutMZy6eqmHIEX51J153Y6dOXfpxeV4kVTrsP5ntEcm6fwHpAB3E4NLQk/BTcf4+jqURzSavcabyWbf+oKV+sJlM27dvM3vQij1llVNryC aeXUpzST f4p4tOYYRU1Jp60wfakl6lLHaoqn4JdXQ5Bas+cAuKgFGvjgIsAG0nqH1BH5UXiMLCUg6/X6cF98+7p7M3UIzAzATMN9MVkYJrn/fyl7EIhfHQdXS35aT0pHcNREyY9GCxzosTzFrkj+G7/g6Du35qy8vtf6a4Fhd51hhFLyRAoPNOw0x+NVBxOwQnBGx+gOWnYrkmwHF3Lce00SFsQBSk0ajTxNmgYYzkk+P/Lqjrbj1+CuNu+v1oQRIm10UoGvR2L6G97rmFvaL3c7YemcQUOaxm2ZwEu97QQVHTP8unWiQOZNgKM3BHBXWBQyiMfaDS82V6bJyCu/ALK3Ysjw1OLHssQhfdXuG1FTzTttwzOabawgbWdurCOB+TQ== 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: On Sun, Nov 10, 2024 at 5:50=E2=80=AFAM Leon Romanovsky w= rote: > > 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 are= an "They" doesn't sound nice. > +optional path that requires extra code and are only recommended for driv= ers > +where DMA mapping performance, or the space usage for storing the DMA ad= dresses > +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 fo= r drivers where performance in DMA mapping or the storage space for DMA addresses are critical. All the considerations discussed in the previous se= ction also apply in this case. You can disregard this comment, as anyone reading this paragraph will understand the intended message. > + > +:: > + > + bool dma_iova_try_alloc(struct device *dev, struct dma_iova_state *s= tate, > + phys_addr_t phys, size_t size); > + > +Is used to try to allocate IOVA space for mapping operation. If it retu= rns > +false this API can't be used for the given device and the normal streami= ng > +DMA mapping API should be used. The ``struct dma_iova_state`` is alloca= ted > +by the driver and must be kept around until unmap time. > + > +:: > + > + static inline bool dma_use_iova(struct dma_iova_state *state) > + > +Can be used by the driver to check if the IOVA-based API is used after a > +call to dma_iova_try_alloc. This can be useful in the unmap path. > + > +:: > + > + int dma_iova_link(struct device *dev, struct dma_iova_state *state, > + phys_addr_t phys, size_t offset, size_t size, > + enum dma_data_direction dir, unsigned long attrs); > + > +Is used to link ranges to the IOVA previously allocated. The start of a= ll > +but the first call to dma_iova_link for a given state must be aligned > +to the DMA merge boundary returned by ``dma_get_merge_boundary())``, and > +the size of all but the last range must be aligned to the DMA merge boun= dary > +as well. > + > +:: > + > + int dma_iova_sync(struct device *dev, struct dma_iova_state *state, > + size_t offset, size_t size); > + > +Must be called to sync the IOMMU page tables for IOVA-range mapped by on= e or > +more calls to ``dma_iova_link()``. > + > +For drivers that use a one-shot mapping, all ranges can be unmapped and = the > +IOVA freed by calling: > + > +:: > + > + void dma_iova_destroy(struct device *dev, struct dma_iova_state *stat= e, > + enum dma_data_direction dir, unsigned long attrs); > + > +Alternatively drivers can dynamically manage the IOVA space by unmapping > +and mapping individual regions. In that case > + > +:: > + > + void dma_iova_unlink(struct device *dev, struct dma_iova_state *stat= e, > + size_t offset, size_t size, enum dma_data_direction dir, > + unsigned long attrs); > + > +is used to unmap a range previously mapped, and > + > +:: > + > + void dma_iova_free(struct device *dev, struct dma_iova_state *state); > + > +is used to free the IOVA space. All regions must have been unmapped usi= ng > +``dma_iova_unlink()`` before calling ``dma_iova_free()``. > > Part II - Non-coherent DMA allocations > -------------------------------------- > -- > 2.47.0 > >