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 4B047C77B7F for ; Fri, 27 Jun 2025 10:10:44 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 6DC9E6B00CB; Fri, 27 Jun 2025 06:10:40 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 68BD76B00CC; Fri, 27 Jun 2025 06:10:40 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 57B666B00CD; Fri, 27 Jun 2025 06:10:40 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0014.hostedemail.com [216.40.44.14]) by kanga.kvack.org (Postfix) with ESMTP id 49DEC6B00CB for ; Fri, 27 Jun 2025 06:10:40 -0400 (EDT) Received: from smtpin11.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay08.hostedemail.com (Postfix) with ESMTP id 163F914061E for ; Fri, 27 Jun 2025 10:10:40 +0000 (UTC) X-FDA: 83600761440.11.B18E0C1 Received: from mail-wr1-f42.google.com (mail-wr1-f42.google.com [209.85.221.42]) by imf17.hostedemail.com (Postfix) with ESMTP id 2737640010 for ; Fri, 27 Jun 2025 10:10:37 +0000 (UTC) Authentication-Results: imf17.hostedemail.com; dkim=pass header.d=suse.com header.s=google header.b=Knovd41H; spf=pass (imf17.hostedemail.com: domain of ptesarik@suse.com designates 209.85.221.42 as permitted sender) smtp.mailfrom=ptesarik@suse.com; dmarc=pass (policy=quarantine) header.from=suse.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1751019038; a=rsa-sha256; cv=none; b=n4WWDR1IM/M7LsBz8tMrJHTvya5iNsUjcFmORVo5sUXjhEpzVFQMCJgcCMikKpTPCOWzqi vpO6bWRJ83AR5Zt2Qow6bst/j2pqEnB8GBRToMY6fCUe9wHWygrUrV33HNb9FsHgQpLfy3 WxYSX9xS5AfXz0QxmU0hnTCiUuB3DjQ= ARC-Authentication-Results: i=1; imf17.hostedemail.com; dkim=pass header.d=suse.com header.s=google header.b=Knovd41H; spf=pass (imf17.hostedemail.com: domain of ptesarik@suse.com designates 209.85.221.42 as permitted sender) smtp.mailfrom=ptesarik@suse.com; dmarc=pass (policy=quarantine) header.from=suse.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1751019038; 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-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=+TquI4kf2LD9Vztrqxbozxq9qf65pOiNFo4XcEnHd+w=; b=mU4yT8jafN2OHP3Wk08Dk3DgVB98/i3cIEYJuZiwmMqOylvwrCi59YZUD197DEZhmrCmU9 VQLRZlTDSOgD0JrA8uLM/R21APOGcYmxe8vuAm5GeEz2hTPIBPma9KuLIrmZmyKeQQio+V XNLIKt9HjxNqxLcPUGZmS8ybjJvrOso= Received: by mail-wr1-f42.google.com with SMTP id ffacd0b85a97d-3a6f24ef3acso211200f8f.3 for ; Fri, 27 Jun 2025 03:10:37 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=google; t=1751019037; x=1751623837; darn=kvack.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=+TquI4kf2LD9Vztrqxbozxq9qf65pOiNFo4XcEnHd+w=; b=Knovd41HTkLz+KVkwvNttjF+VeeHD7J+dIXNGjTKB2BM0TwwluUPM1GctxhyC3pw0/ TvKn1VZnRvQQGStGWNiKaX3gjivlycmmferfV2I7Bha4obZCkpOd5xhaGw5wGycN1PHV 6mcJcCMWLven/MFdsUzrkeo/9cWmB8++kUBMDULzMuQvl5Q1szZTGX97sp3CLjY9lQaD hWSxO0GjXd9ruxxrrLTOtw78NdHB9Wm3jZ3IgniRa30Qcu+T2ejuxQ0MrWjA+OMmIr+L 0sZZ14StEwb/QtHQ1nmt/34LJzy39cJ6bq8GmW2fMV+v1jTI718f4+b4ypF0MLqfmFpW RIkQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1751019037; x=1751623837; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=+TquI4kf2LD9Vztrqxbozxq9qf65pOiNFo4XcEnHd+w=; b=q3KnV+2NU4tqtXq1h31Bt6J4QLsg1L6dAxVCftPsXv15GK2sdNFpe4fqwUXBl1tSJ5 Q82YJ64FuYk8wZSES3Udn5zQqTXMQ82KM53WSmtax1WTIJ6rAmCF3X5NAZtZBE/fWbfE Cymbb3sigZ1UgyzdmN5meuH+gZG7TPE6KfRgMWiacJ/UNM+z7lBvRo+qmUOQVcGHApxu WjH2XWBOFk4qn6lNC3z2yBaBXDyrDbeI7X8Y4cvp6Ys2cNLnNIEgNB34BxZQR7mXcVH+ dWpvceoVz0muzYPAAUh5nU7OKiKSREVUOfezUrof2qDMqtvakj4T5BEO+nvcBSPes6qE b2+g== X-Forwarded-Encrypted: i=1; AJvYcCU6rEKfBgwCS4+/O8y4nmmd8R5wOlg9kdmIVzi9tskcWyiHy4pYuCDoAsCAKEmDXZnYDxxsrnZT5Q==@kvack.org X-Gm-Message-State: AOJu0YwX3YlE5TCrSEHEdzolvMB+mJcv/99NoavEn1YBuSLKKKJrm7qn YvU3GD//n6WK2ylq7DWVT+a3t6nqAuRu1CNbGSkcRxU0DvC7ZxrDwlw8KbY02RybN88= X-Gm-Gg: ASbGncsWTt0hovUXqWiQqqksl9zDI2D5rXAUUhNYvIRijBOEU2m6NyFopDNOai4xLni K1Xlv3HhiNPIWdYiBuvpB+eWx4ZR2CXrZodHz2sixq+U0ya4AL05vmwlbQAbbys8b3JsBBQvQel zzWRc4QWaxqUHbWlOHck9pUr3gh9htpGwSW3XW/ESzzWCKMm7CVkJzP9vNN4Ps0Qov04etWeN8w OSzERgN7LIsYpmOA/PJ86uqTkL5wP+NVybXae2Le7jmSEMlEWS+1YO0587QEYhpWdy2TGomXAQy 0v7lKfA9G94qzBQPDnmd+FNJB+6Di1gC/ECbFBNLgU6jpu32dXiP7hyhT1fiNC2iuLO29AlJeVX Xn73+CEa6Xv72iBrXXEknU/4EmBguqgOOFAnPHcQ6sqdIKrRqlPaZLH4bMiAijXo= X-Google-Smtp-Source: AGHT+IErhL/Jp/Zzw50DopSUtmqu7kBNtcSnX1TVkRC2/Elb7ZST13WhfXT1w6C3WIxy5rXTNtnoKQ== X-Received: by 2002:adf:b652:0:b0:3a3:6e85:a550 with SMTP id ffacd0b85a97d-3a8fe1dd5ecmr831103f8f.5.1751019036624; Fri, 27 Jun 2025 03:10:36 -0700 (PDT) Received: from localhost (dynamic-2a00-1028-83b8-1e7a-3010-3bd6-8521-caf1.ipv6.o2.cz. [2a00:1028:83b8:1e7a:3010:3bd6:8521:caf1]) by smtp.gmail.com with UTF8SMTPSA id ffacd0b85a97d-3a892e52a26sm2290796f8f.51.2025.06.27.03.10.35 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 27 Jun 2025 03:10:36 -0700 (PDT) From: Petr Tesarik To: Jonathan Corbet , Randy Dunlap , Robin Murphy , Marek Szyprowski Cc: Andrew Morton , Keith Busch , Jens Axboe , Bagas Sanjaya , linux-doc@vger.kernel.org (open list:DOCUMENTATION), linux-kernel@vger.kernel.org (open list), linux-mm@kvack.org (open list:MEMORY MANAGEMENT), Petr Tesarik , iommu@lists.linux.dev Subject: [PATCH v2 7/8] docs: dma-api: update streaming DMA physical address constraints Date: Fri, 27 Jun 2025 12:10:14 +0200 Message-ID: <20250627101015.1600042-8-ptesarik@suse.com> X-Mailer: git-send-email 2.49.0 In-Reply-To: <20250627101015.1600042-1-ptesarik@suse.com> References: <20250627101015.1600042-1-ptesarik@suse.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Stat-Signature: xnbzcbru4fspj59y34yffnnchy8m664j X-Rspamd-Server: rspam05 X-Rspamd-Queue-Id: 2737640010 X-Rspam-User: X-HE-Tag: 1751019037-591695 X-HE-Meta: U2FsdGVkX19BbSzIyFVKKYnm/JtrB70xqTnwJOwDz1MP5CWPfTsFgLEwoH45QsE3cFCHp9DsPYSU9vcSvX27TP2gpXQV6WSN1GwrhjfIZFOTbogx+VoZJLG/pA0ad/F+z+LN1QJs9rxtvm47K9VKrOeZqYBf9LU/OmOtwCddLyEqZHvTPu2BJ4KGQFY+xIkCyPw0Zo2JyL4S9UUJ0L6RBQdSQLMWBF/3RzBZbq2wk0PK7A3HSqe8+rUqYpX3ik83RBzoth08xzjDpLm7RQOMwdDJpZEkhDozc8v7Caoq/z5rRSuyzptm2ZbeYpG32JclcxLgVPt3WRWL+LVh/Yj27wE6WQ4wAOKzF23Inw/3TmroBYUGd9wb9nx++WIfsoM8v9aeBeWxqz8yiYe29pKrTUVnPTK8GVgz8tlkUGOfUlzECb0ZFJTXiWf/IOUMlIatYeQslp2Sh0ZVbFmmCmFKMOy+MAnYbaVOWLdspcKBtVY2vP/asuGw2T7whxGMRybV5VEr5kO2EXrglZDozQHPYoKVPrUfNwBQMjCdIVikvcAJA+kRP3HGMegMMFPyN630C+r0dyQ0BChcpP4tyx9abnSsAz5HQYTlH4lH3qTjksYk9qZ/fnQ2eaKv4v+BuE4EIiWlAOuFV+v2Fifs1dEmGstcka/ErXv8XZHCrVqGCIxpwfRFGHcaHXyfQz65OufBvHzaKHOChL4szue6uzM3ArsDdZONQ6qTkdEsUyd+4UVpT6b2adrxk7C2VfXdgSJIZyt/5F1S1NNjziEyiUMWcnO9LX/GZmzpPUntyKqZN/Oxud7ooY1SKTBPxDucGi2yXozjev6J+hnRg++HEQ9wlvCjX6nE85BWsLkUy075qgMj5lkq3qV78D+E+6/RQpqCJUAoCXVf7jffu99rdavMXNye1tu9Dbk4GumorMd8kvISEUnlmDbtiQNqBl+hvD5Ljl+SJVsOWpjSgNPLGnj CSM5qDXt AbKaO/NVzmfrcam0h6DesMnTaKsN9o8TgYt2u6dPrh8R6qY5TWwtbynXZvGiQJiwHMh/p/BS77hRYCwsphTb74pioUTfJ/N39qG6Z2g/NVnrl29gMfa8XmVnFIaJzg9tSPzOIaALgrRcfeu1+aP331sWI5coj8QJrxezqskqkrxKpxJCv8czOWBQKgSJ4tcI51jAB2pqjVxTf34xqBgFXKGdlWMiquhO5D+TA9BuC/iUGBRkLUC8sZai/7vDWtSQf6twzaTDO4swwI33KRo0srsiJh2Q4M9i/peM6THhuI04FZs1aVaEZS485fGGpEwQXQMxFMdDQHWMzkcHrlIu+kVTyvQ== 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: Add an introductory paragraph to Part Id - Streaming DMA mappings and move the explanation of address constraints there, because it applies to all map functions. Clarify that streaming DMA can be used with memory which does not meet the addressing constraints of a device, but it may fail in that case. Make a note about SWIOTLB and link to the detailed description of it. Do not mention platform-dependent allocation flags. The note may mislead device driver authors into thinking that they should poke into and try to second-guess the DMA API implementation. They definitely shouldn't. Remove the claim that platforms with an IOMMU may not require physically contiguous buffers. The current implementation explicitly rejects vmalloc addresses, regardless of IOMMU. Signed-off-by: Petr Tesarik --- Documentation/core-api/dma-api.rst | 36 +++++++++++++++++------------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst index 9fcdb160638e0..a075550ebbb54 100644 --- a/Documentation/core-api/dma-api.rst +++ b/Documentation/core-api/dma-api.rst @@ -184,6 +184,26 @@ segments, the function returns 0. Part Id - Streaming DMA mappings -------------------------------- +Streaming DMA allows to map an existing buffer for DMA transfers and then +unmap it when finished. Map functions are not guaranteed to succeed, so the +return value must be checked. + +.. note:: + + In particular, mapping may fail for memory not addressable by the + device, e.g. if it is not within the DMA mask of the device and/or a + connecting bus bridge. Streaming DMA functions try to overcome such + addressing constraints, either by using an IOMMU (a device which maps + I/O DMA addresses to physical memory addresses), or by copying the + data to/from a bounce buffer if the kernel is configured with a + :doc:`SWIOTLB `. However, these methods are not always + available, and even if they are, they may still fail for a number of + reasons. + + In short, a device driver may need to be wary of where buffers are + located in physical memory, especially if the DMA mask is less than 32 + bits. + :: dma_addr_t @@ -204,27 +224,13 @@ DMA_BIDIRECTIONAL direction isn't known .. note:: - Not all memory regions in a machine can be mapped by this API. - Further, contiguous kernel virtual space may not be contiguous as + Contiguous kernel virtual space may not be contiguous as physical memory. Since this API does not provide any scatter/gather capability, it will fail if the user tries to map a non-physically contiguous piece of memory. For this reason, memory to be mapped by this API should be obtained from sources which guarantee it to be physically contiguous (like kmalloc). - Further, the DMA address of the memory must be within the dma_mask of - the device. To ensure that the memory allocated by kmalloc is within - the dma_mask, the driver may specify various platform-dependent flags - to restrict the DMA address range of the allocation (e.g., on x86, - GFP_DMA guarantees to be within the first 16MB of available DMA - addresses, as required by ISA devices). - - Note also that the above constraints on physical contiguity and - dma_mask may not apply if the platform has an IOMMU (a device which - maps an I/O DMA address to a physical memory address). However, to be - portable, device driver writers may *not* assume that such an IOMMU - exists. - .. warning:: Memory coherency operates at a granularity called the cache -- 2.49.0