From nobody Wed Oct 8 13:27:06 2025 Received: from mail-wr1-f46.google.com (mail-wr1-f46.google.com [209.85.221.46]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 7A0E3298CA2 for ; Fri, 27 Jun 2025 10:10:22 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.46 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751019024; cv=none; b=JXZU3CtncK6wwXyL6eXiXruYAHZBRDvoD2YOUxw51zfSlQieaXJClKRx9g5/bfCb8BZOAjP53WzfqpvchyGOHCWS5wA5ISc+oG5OIR8wP4svNpiWVubRPhn0GBb9nObUf2nZdiBSn/YipQfFdFg593aorNU253JA0tUS4FhpldQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751019024; c=relaxed/simple; bh=BUrtkuU0GNtLGvxwO3DTlvmmCqCxudl5NEHe+to6l5g=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=O3AWxH31+Gd/36K/I9aGpKeO1yqPzKapmAhf9NQ0mFhWt+GucrkjqyDe/OU+JAuPAqZgP97Mw7xC9hKMYXUa85oxyAqsF9FuWs33dCATkUH1OAFI0ydBKJWRAIdPZEj8LSpAmgrr5lrKOMVLC+TdG+VVDbElESYslIAryyW852w= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=suse.com; spf=pass smtp.mailfrom=suse.com; dkim=pass (2048-bit key) header.d=suse.com header.i=@suse.com header.b=bmbuBhIu; arc=none smtp.client-ip=209.85.221.46 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=suse.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=suse.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=suse.com header.i=@suse.com header.b="bmbuBhIu" Received: by mail-wr1-f46.google.com with SMTP id ffacd0b85a97d-3a4e749d7b2so318509f8f.0 for ; Fri, 27 Jun 2025 03:10:22 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=google; t=1751019021; x=1751623821; darn=vger.kernel.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=w3xq9CnnryfUDxSUQF9GpV8PIE+GCE84sbP2gNrPwwc=; b=bmbuBhIu5GeV3m0+BYeroVFz+fQcxry1duItb2Wa5M+jWEwpi7eY5xCtQBE7kbIyjg SNvKJCcm4qFhPmfD1qTMPBZ4QjGat72dc9EKC5HcKLoPq5+JBvXKXlRl8FjqlEnrIirB UO6H3+jhyJp2Fh8twjXbQFOEmQ5tR9yIYYRvPhOffoWEwihLEU+YxfbFJ3XjncqqTdbU XVLwnkC3huHKwRQxSRUYzl/M7LIlxrF02nUL79tzn1HXw3tSI4xf2m9npsGGh/WkcvO4 OhKJvTdcMSQwmCpdhb94QrT3E9kosaMZ2stMkdqpZAcd7s4FQelvhybOiFoLqQBGWZa4 m36w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1751019021; x=1751623821; 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=w3xq9CnnryfUDxSUQF9GpV8PIE+GCE84sbP2gNrPwwc=; b=WTe3O/EZYfpeUZxysm153rCUGXTxbu0Ko99TSnG+hSdyenv6r1pGxginoxmI6r8zvl CDTWoK1+2VGfyKkFfejT/m4zd56lCImDuvoKhY7TDo5RSRRjmpO9VVkChU0kquQVMyWU uvBVYDpAHr3luBkwQSbZAnm4jr5m4cmPABTaNVX/BV47zbtJud/K3UULI9dJk5fJdyox hp+j6hFVWgEUbs7H0/OoWhmwyjZdHQlaj4JpSX/N9undi6Qmgou0KIF2ErLGX9CxbRCP e4TnxvBrdXAjFfnTPSEy5jWPGF165OzoVI2hEdczIQePXjM3KCEH2IjSKPxMs5m0SKg1 7Zbw== X-Forwarded-Encrypted: i=1; AJvYcCVhysN1W4u9HyimYF0CE/eDir+rT5gTP72uK72edQqcVubV5GVPwjdAMPyyjYTL0doJTnN9zGYme2Abn3c=@vger.kernel.org X-Gm-Message-State: AOJu0YwRBAvnGHmaWdmEpcv+xkPToltcXQRvTMqoLt+d9eDmKcj0E6OR nEj/n42fGGoEfjy4/isikvP43x+NxKHhhsMNqDzpMQ7eox3i3uluP0dKmkBx3M88clU= X-Gm-Gg: ASbGncuPqTnl/71O7QGU5m2Wekb/OKA9XPNdi/aHrZP19wmuCX1YnBJR4bm7lWiaZvw kS0Y6w80TbnxABsDIaaqoZibJe5kIAflWTz3qzNkoSevx7XNm+pu6Qa/WPNfq+e9eBvLwRVihrz A6u/RVrsIw2spi3acoXbKzJAeSNmwudmSkqI8bjWISY4QiW2iCkMH8eO1Xad75R6TvB2avT8MVn T33b1yjefRRAGcCCEUuqWprSgqFWfAaCotmoWBOBiZuiHkXcYIpGNYZ/5Lgy6sQamT//DILrUBZ HEI4nu5BPJQzsAlEMzOBdg5ENnjqT3HpIieaTw7Dj2ayug7vxh32jIwItNP0+QooOOemFeIDPkC aPzc04KCrifs0GoL94Q94U3seIurIDNYdC1g00GKY7JXyLUOPA3/Y X-Google-Smtp-Source: AGHT+IFl9NeQHOTdy/+Ly2ukX55GHMuwNJpmvj1Ce+Om/UQDamucwxW4fiFQPB/A8qZbOum6aIcqTw== X-Received: by 2002:a5d:5f53:0:b0:3a3:584b:f5d7 with SMTP id ffacd0b85a97d-3a90c551c42mr942241f8f.5.1751019020637; Fri, 27 Jun 2025 03:10:20 -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-3a892e52ca4sm2286180f8f.58.2025.06.27.03.10.20 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 27 Jun 2025 03:10:20 -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 Subject: [PATCH v2 1/8] docs: dma-api: use "DMA API" consistently throughout the document Date: Fri, 27 Jun 2025 12:10:08 +0200 Message-ID: <20250627101015.1600042-2-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> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Make sure that all occurrences are spelled "DMA API" (all uppercase, no hyphen, no underscore). Signed-off-by: Petr Tesarik Reviewed-by: Randy Dunlap Acked-by: Marek Szyprowski Tested-by: Randy Dunlap --- Documentation/core-api/dma-api.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dm= a-api.rst index 2ad08517e626e..97f42c15f5e43 100644 --- a/Documentation/core-api/dma-api.rst +++ b/Documentation/core-api/dma-api.rst @@ -13,10 +13,10 @@ machines. Unless you know that your driver absolutely = has to support non-consistent platforms (this is usually only legacy platforms) you should only use the API described in part I. =20 -Part I - dma_API +Part I - DMA API ---------------- =20 -To get the dma_API, you must #include . This +To get the DMA API, you must #include . This provides dma_addr_t and the interfaces described below. =20 A dma_addr_t can hold any valid DMA address for the platform. It can be @@ -76,7 +76,7 @@ may only be called with IRQs enabled. Part Ib - Using small DMA-coherent buffers ------------------------------------------ =20 -To get this part of the dma_API, you must #include +To get this part of the DMA API, you must #include =20 Many drivers need lots of small DMA-coherent memory regions for DMA descriptors or I/O buffers. Rather than allocating in units of a page @@ -247,7 +247,7 @@ Maps a piece of processor virtual memory so it can be a= ccessed by the device and returns the DMA address of the memory. =20 The direction for both APIs may be converted freely by casting. -However the dma_API uses a strongly typed enumerator for its +However the DMA API uses a strongly typed enumerator for its direction: =20 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -775,19 +775,19 @@ memory or doing partial flushes. of two for easy alignment. =20 =20 -Part III - Debug drivers use of the DMA-API +Part III - Debug drivers use of the DMA API ------------------------------------------- =20 -The DMA-API as described above has some constraints. DMA addresses must be +The DMA API as described above has some constraints. DMA addresses must be released with the corresponding function with the same size for example. W= ith the advent of hardware IOMMUs it becomes more and more important that driv= ers do not violate those constraints. In the worst case such a violation can result in data corruption up to destroyed filesystems. =20 -To debug drivers and find bugs in the usage of the DMA-API checking code c= an +To debug drivers and find bugs in the usage of the DMA API checking code c= an be compiled into the kernel which will tell the developer about those violations. If your architecture supports it you can select the "Enable -debugging of DMA-API usage" option in your kernel configuration. Enabling = this +debugging of DMA API usage" option in your kernel configuration. Enabling = this option has a performance impact. Do not enable it in production kernels. =20 If you boot the resulting kernel will contain code which does some bookkee= ping @@ -826,7 +826,7 @@ example warning message may look like this:: <4>---[ end trace f6435a98e2a38c0e ]--- =20 The driver developer can find the driver and the device including a stackt= race -of the DMA-API call which caused this warning. +of the DMA API call which caused this warning. =20 Per default only the first error will result in a warning message. All oth= er errors will only silently counted. This limitation exist to prevent the co= de @@ -834,7 +834,7 @@ from flooding your kernel log. To support debugging a d= evice driver this can be disabled via debugfs. See the debugfs interface documentation below for details. =20 -The debugfs directory for the DMA-API debugging code is called dma-api/. In +The debugfs directory for the DMA API debugging code is called dma-api/. In this directory the following files can currently be found: =20 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D @@ -882,7 +882,7 @@ dma-api/driver_filter You can write a name of a driver= into this file =20 If you have this code compiled into your kernel it will be enabled by defa= ult. If you want to boot without the bookkeeping anyway you can provide -'dma_debug=3Doff' as a boot parameter. This will disable DMA-API debugging. +'dma_debug=3Doff' as a boot parameter. This will disable DMA API debugging. Notice that you can not enable it again at runtime. You have to reboot to = do so. =20 --=20 2.49.0 From nobody Wed Oct 8 13:27:06 2025 Received: from mail-wm1-f49.google.com (mail-wm1-f49.google.com [209.85.128.49]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id D4C4929992B for ; Fri, 27 Jun 2025 10:10:25 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.49 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751019028; cv=none; b=unXYIxmaracrc6T2Eoj1X6GGLa4H4gF76NDVMgbs2GLNTsKV7pT4FeMiXhoS5BfSWyiiM7+0b2tNZfOUfqROJ94TG7lUpGIA79l6cTBYPDmh0lNfvBbLVMeUZ2ydCsr+L/UcY/7dv11wP8wiCJgVqMGUapJi1hvtizbvwPRXbTM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751019028; c=relaxed/simple; bh=hHwtqUaEFph1e9dx7UvXr1mnmNdG4H8BsBjki4vvZPk=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=GdU2aWh/9qzsL893GT7KHWJ36RJVQ7BwTkVAL7SQ2VIaUB71IZSmgmDvnYbadzn1CX6mmtHRv89TipxtuuzoCpj4y6au1KV+shKZRhWKmRZ5VwLHXL4i6m8I+klcl1/ZM7gS9zsbv+W1KvXjE4SgzeY9F5Tb9lC/zojK3WojnNE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=suse.com; spf=pass smtp.mailfrom=suse.com; dkim=pass (2048-bit key) header.d=suse.com header.i=@suse.com header.b=SMtUKHXv; arc=none smtp.client-ip=209.85.128.49 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=suse.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=suse.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=suse.com header.i=@suse.com header.b="SMtUKHXv" Received: by mail-wm1-f49.google.com with SMTP id 5b1f17b1804b1-45362642f3bso2835045e9.2 for ; Fri, 27 Jun 2025 03:10:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=google; t=1751019024; x=1751623824; darn=vger.kernel.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=TpQ7AkRvShs03kmO7VCXGfaSepdwFFSh/faqrQd+6cQ=; b=SMtUKHXvIdRq0F8XgShO3qI6Np9dY6DzbSIZjxke8Z3syHr0kpycbJ75WnsfjTMYsW FD53hqx9pARNzld7PimTAaRVokVgPzfZQNigni2SfGpzUocXQ80Xik6dE76WBXCU8C7W n3Fimiy/dk0H1aO+hhEACAd5+LCH2XdGeh5ZhwMg8wwe1wR3Ak5mcpWUbtAtNA10XMOH 7B6jlmwSx+MbWihbpFjj3tY67+EDzTo9QBWnZrzVZ8hTFh+/LY5OUb1ePaD7HPh2KDRS NuSGIBq+9kXU/C5wN4QB5a8gB0XVHn88tMN1R3ep4zEWwh9NHjh0tuY0TaPYZreBlgrl nphw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1751019024; x=1751623824; 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=TpQ7AkRvShs03kmO7VCXGfaSepdwFFSh/faqrQd+6cQ=; b=S93MIkgCCUzg5hLv1TPQ9bDTG58Oz4BrjB3aTbKq/Eyq2mgEIt7R54mc5uR3yZ3Vq2 pWu4N/bEMQ1vvFhm1HlvujMtOOf6ADmYhSIMKgFDpQg/b2xq7Ran1wT3JGPHJl/HUeaM G53E16UMaUhVUPyRuI7UqvPOHPW/Zb2Sv/ByXlLO/Aet1MnDfU+4kjZOdG5lej8NCPKt WKHqg4WM3faJK2JkNAhs0W83ko3kj26lghW7hqLbbU4JryC/zPUSWHg9MbybjJfFIHEZ gD57j2ZQW/chzSBOby25wD0000MBPnG3MIqfKHNMKDHsgVA4nioGUi/hucdaSMab2d3O bdqg== X-Forwarded-Encrypted: i=1; AJvYcCVXaa/f9Cep+oVgjtz+KxEL/KK89IxllpOkXr7598y0P/9/NdHzgzY+OpDGH8qdKA7xsv3d5MWBvf0Vli8=@vger.kernel.org X-Gm-Message-State: AOJu0Yx2tiyijbZyz/zW8fA1agmLUQ6MDLrC+DjA/VlpuY/gkpUqW+80 t7neYbalQBmN9uZHiMFGsYE+ECy9+iM7/PwmiTXkT4VbtzE7JWPK02yYrIXqSP7qOHQ= X-Gm-Gg: ASbGncsgWA48gB1TSQ6uqVvhgWc+Hoick6fFZRCRqRIdrloBe1zWWgjnJxEUfFztbmh U4uT2HLIADPpVLz7Fg89p+DautbMYcpGa8JDb5Rvp9VZ0bHuJp+TB1DINKbw/ZzH9Yf6mEXAJur Ox/mAgl8tx7EX9Nl8+DXka+fpwh86fPlUQ3p7ZHYA3yuX1W7k4tsG8pPXpdN/k0dIvYLh+BkKv4 r6WQXdCMDSk7AkHcBBdMw54qcO0jvnpNLFpDl/lY3rw5VpfYjPkEKJ+XgWwjrR6gWkX/als3Mvj ldmKPnyk8UpfrH2qVMVa33qhRhy43urOyyHyrcxj4H8Fp4aaG8blpsr85B/dQgGF7haWQ2ADsz2 sMgHWEaclZLfwXe+/MCo/DO0OT2+uInQONWu89p4ICe9XIIZ4B03U X-Google-Smtp-Source: AGHT+IEdyquFfyx9KUX5NVl3Szzj+1MmtSq9TEoKItOj38mGNZ/23I3A2OT7FNM9TsLGyfqL0ocpUg== X-Received: by 2002:a05:600c:4ec8:b0:43b:c0fa:f9c4 with SMTP id 5b1f17b1804b1-4538f8834b1mr8127595e9.4.1751019024073; Fri, 27 Jun 2025 03:10:24 -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 5b1f17b1804b1-4538a3fe0d6sm45512065e9.25.2025.06.27.03.10.22 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 27 Jun 2025 03:10:23 -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 2/8] docs: dma-api: replace consistent with coherent Date: Fri, 27 Jun 2025 12:10:09 +0200 Message-ID: <20250627101015.1600042-3-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> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" For consistency, always use the term "coherent" when talking about memory that is not subject to CPU caching effects. The term "consistent" is a relic of a long-removed PCI DMA API (pci_alloc_consistent() and pci_free_consistent() functions). Signed-off-by: Petr Tesarik Acked-by: Marek Szyprowski Tested-by: Randy Dunlap --- Documentation/core-api/dma-api-howto.rst | 36 ++++++++++++------------ Documentation/core-api/dma-api.rst | 14 ++++----- mm/dmapool.c | 6 ++-- 3 files changed, 28 insertions(+), 28 deletions(-) diff --git a/Documentation/core-api/dma-api-howto.rst b/Documentation/core-= api/dma-api-howto.rst index 0bf31b6c4383c..96fce2a9aa901 100644 --- a/Documentation/core-api/dma-api-howto.rst +++ b/Documentation/core-api/dma-api-howto.rst @@ -155,7 +155,7 @@ a device with limitations, it needs to be decreased. =20 Special note about PCI: PCI-X specification requires PCI-X devices to supp= ort 64-bit addressing (DAC) for all transactions. And at least one platform (= SGI -SN2) requires 64-bit consistent allocations to operate correctly when the = IO +SN2) requires 64-bit coherent allocations to operate correctly when the IO bus is in PCI-X mode. =20 For correct operation, you must set the DMA mask to inform the kernel about @@ -174,7 +174,7 @@ used instead: =20 int dma_set_mask(struct device *dev, u64 mask); =20 - The setup for consistent allocations is performed via a call + The setup for coherent allocations is performed via a call to dma_set_coherent_mask():: =20 int dma_set_coherent_mask(struct device *dev, u64 mask); @@ -241,7 +241,7 @@ it would look like this:: =20 The coherent mask will always be able to set the same or a smaller mask as the streaming mask. However for the rare case that a device driver only -uses consistent allocations, one would have to check the return value from +uses coherent allocations, one would have to check the return value from dma_set_coherent_mask(). =20 Finally, if your device can only drive the low 24-bits of @@ -298,20 +298,20 @@ Types of DMA mappings =20 There are two types of DMA mappings: =20 -- Consistent DMA mappings which are usually mapped at driver +- Coherent DMA mappings which are usually mapped at driver initialization, unmapped at the end and for which the hardware should guarantee that the device and the CPU can access the data in parallel and will see updates made by each other without any explicit software flushing. =20 - Think of "consistent" as "synchronous" or "coherent". + Think of "coherent" as "synchronous". =20 - The current default is to return consistent memory in the low 32 + The current default is to return coherent memory in the low 32 bits of the DMA space. However, for future compatibility you should - set the consistent mask even if this default is fine for your + set the coherent mask even if this default is fine for your driver. =20 - Good examples of what to use consistent mappings for are: + Good examples of what to use coherent mappings for are: =20 - Network card DMA ring descriptors. - SCSI adapter mailbox command data structures. @@ -320,13 +320,13 @@ There are two types of DMA mappings: =20 The invariant these examples all require is that any CPU store to memory is immediately visible to the device, and vice - versa. Consistent mappings guarantee this. + versa. Coherent mappings guarantee this. =20 .. important:: =20 - Consistent DMA memory does not preclude the usage of + Coherent DMA memory does not preclude the usage of proper memory barriers. The CPU may reorder stores to - consistent memory just as it may normal memory. Example: + coherent memory just as it may normal memory. Example: if it is important for the device to see the first word of a descriptor updated before the second, you must do something like:: @@ -365,10 +365,10 @@ Also, systems with caches that aren't DMA-coherent wi= ll work better when the underlying buffers don't share cache lines with other data. =20 =20 -Using Consistent DMA mappings -=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D +Using Coherent DMA mappings +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D =20 -To allocate and map large (PAGE_SIZE or so) consistent DMA regions, +To allocate and map large (PAGE_SIZE or so) coherent DMA regions, you should do:: =20 dma_addr_t dma_handle; @@ -385,10 +385,10 @@ __get_free_pages() (but takes size instead of a page = order). If your driver needs regions sized smaller than a page, you may prefer using the dma_pool interface, described below. =20 -The consistent DMA mapping interfaces, will by default return a DMA address +The coherent DMA mapping interfaces, will by default return a DMA address which is 32-bit addressable. Even if the device indicates (via the DMA ma= sk) -that it may address the upper 32-bits, consistent allocation will only -return > 32-bit addresses for DMA if the consistent DMA mask has been +that it may address the upper 32-bits, coherent allocation will only +return > 32-bit addresses for DMA if the coherent DMA mask has been explicitly changed via dma_set_coherent_mask(). This is true of the dma_pool interface as well. =20 @@ -497,7 +497,7 @@ program address space. Such platforms can and do repor= t errors in the kernel logs when the DMA controller hardware detects violation of the permission setting. =20 -Only streaming mappings specify a direction, consistent mappings +Only streaming mappings specify a direction, coherent mappings implicitly have a direction attribute setting of DMA_BIDIRECTIONAL. =20 diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dm= a-api.rst index 97f42c15f5e43..c0a2cc7d0b959 100644 --- a/Documentation/core-api/dma-api.rst +++ b/Documentation/core-api/dma-api.rst @@ -8,9 +8,9 @@ This document describes the DMA API. For a more gentle int= roduction of the API (and actual examples), see Documentation/core-api/dma-api-howto= .rst. =20 This API is split into two pieces. Part I describes the basic API. -Part II describes extensions for supporting non-consistent memory +Part II describes extensions for supporting non-coherent memory machines. Unless you know that your driver absolutely has to support -non-consistent platforms (this is usually only legacy platforms) you +non-coherent platforms (this is usually only legacy platforms) you should only use the API described in part I. =20 Part I - DMA API @@ -33,13 +33,13 @@ Part Ia - Using large DMA-coherent buffers dma_alloc_coherent(struct device *dev, size_t size, dma_addr_t *dma_handle, gfp_t flag) =20 -Consistent memory is memory for which a write by either the device or +Coherent memory is memory for which a write by either the device or the processor can immediately be read by the processor or device without having to worry about caching effects. (You may however need to make sure to flush the processor's write buffers before telling devices to read that memory.) =20 -This routine allocates a region of bytes of consistent memory. +This routine allocates a region of bytes of coherent memory. =20 It returns a pointer to the allocated region (in the processor's virtual address space) or NULL if the allocation failed. @@ -48,9 +48,9 @@ It also returns a which may be cast to an un= signed integer the same width as the bus and given to the device as the DMA address base of the region. =20 -Note: consistent memory can be expensive on some platforms, and the +Note: coherent memory can be expensive on some platforms, and the minimum allocation length may be as big as a page, so you should -consolidate your requests for consistent memory as much as possible. +consolidate your requests for coherent memory as much as possible. The simplest way to do that is to use the dma_pool calls (see below). =20 The flag parameter (dma_alloc_coherent() only) allows the caller to @@ -64,7 +64,7 @@ the returned memory, like GFP_DMA). dma_free_coherent(struct device *dev, size_t size, void *cpu_addr, dma_addr_t dma_handle) =20 -Free a region of consistent memory you previously allocated. dev, +Free a region of coherent memory you previously allocated. dev, size and dma_handle must all be the same as those passed into dma_alloc_coherent(). cpu_addr must be the virtual address returned by the dma_alloc_coherent(). diff --git a/mm/dmapool.c b/mm/dmapool.c index 5be8cc1c65292..5d8af6e291276 100644 --- a/mm/dmapool.c +++ b/mm/dmapool.c @@ -200,7 +200,7 @@ static void pool_block_push(struct dma_pool *pool, stru= ct dma_block *block, =20 =20 /** - * dma_pool_create_node - Creates a pool of consistent memory blocks, for = dma. + * dma_pool_create_node - Creates a pool of coherent DMA memory blocks. * @name: name of pool, for diagnostics * @dev: device that will be doing the DMA * @size: size of the blocks in this pool. @@ -210,7 +210,7 @@ static void pool_block_push(struct dma_pool *pool, stru= ct dma_block *block, * Context: not in_interrupt() * * Given one of these pools, dma_pool_alloc() - * may be used to allocate memory. Such memory will all have "consistent" + * may be used to allocate memory. Such memory will all have coherent * DMA mappings, accessible by the device and its driver without using * cache flushing primitives. The actual size of blocks allocated may be * larger than requested because of alignment. @@ -395,7 +395,7 @@ void dma_pool_destroy(struct dma_pool *pool) EXPORT_SYMBOL(dma_pool_destroy); =20 /** - * dma_pool_alloc - get a block of consistent memory + * dma_pool_alloc - get a block of coherent memory * @pool: dma pool that will produce the block * @mem_flags: GFP_* bitmask * @handle: pointer to dma address of block --=20 2.49.0 From nobody Wed Oct 8 13:27:06 2025 Received: from mail-wr1-f41.google.com (mail-wr1-f41.google.com [209.85.221.41]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 97C342BEFFF for ; Fri, 27 Jun 2025 10:10:28 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.41 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751019030; cv=none; b=tn+wVLkBcDL3VgCa7Mv9CPs48ba4poQLlqBczUYpp64JRftBWbgktf6bs4b3RY2/G83yPTKX7IReEk6+3MQnqpkcUkvxrq0XhRJAUg2g0KbUjR6x0MERF2HMTzSquCSgB377mEAaPzndZ+pZAKAspENf9X9l96ZfMlki+joMb9w= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751019030; c=relaxed/simple; bh=VO+P2GSdqpL3yvynRfRhH8v4iWnJAPq8glERuUFSA90=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=rnP5uKcQRlOs1Fw3OJ4lLNM/In2/Z4W4BkaPbJ/wDCQmsR5+p23hiZSKIPm1w6Qt9f5Bnli2d/jYWtRCcgTlOrEeBcR1/gjeteeiKT5RxXuiXydeUPRfXWl/u1dhZLg1tdaTEd3AyPwvqXBjkmpGUpCZG4OWRbDx1WLFxZ2HR0o= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=suse.com; spf=pass smtp.mailfrom=suse.com; dkim=pass (2048-bit key) header.d=suse.com header.i=@suse.com header.b=EPOyqSa4; arc=none smtp.client-ip=209.85.221.41 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=suse.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=suse.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=suse.com header.i=@suse.com header.b="EPOyqSa4" Received: by mail-wr1-f41.google.com with SMTP id ffacd0b85a97d-3a4eed70f24so299793f8f.0 for ; Fri, 27 Jun 2025 03:10:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=google; t=1751019027; x=1751623827; darn=vger.kernel.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=JnKlnox89+aqxPWrx0LhOdTGwWWYyCW4d7dddKDwsrg=; b=EPOyqSa4sLtNfz6F+fZjtxU7guHSqmnRK9lTe3fPDrBIwVwr5JwapU3SjlSWk+6Q8S KMNk79u2AsVOdJ70jQtssaDRgrleLfpFp3SVGDMmnzdXsVivCmD8Lo9gkcXjLKmuN9qM Y5MjsFny1VkrzPMOwdUIxKiG8tGbRQ22FPoATxIvmzs+WNjiv5+I8c4p9cj6JOE0MXY/ 1ayrWA5YhZXbuUfqgW2YjZ5PleBeqAuga3eW8JhCG/UpgmdazkxSRACei9rH1bzZwjdW WjsKc8zohjvLg+YWh94eWbMbCpiqxsv5q45H4zPFPZXSkbr8KwQEaRTde7RngjhaOO/o D3jw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1751019027; x=1751623827; 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=JnKlnox89+aqxPWrx0LhOdTGwWWYyCW4d7dddKDwsrg=; b=pimEUjKnTWWwQn2HXIHNxASFFKdkyk1EIM2PlTEBVENBX3Hg0K59CIDTEFDIhEjbW4 JuHy6lFDesyW3g7WY7IF8zFrKuE2ZkgqcVRCtIWjibJK2UJADSbc4j3GEaPcUGKqY3M2 tDAJLxpHsXAYnv0O3SLrcl9ngpULaa3S2X4nbj/+obF5R8fCvEbLcMz1jHdLX81jB26M lkkF7LaBd9GTlJdlOZSPtex+S+P1aX5OBGi/nobq97BSOJ611aTZ3exvPmZ3QlmVphl3 PrdnFR5Zt0vRt9hQ9f/6BV1EdXURjXQUqdQ/UyhLk4obvKfUP+rBHt4X8WrlOYcum/q1 MwgQ== X-Forwarded-Encrypted: i=1; AJvYcCX5WxRyJBZ0VDlRNKrySR6QScdenp6yKMFGLdbrDaQVyRyI2Y4QLYQeVUBs4yEx6s2RWH0o4HHEWcIqTUk=@vger.kernel.org X-Gm-Message-State: AOJu0YwwGfv4S6dQq1h3orDtsi/Hua2fj//dJcerOviR5y32QPIk3ebV GA1MsOwmn19MGTJ9b/cZNOSxNG/FVyRUZfPeBSV7QJAGtH+4NwuWHt/BdwT0KhXQ+og= X-Gm-Gg: ASbGncvAWl842024kT0JVTdJO1FbQft87D88etiqhxY30peYu8iA6wB8YaXsXLrEsFq VjC89dar3I71tN7nhADXWq187qyAdkL/S9xaVfPCWvsBa8rKFT+UgFvnGvZ2zD1qyvHw7g9cX2i KPOlBxDeF9ZocpNexaTDka6l6sF9mJQqwreoYblVBsz9O4WHKulCdguqvCgDJNtqNGaXamZ/pRD DScvuwslaCw/lQ5gW5Z0VVT7KldIkMHovFIfIJt+1FAnb/UbaJKYgg/LIm2xVaeaNSGvjZAzYXB 88tsf1YTs9mSpIrrau7hUeimI2yDbujNfj78jY+aqNHLBUqF057XC1pHsZQmG9Rdjk3DPW7i61k CJ/Rh6BpOGJWxI4q9NpWBWMfaTlXUYfA88MGTAk1ys4YzUUrcOBnb X-Google-Smtp-Source: AGHT+IHuMh68Tyv7KxWY4j2dyJ3BwGirI46s8aecbMNC3bBEbknxdDdWsYm9o5PlniB0HBGERk1eWA== X-Received: by 2002:adf:9ccb:0:b0:3a4:f7ae:7801 with SMTP id ffacd0b85a97d-3a8fe79bb3cmr805861f8f.8.1751019026969; Fri, 27 Jun 2025 03:10:26 -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 5b1f17b1804b1-4538a3a5599sm46934265e9.13.2025.06.27.03.10.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 27 Jun 2025 03:10:26 -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 Subject: [PATCH v2 3/8] docs: dma-api: remove remnants of PCI DMA API Date: Fri, 27 Jun 2025 12:10:10 +0200 Message-ID: <20250627101015.1600042-4-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> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" The wording sometimes suggests there are multiple functions for an operation. This was in fact the case before PCI DMA API was removed, but since there is only one API now, the documentation has become confusing. To improve readability: * Remove implicit references to the PCI DMA API (plurals, use of "both", etc.) * Where possible, refer to an actual function rather than a more generic description of the operation. Signed-off-by: Petr Tesarik Reviewed-by: Bagas Sanjaya Acked-by: Marek Szyprowski Tested-by: Randy Dunlap --- Documentation/core-api/dma-api.rst | 25 ++++++++++--------------- 1 file changed, 10 insertions(+), 15 deletions(-) diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dm= a-api.rst index c0a2cc7d0b959..3e89e3b0ecfd2 100644 --- a/Documentation/core-api/dma-api.rst +++ b/Documentation/core-api/dma-api.rst @@ -53,10 +53,9 @@ minimum allocation length may be as big as a page, so yo= u should consolidate your requests for coherent memory as much as possible. The simplest way to do that is to use the dma_pool calls (see below). =20 -The flag parameter (dma_alloc_coherent() only) allows the caller to -specify the ``GFP_`` flags (see kmalloc()) for the allocation (the -implementation may choose to ignore flags that affect the location of -the returned memory, like GFP_DMA). +The flag parameter allows the caller to specify the ``GFP_`` flags (see +kmalloc()) for the allocation (the implementation may ignore flags that af= fect +the location of the returned memory, like GFP_DMA). =20 :: =20 @@ -64,13 +63,12 @@ the returned memory, like GFP_DMA). dma_free_coherent(struct device *dev, size_t size, void *cpu_addr, dma_addr_t dma_handle) =20 -Free a region of coherent memory you previously allocated. dev, -size and dma_handle must all be the same as those passed into -dma_alloc_coherent(). cpu_addr must be the virtual address returned by -the dma_alloc_coherent(). +Free a previously allocated region of coherent memory. dev, size and dma_= handle +must all be the same as those passed into dma_alloc_coherent(). cpu_addr = must +be the virtual address returned by dma_alloc_coherent(). =20 -Note that unlike their sibling allocation calls, these routines -may only be called with IRQs enabled. +Note that unlike the sibling allocation call, this routine may only be cal= led +with IRQs enabled. =20 =20 Part Ib - Using small DMA-coherent buffers @@ -246,9 +244,7 @@ Part Id - Streaming DMA mappings Maps a piece of processor virtual memory so it can be accessed by the device and returns the DMA address of the memory. =20 -The direction for both APIs may be converted freely by casting. -However the DMA API uses a strongly typed enumerator for its -direction: +The DMA API uses a strongly typed enumerator for its direction: =20 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D DMA_NONE no direction (used for debugging) @@ -325,8 +321,7 @@ DMA_BIDIRECTIONAL direction isn't known enum dma_data_direction direction) =20 Unmaps the region previously mapped. All the parameters passed in -must be identical to those passed in (and returned) by the mapping -API. +must be identical to those passed to (and returned by) dma_map_single(). =20 :: =20 --=20 2.49.0 From nobody Wed Oct 8 13:27:06 2025 Received: from mail-wr1-f49.google.com (mail-wr1-f49.google.com [209.85.221.49]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id CA38E2BF015 for ; Fri, 27 Jun 2025 10:10:30 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.49 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751019032; cv=none; b=HHmoGj1sbEuKkoDBcQvjstCmeI1o0t/GVeyMJinx5wFrVRdwEumVyFpIjJujx8sYkrP/IBzsa+gSFtak8omtyA1dKaGf6LTGeiKGH1z0Oo+fJQJ9AHN3S+gcL72MTzN9vrrQXwDE3+EOrLp21KuH6R0KFmOweJxPfvgS6LK5zpw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751019032; c=relaxed/simple; bh=+x3y1vqW9Z5Car8CAaRNk20tbSowY5YAsoM75/r+qO8=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=n3OLXwyZibj+6O9L5P7xUOmFEc866Fj5om6Q0Cs7xlqGKku/p9Sd7QYzcuPvu65fhiymLB8SyqvKGHkL3UjKEraPwCXomD3e7tOdC59YmZ60Q38EfpWt0blp9DBJpp4YVUOJxBaMd/T5gmpVzWSBtp96YvOulIVrjg6dANQPyWg= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=suse.com; spf=pass smtp.mailfrom=suse.com; dkim=pass (2048-bit key) header.d=suse.com header.i=@suse.com header.b=bKsSAa+H; arc=none smtp.client-ip=209.85.221.49 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=suse.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=suse.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=suse.com header.i=@suse.com header.b="bKsSAa+H" Received: by mail-wr1-f49.google.com with SMTP id ffacd0b85a97d-3a52878d37aso249242f8f.2 for ; Fri, 27 Jun 2025 03:10:30 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=google; t=1751019029; x=1751623829; darn=vger.kernel.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=5atQvWZ5XtF65GtICFYcWzizaeglvYjKjJ357iLMqgU=; b=bKsSAa+HtNk1Fy6+0XLGMARaYyOGlRb8lAJbIYRcZyfC1jV5Y5SvH3HjEGOMnkBuW5 zD5gstFkTWsa42wMr5/m1FsilGDrjLgroyE4N7p18yq+5uYwbiINcQ1gsKWd452NJW58 R+i8EATQUHIg5ur00+aKLZzWecIWWRQTBoVl3bao0eYWLzb1fZI5ZtRa/OZP7MnpCad9 MGzT6L8VJLmi+5Iz4d0YhFL2c8/uwOkSCoJBpTyLdSRzWBZMf6xvS0MTrIqFQGtUTQX1 2tUJhOtAq5fsQQgtpc80waqRoDMsB04DTONVBC4gwa/UNv1Gj355a/Fw/OmJ+dhPrwbj VNsg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1751019029; x=1751623829; 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=5atQvWZ5XtF65GtICFYcWzizaeglvYjKjJ357iLMqgU=; b=fHwtqgRqDtZlM2bGlfDS02PLpcr6WmygVjFn6g35XXdOcoUZ5Hlz+V0ZmykMpHc1TW j/3Tj2XAzlbuMihBOELPpJLNCrrtdEle7W3CaXewKisYTPF3gESXV4M3YL8ko2FNzamv XNUxvxovw+sb9XWvNb4NKUQT2cZC3MuzCpO0xckIAj+bfMrwhLWwuK2fVpmBudpkjJaw anWGDVlC7w/Fnd4cN4OJSXRxAFgPKavGM11XnsUcNAYfW33zWXCwoAPpac2PKD3/aHQu KTaFaRvh1mGsMEb2lydrVboGsucjTgPeTBpeA1J6jJ8K9kEZbayv8QQepsVyjL4D4FDv 6CWQ== X-Forwarded-Encrypted: i=1; AJvYcCWC+N3eVfC9iUjRda0yz5IEypiVmfowFSKwUa+6SuYFsNf6KHtWvsKYeK551bZyHJgmzK2suAP8bBftJRQ=@vger.kernel.org X-Gm-Message-State: AOJu0Yzou35h05mi5fGq6bVeK02QGQMEY/KjZXsYiq/RHqoy/eywtOKd odU8JDI2M9X9x6z510fTWIYpPQ2SbkoipVRHm8iu31ZfjbFv28j203JFRGeY0kdzAr8= X-Gm-Gg: ASbGncuq+CLGLmenkKN9+lcNSMJIVf9sOBqperK4UAQgVQ50EY4dbvMcH4c2eQAPMdt cGSJn/hjQBVv0Ni7VyeIyBKfqrUT/eXRp2O9nKzciDfiwaUyN6FcE3kAqXEcMedB1sffnPx3FFR 7MErPbEjbDQz9hrTRG7IwwV3FgUOuGMAtw5va/2JVfiCMqrpqhMe30210E0TuZ+XgkKZ9txL4g9 dnoGbBYJ7UGgLKPzPF74KGg5ETND85r+/tHxVSfyWTbj1Meek+0IxjFaJWOOmXzyxLDpxfe3NLp Z3X+WKPTi4kUX5nKJ4gimk4jttMDKbD0dxG8NMX7oDW5F4iTcX25MOgWPhwhTrNcHeQR2mK2RqS g2Ox7Vou6qaL9u/AZrxFxi/e4t38SxYOPhUeXtzMgDswvJT/ySnH4gcMdOwMz+j4= X-Google-Smtp-Source: AGHT+IGZE2klh6TBPD0rO9TA6JzZZw9l9tj4iEA/pqRFAVww2T2OERx45EFu4KjvgIYNex31bGtc7A== X-Received: by 2002:adf:b612:0:b0:3a4:dc42:a09e with SMTP id ffacd0b85a97d-3a8fe1dee45mr758781f8f.5.1751019029122; Fri, 27 Jun 2025 03:10:29 -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 5b1f17b1804b1-453823ad20bsm76001965e9.20.2025.06.27.03.10.28 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 27 Jun 2025 03:10:28 -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 Subject: [PATCH v2 4/8] docs: dma-api: add a kernel-doc comment for dma_pool_zalloc() Date: Fri, 27 Jun 2025 12:10:11 +0200 Message-ID: <20250627101015.1600042-5-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> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Document the dma_pool_zalloc() wrapper. Signed-off-by: Petr Tesarik Acked-by: Marek Szyprowski Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap --- Documentation/core-api/mm-api.rst | 2 ++ include/linux/dmapool.h | 8 ++++++++ 2 files changed, 10 insertions(+) diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-= api.rst index af8151db88b28..a61766328ac06 100644 --- a/Documentation/core-api/mm-api.rst +++ b/Documentation/core-api/mm-api.rst @@ -97,6 +97,8 @@ DMA pools .. kernel-doc:: mm/dmapool.c :export: =20 +.. kernel-doc:: include/linux/dmapool.h + More Memory Management Functions =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D =20 diff --git a/include/linux/dmapool.h b/include/linux/dmapool.h index 06c4de602b2f3..c0c7717d3ae7b 100644 --- a/include/linux/dmapool.h +++ b/include/linux/dmapool.h @@ -60,6 +60,14 @@ static inline struct dma_pool *dma_pool_create(const cha= r *name, NUMA_NO_NODE); } =20 +/** + * dma_pool_zalloc - Get a zero-initialized block of DMA coherent memory. + * @pool: dma pool that will produce the block + * @mem_flags: GFP_* bitmask + * @handle: pointer to dma address of block + * + * Same as @dma_pool_alloc, but the returned memory is zeroed. + */ static inline void *dma_pool_zalloc(struct dma_pool *pool, gfp_t mem_flags, dma_addr_t *handle) { --=20 2.49.0 From nobody Wed Oct 8 13:27:06 2025 Received: from mail-wr1-f44.google.com (mail-wr1-f44.google.com [209.85.221.44]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 80B362C08D5 for ; Fri, 27 Jun 2025 10:10:33 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.44 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751019035; cv=none; b=rF1QREr5C4U6HzzM7qGbq8eldlpU3CDrpmaBwrgYcRaeeRqFEyv6Jzp7t+HGV6NhMSOcfbD/9gK34ogyxccHKbUZ2b0ptXbr1nVQ2eNicYFeQUe402HsVA9AdWoDwXFk6/S5OuBDWQiBGpD8GFy0iycGb1UBV3y6n9fUtbJAbQg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751019035; c=relaxed/simple; bh=PIkDrcWZHnXgH0r6rcPc9bMgUEA8fdophSyVS2rNkAE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=BeLf7eh0vPRMOCF1E1GWFoX8RgxbEzNX+ZGmSlZ8I5MCqQ+Vq3NDFd+ZQ1SeGEiHo37nQTZY7MmZYcLwCeWhXPyTNh0BX8ksl3Etk9R/tERnj3rEr6kVe8w81J2cGJFvcRZO/HXf6TSW643YX49URxcJAL1Vn+X27XtNkK01YOk= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=suse.com; spf=pass smtp.mailfrom=suse.com; dkim=pass (2048-bit key) header.d=suse.com header.i=@suse.com header.b=N+djK7bp; arc=none smtp.client-ip=209.85.221.44 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=suse.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=suse.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=suse.com header.i=@suse.com header.b="N+djK7bp" Received: by mail-wr1-f44.google.com with SMTP id ffacd0b85a97d-3a4eb4dfd8eso282950f8f.2 for ; Fri, 27 Jun 2025 03:10:33 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=google; t=1751019032; x=1751623832; darn=vger.kernel.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=vkvls7hwXwv0ykrBS/xxPUz/PpMkCNXsAILifVa3mmw=; b=N+djK7bpqt7LB0R04o3JwAeodwItcrql/qwSyxmzM9p7BvZAPa4L3hLT4QpKAmKGb5 Hxq2qHgSNIHs858XWYFMUEuniLE3h7aYn4cCZaI4sNhLCCaRG7RSAMhMzwnFPPHai7uG jCOGCP6hq9ICjK5odhPlTYSEDmMKTsL6WAc3n8ALbDpztU9CHy0KiHOsdprv0mguwOtu WUChUcjLOv8juO3jBDv7oo3K3U/pHc+RQBArcVxumW/149AN7bpqJs08VsaMSdMW/noR hf1Zdiu9H2ICOR2YFJ8a/u6RsMKZmNvd2xUQdYjx7/TjEAdHn2ehoD2Sgt61jykFZEKL u4Fw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1751019032; x=1751623832; 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=vkvls7hwXwv0ykrBS/xxPUz/PpMkCNXsAILifVa3mmw=; b=pl7uwI0LVtQv4Px7YRZe1swRIYGlKwDMxmtlk92mpQ4m77KIStytXZI3gfdk2fKVDo yHqI3RsQrRA/eHVxOrHIYBcUKg8evN2mMEZl75ECS45zXP6d5XlKtxGOiLzFHuGs7w7C LfP8kRaW9Y0ae4wKmUrgD9V8h7uYL7A8267WK5oVTql6JrfLPFz4WrU+eAWr1SCwSEuI jOW4AWkK9mJ1Ck2xQF8xKMujLVYEH/oyLQRxg0qsjcUttJ/Ko6bT0hTK5DnobHsUbIP0 20a3mILQaRHx5S3dXfUZCcC4d7JQYlFNW6bdnoBbmSLG5UeGIBmuxktZuY3zPZ0Sc6cY Y+Aw== X-Forwarded-Encrypted: i=1; AJvYcCWduFHrDn/4i3wlWRkKOR06U73XMKLsWe0CGaHgQq7U/gLNIi6PwUBY8Q53lilHBT/ReOwwNFx5jNJYxFQ=@vger.kernel.org X-Gm-Message-State: AOJu0YwyhWafzz6AWFea74Q+XNnE8Aly0mOPifjz7byoMqL0/ynn83nE 03vlYPRiIl4PxsmOo749R8CfDA7ro7PXH3n8tHx0R5s4Da8iZe0AiY2Bcbn8QI3xxRc= X-Gm-Gg: ASbGncsp6hmEadmU4D9RHfD7JQveihU7oykc2rMY4UP/8KDW2HUxh2e+GCmeBnxg5wz SGo/dENa31pwwz+1UYBnO13Rka1d7k9gWe+U+2DtbpC1Tz+y1D+4Qv+qOxwr88+w9eLDZnFuaNd PlQF58mZdqAywpr/AMNJMk4Hbhbdf+hWEczhVFonfknVYb6hBdolKbRzA27YuN2i1tQe0znCdgA cdNzQXKZQpi97CI1wNypUZcyDP0D2MLmGr0lMvvpeYqYd3lSJV25XLFcsJXdVW4tvptnuD6jG7s W4r7PxQQ+yNTZe687fWWEWlZNAXRkGFimOXX/y4tKcH5rvzein+UGKcxcDoHzjDD4EXh8NakxHd 0eZ8oSbWqqqJ+IhfGdU3Skr19hIij/dMM5I/TEp8Ok6TNFLZj3vVs X-Google-Smtp-Source: AGHT+IFakGUatYasiyktGr52JfBGbmNZ0F1ECxHAdsFEffpOVWE3hvclPTvYOXXiDSO9IxEw8Dy1HA== X-Received: by 2002:a05:6000:23c9:b0:3a4:f912:86af with SMTP id ffacd0b85a97d-3a8fdc1f2b7mr604008f8f.2.1751019031793; Fri, 27 Jun 2025 03:10:31 -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 5b1f17b1804b1-4538a423abbsm46785495e9.39.2025.06.27.03.10.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 27 Jun 2025 03:10:31 -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 Subject: [PATCH v2 5/8] docs: dma-api: remove duplicate description of the DMA pool API Date: Fri, 27 Jun 2025 12:10:12 +0200 Message-ID: <20250627101015.1600042-6-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> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Move the DMA pool API documentation from Memory Management APIs to dma-api.rst, replacing the outdated duplicate description there. Signed-off-by: Petr Tesarik Acked-by: Marek Szyprowski Tested-by: Randy Dunlap --- Documentation/core-api/dma-api.rst | 62 ++---------------------------- Documentation/core-api/mm-api.rst | 8 ---- 2 files changed, 3 insertions(+), 67 deletions(-) diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dm= a-api.rst index 3e89e3b0ecfd2..bed6e8fdf56e2 100644 --- a/Documentation/core-api/dma-api.rst +++ b/Documentation/core-api/dma-api.rst @@ -83,66 +83,10 @@ much like a struct kmem_cache, except that they use the= DMA-coherent allocator, not __get_free_pages(). Also, they understand common hardware constraints for alignment, like queue heads needing to be aligned on N-byte boundaries. =20 +.. kernel-doc:: mm/dmapool.c + :export: =20 -:: - - struct dma_pool * - dma_pool_create(const char *name, struct device *dev, - size_t size, size_t align, size_t alloc); - -dma_pool_create() initializes a pool of DMA-coherent buffers -for use with a given device. It must be called in a context which -can sleep. - -The "name" is for diagnostics (like a struct kmem_cache name); dev and size -are like what you'd pass to dma_alloc_coherent(). The device's hardware -alignment requirement for this type of data is "align" (which is expressed -in bytes, and must be a power of two). If your device has no boundary -crossing restrictions, pass 0 for alloc; passing 4096 says memory allocated -from this pool must not cross 4KByte boundaries. - -:: - - void * - dma_pool_zalloc(struct dma_pool *pool, gfp_t mem_flags, - dma_addr_t *handle) - -Wraps dma_pool_alloc() and also zeroes the returned memory if the -allocation attempt succeeded. - - -:: - - void * - dma_pool_alloc(struct dma_pool *pool, gfp_t gfp_flags, - dma_addr_t *dma_handle); - -This allocates memory from the pool; the returned memory will meet the -size and alignment requirements specified at creation time. Pass -GFP_ATOMIC to prevent blocking, or if it's permitted (not -in_interrupt, not holding SMP locks), pass GFP_KERNEL to allow -blocking. Like dma_alloc_coherent(), this returns two values: an -address usable by the CPU, and the DMA address usable by the pool's -device. - -:: - - void - dma_pool_free(struct dma_pool *pool, void *vaddr, - dma_addr_t addr); - -This puts memory back into the pool. The pool is what was passed to -dma_pool_alloc(); the CPU (vaddr) and DMA addresses are what -were returned when that routine allocated the memory being freed. - -:: - - void - dma_pool_destroy(struct dma_pool *pool); - -dma_pool_destroy() frees the resources of the pool. It must be -called in a context which can sleep. Make sure you've freed all allocated -memory back to the pool before you destroy it. +.. kernel-doc:: include/linux/dmapool.h =20 =20 Part Ic - DMA addressing limitations diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-= api.rst index a61766328ac06..50cfc78429304 100644 --- a/Documentation/core-api/mm-api.rst +++ b/Documentation/core-api/mm-api.rst @@ -91,14 +91,6 @@ Memory pools .. kernel-doc:: mm/mempool.c :export: =20 -DMA pools -=3D=3D=3D=3D=3D=3D=3D=3D=3D - -.. kernel-doc:: mm/dmapool.c - :export: - -.. kernel-doc:: include/linux/dmapool.h - More Memory Management Functions =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D =20 --=20 2.49.0 From nobody Wed Oct 8 13:27:06 2025 Received: from mail-wr1-f51.google.com (mail-wr1-f51.google.com [209.85.221.51]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 6B0792C3274 for ; Fri, 27 Jun 2025 10:10:35 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.51 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751019037; cv=none; b=fskfpEFVKco0U2i1N8HUc/d6pWHxcHRyFui0MfOhxvN2fS6WVQqVu1emWrd58EUfEmQN9x1hmfGZo0KltYU8vTaiHeG/rv85msI0LrLLcbZ3ltltm6Gdx94sFVMDSmXGhqsHIWmhffcdslNmvWvqruGL1MeEJ8JZ23iB/evCsIE= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751019037; c=relaxed/simple; bh=zu4jprqPkVKK+s8SMuEoaDk/xS62TRzk/ACCvXy3VVM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=n0HgDc/Q1wsrWpkxSYAGX6l1aoHb7P/nmd6yoqQ0u/447sNe0P+nVYGIfQ4aSlWuP2ScK9nKwgG8jKG+/HZZQpfjQ92wKEN4VhOS3c+rVP4B5XMKb9SWyurYw7+EQAoAvovbvxaWMttI2eCmbz9Huxz6syXsCjKREcOPHIKk8+w= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=suse.com; spf=pass smtp.mailfrom=suse.com; dkim=pass (2048-bit key) header.d=suse.com header.i=@suse.com header.b=Y52AXAeW; arc=none smtp.client-ip=209.85.221.51 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=suse.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=suse.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=suse.com header.i=@suse.com header.b="Y52AXAeW" Received: by mail-wr1-f51.google.com with SMTP id ffacd0b85a97d-3a4e749d7b2so318546f8f.0 for ; Fri, 27 Jun 2025 03:10:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=google; t=1751019034; x=1751623834; darn=vger.kernel.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=+1GkDD0t9TV+8eyclzSuxcgZwyBe3Yxz+qGLtTo9oS4=; b=Y52AXAeW926JRvxZUrN4oMzCabGj4X8XaJAdJ5CB0eeOwWsCuNgQQb5lG16YISeBZZ 7wbcmfAPGixWJCVNo7w+dt+h1xtRQD6+EfGoV8sdLC+aJoPvuyCaKgzqubv8fai8xM7T LzLy0TevpNBvXjmS9K7CbvJVTRWnrRp8TOXLlRKnAnxau2cHKTBgIE6cmtlamB6+2nNc yvuKqGItvpODq5lJtxzCuCbLXRwKkHspAFUt840cS+pwDX+v/5tshyaMK9z+7vjaqPxi Qa23axnLnH+YyfBFWT0iB/urEZwv90g9GgqWY3rsj90QaAgKwnpwbGkAEhC0M1u0lJ+1 wWyA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1751019034; x=1751623834; 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=+1GkDD0t9TV+8eyclzSuxcgZwyBe3Yxz+qGLtTo9oS4=; b=A3ZvTITPLFvdfxGduGeWX3PSlSdEYV9sT7QxcE9Ffc6hiitjFi5AIuROLVO/EJU7fb BzScNWuqfemYctdjI+c7ay3nlSmbXZenEyfBpdrbWkNJPLXE/Upw3roBsg9GRnF4e994 2Qeek4Ia6wUZolFUIcTtXMNK8aXLh+V3u/McJ8QG90RQe9b5XZpc5eUuvMLUHGmVXPbH Jo2zwNE2gVrdONYKAQU0jq7deOE61RzTF5Qb4y0T1pNo9j0tzjmmV42JHb0/oSRWnvAn gh0+kpBUNPrGetxgK/OIC8pk0H9rpC/36kXQ2HAs9rC4Y3bPC+Q+dsV6B2GEUws0KstE Pcyw== X-Forwarded-Encrypted: i=1; AJvYcCWKPrdOAywbv2VquNUR+dmHGYjLHM8I88+QJP5jKnocIqSktvzcP91d5Hexn/oYz3AyK1bsP4gGoyGvQLM=@vger.kernel.org X-Gm-Message-State: AOJu0YyiYhIXhgIQUi4v+aFVpC7a15bMWBdxoD1jTAQG8AdR2N6tvyct EvIXJI2FhVghSivvKUzgTDZCLHWn1pDgWz9diTyqjO1CR+aSWTnfeMGWijbqrz4qBJk= X-Gm-Gg: ASbGncsR/MbKlPJP06yCihooNztP6FsjO4cWL3wsSuNliFf24macx4ctbjut2Ol10r3 U0O4Q/oh2jp13QSTHMFxe2ZRLiLtXIgxoHrxmWmmRpxW5pmvS4JMXcWzZycQAi2BTRk1Yv0K9Ww e4tsW3ln6N5kHJHY2g5t6+edEwg+ZVJhgysAVgXLY3k8aT8CqI+h8JvgT1TLY6CnhxMMawfe7Ma /oRqepbaWd9FWcVRjBt0EPUXlVKZdP/xP+r0TN9Fm65nbLjwOKMqelzXlaeqHaVic2j1wHTizTz uIPpiZes5NOcnd+PB1RmEQyRMncA2nkg3S/f8Aeindq1xboQtLk4hi6pRFPt8KpqfXr+wQheRoR s/J59SmycXn+n4EWSxvKO/3w9Z0GqI3q81t3P0Hbp98YvNZLUZNEF X-Google-Smtp-Source: AGHT+IFN+4rxHLnEkyIUsrPqGi0U/kgqahdfchbV1MPl60s4rMY1PSGd5MD4vpgOV5VdL516KcG0DQ== X-Received: by 2002:a5d:64e3:0:b0:3a5:781c:6956 with SMTP id ffacd0b85a97d-3a90c5516a3mr1085911f8f.6.1751019033571; Fri, 27 Jun 2025 03:10:33 -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-3a892e5f34csm2232521f8f.85.2025.06.27.03.10.33 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 27 Jun 2025 03:10:33 -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 Subject: [PATCH v2 6/8] docs: dma-api: clarify DMA addressing limitations Date: Fri, 27 Jun 2025 12:10:13 +0200 Message-ID: <20250627101015.1600042-7-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> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Move the description of DMA mask from the documentation of dma_map_single() to Part Ic - DMA addressing limitations and improve the wording. Explain when a mask setting function may fail, and do not repeat this explanation for each individual function. Clarify which device parameters are updated by each mask setting function. Signed-off-by: Petr Tesarik Reviewed-by: Bagas Sanjaya Acked-by: Marek Szyprowski Tested-by: Randy Dunlap --- Documentation/core-api/dma-api.rst | 35 +++++++++++++++--------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dm= a-api.rst index bed6e8fdf56e2..9fcdb160638e0 100644 --- a/Documentation/core-api/dma-api.rst +++ b/Documentation/core-api/dma-api.rst @@ -92,13 +92,20 @@ for alignment, like queue heads needing to be aligned o= n N-byte boundaries. Part Ic - DMA addressing limitations ------------------------------------ =20 +DMA mask is a bit mask of the addressable region for the device. In other = words, +if applying the DMA mask (a bitwise AND operation) to the DMA address of a +memory region does not clear any bits in the address, then the device can +perform DMA to that memory region. + +All the below functions which set a DMA mask may fail if the requested mask +cannot be used with the device, or if the device is not capable of doing D= MA. + :: =20 int dma_set_mask_and_coherent(struct device *dev, u64 mask) =20 -Checks to see if the mask is possible and updates the device -streaming and coherent DMA mask parameters if it is. +Updates both streaming and coherent DMA masks. =20 Returns: 0 if successful and a negative error if not. =20 @@ -107,8 +114,7 @@ Returns: 0 if successful and a negative error if not. int dma_set_mask(struct device *dev, u64 mask) =20 -Checks to see if the mask is possible and updates the device -parameters if it is. +Updates only the streaming DMA mask. =20 Returns: 0 if successful and a negative error if not. =20 @@ -117,8 +123,7 @@ Returns: 0 if successful and a negative error if not. int dma_set_coherent_mask(struct device *dev, u64 mask) =20 -Checks to see if the mask is possible and updates the device -parameters if it is. +Updates only the coherent DMA mask. =20 Returns: 0 if successful and a negative error if not. =20 @@ -173,7 +178,7 @@ transfer memory ownership. Returns %false if those cal= ls can be skipped. unsigned long dma_get_merge_boundary(struct device *dev); =20 -Returns the DMA merge boundary. If the device cannot merge any the DMA add= ress +Returns the DMA merge boundary. If the device cannot merge any DMA address segments, the function returns 0. =20 Part Id - Streaming DMA mappings @@ -207,16 +212,12 @@ DMA_BIDIRECTIONAL direction isn't known this API should be obtained from sources which guarantee it to be physically contiguous (like kmalloc). =20 - Further, the DMA address of the memory must be within the - dma_mask of the device (the dma_mask is a bit mask of the - addressable region for the device, i.e., if the DMA address of - the memory ANDed with the dma_mask is still equal to the DMA - address, then the device can perform DMA to the memory). 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). + 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). =20 Note also that the above constraints on physical contiguity and dma_mask may not apply if the platform has an IOMMU (a device which --=20 2.49.0 From nobody Wed Oct 8 13:27:06 2025 Received: from mail-wr1-f46.google.com (mail-wr1-f46.google.com [209.85.221.46]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 55A072C324E for ; Fri, 27 Jun 2025 10:10:38 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.46 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751019040; cv=none; b=fO6I/76q5N/547AYA5MQe0BQ7Q4Q+kGKpIB2FMVM6HYWbe2a8+CJK3+0pneOjJ7mpxrv0EQCZqvMRdkMi75BhiFxYO/stsMbjAhqW5kElCmn8OPDvo9WGk9urTGxk9o52a1ijQ9gBAzx1ngRwLLWlFjF9YjCiYY/129cXjbLEfk= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751019040; c=relaxed/simple; bh=3+ynpMQcTjsyaLFunYDi9YC+WhFUge4SSY1Ra3bgnMs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=IYsfg2+P25VcOwaR8u+jimtAgQFIPa1N6CnREHNAB5WwC+JXEh+NpRWnVWJhldyAt3+PqFyg1aN98A1tHQIyLcLxDcazLMFYhlW3fhg0C0gN3qWqHpjpSx5jDHOX7GZihCPITvWejdVCr7H6R9vstaLz7soQnoFpFX4Ahz5r20k= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=suse.com; spf=pass smtp.mailfrom=suse.com; dkim=pass (2048-bit key) header.d=suse.com header.i=@suse.com header.b=EVzt5GoG; arc=none smtp.client-ip=209.85.221.46 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=suse.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=suse.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=suse.com header.i=@suse.com header.b="EVzt5GoG" Received: by mail-wr1-f46.google.com with SMTP id ffacd0b85a97d-3a4f64cdc2dso304348f8f.1 for ; Fri, 27 Jun 2025 03:10:38 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=google; t=1751019037; x=1751623837; darn=vger.kernel.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=EVzt5GoGtp0EtE8oNXa5V2RADS61+7/7l8TNxCCpEPdDo4xuV7S0cegYEn6Xz8wlgF GyhVzrTIkhkIvrf8ZHs+2WbQvFYcQ0rkfcXNc6VddN+j5vWFV6wJ5y0wcRBU0XSQY7gf hFarfWd0q87GAh8hjqSv4vPKi/Fq7a2EnH0Fjmg0bxNWokbYzxIbbtlzO/AsP7lD93KV +h9MUpsEUxN4XDhKyuyLQurZQH5tfu3yEs1M0BLpXphkqY0RfyN6LGF0n0h+YijpPjK9 MMkwdsoG0s8WV9MYk5Hz4OsI3Or3YoRsEYiTP3ZQFxebB+47/2njFeFASpkFyx00lMh7 zKmw== 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=A9MBY4ZQcQSFeZJmMtfPLjn4mgzGSBiTY3LY1RbqMjxingrgsmqi9xKDSonMVHgNIj WlojSSOJBsfaXHDXfCnsmH7u+sM5Ne0nGnAyRuRzRYSvlP14yhaUbAhYfyo9gSOA0pBU pPM5UTi7AmCfy22h/MrAIRpNtjfSJXrtukPZBEhxTwGowSgLODU3NEBJVd+wCHceJOBj H+rrIbAYrbkMrsaQJqKY8sl9sy5+btAiE26yyBz0YEPT7hpBqJ0owyjfhlY7ZJnxp9dF a1moYm/NqwUJ54Y8kt9DUKij8E4wwzg/N+WxNDR/uQ00AfsDUMRj/pnqYDF15WHdq4SJ n02g== X-Forwarded-Encrypted: i=1; AJvYcCUQVjflSro6UBxeyn7UjVUU/JhJT8vCUrFjNobwg8XNoOoCJN/KWOPgMacPvLkr73n2w6WYnzEo4z0baPo=@vger.kernel.org X-Gm-Message-State: AOJu0Yw3plEvSVyeC+IVKuxDrYvM+jg+Jw/E6+VG1XeAgC7fSMSbo99i XrJ8EiHYl6xjrCXLjzVHT025FaaA6z9cqJYiowqCIDBx9z90kBgwmm/81PXFKohFj1k= X-Gm-Gg: ASbGncurkfByitqdiC8KqvEsR3LH32jNOe/UhQA2VQt/TngDxwrMJXgKo0hQd/hxB+M l70SL6KUuk2Y0vX0iK2LK7Kh2v/PEwt4IDsKVSZTW6pkz6WAxg8l8qAqBtXvUeRLPbbPW8mNtbM 99WCUN+we6F2rW3nIU/g2itw2bOaoYCoE/TidV6KDT1yuX9wNdvAkQerlk34j0nqFm29J+cojqa 4v1+kwSnI4ACVNjExxgqVeoC7pAKbhq1XvCAtEM1cJTSLIxxfV3m+XfYAYL8JXwHCNltDT7wCwP I27eBuHtyC1CGu9Oi5IXPumj45+TlxkfoMbbEF2dFF8oRAFhvdSsXBv/ijc84roUKdG4tDYVcEr AxQVFRCTswsdRVKpgbdNl//j0qzsuvxc08eBBK2aBV78dgXN2AcsT2WdsgH9EDlQ= 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> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" 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 Acked-by: Marek Szyprowski Reviewed-by: Bagas Sanjaya Tested-by: Randy Dunlap --- 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/dm= a-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 -------------------------------- =20 +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 t= he +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. + :: =20 dma_addr_t @@ -204,27 +224,13 @@ DMA_BIDIRECTIONAL direction isn't known =20 .. note:: =20 - 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). =20 - 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:: =20 Memory coherency operates at a granularity called the cache --=20 2.49.0 From nobody Wed Oct 8 13:27:06 2025 Received: from mail-wm1-f51.google.com (mail-wm1-f51.google.com [209.85.128.51]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id AECA42D3EDA for ; Fri, 27 Jun 2025 10:10:40 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.51 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751019042; cv=none; b=u8N2G0YHSH5PRVDUB0XKRvCGUj+ERuyY6shuEBxAu+LstSIj9ZbmeZC9ExpuPl2UVHB0jGAMZ4sZvOwsCGAAFFaGX6QOAWwDYQc69GZEclOq9/9nwCaGn5iQ3gQtx9bpM3UaZIOQrem7MbTQLYF3Rl6jln+2mbLDixUC2ebMUUo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1751019042; c=relaxed/simple; bh=PY7MCM4FXuwFMl63xmFYQRu/KWGisjazEhN6tbWGbm4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=tyVaG5KruINwL6qCgFYVD5KdPU+SAwvTZm4Lka4xx/EBz1tJxDzbtRB/NK7F8uFsltuGsZvGVqQN4G8aBwV348Si2qwY3BnydrkId34GC4742BE8zlfe4vCc92HUp9CNTJwHPqF3FnsjFTtpaGzXVtBO7g8cxGgJMQAVapNwe+I= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=suse.com; spf=pass smtp.mailfrom=suse.com; dkim=pass (2048-bit key) header.d=suse.com header.i=@suse.com header.b=GTkBwrvX; arc=none smtp.client-ip=209.85.128.51 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=quarantine dis=none) header.from=suse.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=suse.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=suse.com header.i=@suse.com header.b="GTkBwrvX" Received: by mail-wm1-f51.google.com with SMTP id 5b1f17b1804b1-450ddb35583so2877955e9.1 for ; Fri, 27 Jun 2025 03:10:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=google; t=1751019039; x=1751623839; darn=vger.kernel.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=Q4D/AiHSkh+69Es8gMfweA+RJzsnoZRpe3Ttw4Zd1mI=; b=GTkBwrvXOARO/FKqqBUgWxCtGjIIoFE2vfqAt+pmKhYlk6e0plTyzEqonnPv+yljVC lyuTNQhXS/idjKrgB/NqTJ1fEOsDoEicThZdoHtSjDjPTlWX6jzao7iXChqdk2w0R6NE n74qxZvqLxB1r4f7U0gx0IN8xKsn/g95Jjx5aX6WUyWsVK7P1wJr4x/HjvRfxMjqaqQb We7frVBa213i30v7ArbhI7vC+kjOiSePD2Hg6UipPV8IWA3rvUQShtrWVTMyl/1Aya0j n076V/mHVAMnS64LXaG8FvRmzGJGcuyf+LumuZq6skjBhmd0zFKEqZhDi5tBRUjggNrw L1RQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1751019039; x=1751623839; 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=Q4D/AiHSkh+69Es8gMfweA+RJzsnoZRpe3Ttw4Zd1mI=; b=ep4pOzlT8LFh5CigLDCavEt6KZkcpOCvK3pR7mx7hgajbUL5vrUhx+Rdw5Xy+oVpKL drTpXoOHfm20dhWAZus/E7dc2LrpMTKS68be4yDWA0+SHW0BgPkj/OZnyMQ5GTYLr84I OlCSQeu1XHpNfwfIhFHa4r+MDFeMJSkL8GGbekaAIYFaThp9PEe2AI4g4gBfY9fn6ciy qqiP95szfyi8myHzA0VyTQkYg1d5nlv2izbMQeWX7Zw9WovTKqWwMZ1S0HsfpvAQ+ep6 jsnaQADawqVEdehpyt4V5ZiibcUuvlPOdHkZeiW7AmdFRSeHyJAlTKACUf4PJY7HXr2B +1qA== X-Forwarded-Encrypted: i=1; AJvYcCVxd9b/kzRUGCi0mGD6u4t6SmFneavsJ1iNJLcA+xRteM8EOhRRjqJmEoLWGxv2Gfx53qP1XeK7Oy7YWCA=@vger.kernel.org X-Gm-Message-State: AOJu0Yyi3TeRmMN//698UnXCzp4igC/TcKbnXY+Z5rynjbQxRY8+NqQc Ar3WtKaK53qIUQ0lRiXRDa/fW3TQmZ6nfVrU0riWpgG8mRcoeNbPfwskIGf3t2QzyHs= X-Gm-Gg: ASbGncuylF2njBprtZi8yyZ8ur2ryP7EUcFYTHz+ySiKWqJbFUFUWBDtwS/euJVgpyr Q2GUoCcsj6NiEnR18l08FU73hFPkTBG427dQ33qzT5/IcJkIHGAILlJTip/MJt5MGA8yIbAH+/b P/uyYvGX9OP79DR15EcIcS0A4fDmrNwJd9+OBoOPoE+Kjh/igyyeG2B8PiAPWz7KhHlTfoKu/ZU WBY5PpYepDESIk6b01q6dERUzkdJ5Z4HsvzQAotWkITIdfjbPDrN4IMlrDggUQ3OKRdrhdwSltF fxlhJGZ+zCLlBAZY6oVAa/IJLIvL2/IN1Suz6ELdPeVXkNWV2HNy//6vgXSaXQ7K3+dQ3/BFIZ6 +hZq0rnwALyr2taPSdxb7u78znkHzLbf2ferNloYIzE7FxFG9Af99 X-Google-Smtp-Source: AGHT+IFhGjN5+1VG4TKQb30R0Dc6Kgtf1mHBD0dtlQDL49I+8wxvgFwjsJemxuxfEbYHyeyL9tfPrA== X-Received: by 2002:a05:600c:a08b:b0:450:d5ed:3c20 with SMTP id 5b1f17b1804b1-4538ee7446fmr10977035e9.6.1751019038988; Fri, 27 Jun 2025 03:10:38 -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 5b1f17b1804b1-4538327fed8sm37178605e9.1.2025.06.27.03.10.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 27 Jun 2025 03:10:38 -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 Subject: [PATCH v2 8/8] docs: dma-api: clean up documentation of dma_map_sg() Date: Fri, 27 Jun 2025 12:10:15 +0200 Message-ID: <20250627101015.1600042-9-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> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Describe in one sentence what the function does. Do not repeat example situations when the returned number is lower than the number of segments on input. Signed-off-by: Petr Tesarik Reviewed-by: Bagas Sanjaya Acked-by: Marek Szyprowski Tested-by: Randy Dunlap --- Documentation/core-api/dma-api.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dm= a-api.rst index a075550ebbb54..6a57618118fd4 100644 --- a/Documentation/core-api/dma-api.rst +++ b/Documentation/core-api/dma-api.rst @@ -322,10 +322,10 @@ action (e.g. reduce current DMA mapping usage or dela= y and try again later). dma_map_sg(struct device *dev, struct scatterlist *sg, int nents, enum dma_data_direction direction) =20 -Returns: the number of DMA address segments mapped (this may be shorter -than passed in if some elements of the scatter/gather list are -physically or virtually adjacent and an IOMMU maps them with a single -entry). +Maps a scatter/gather list for DMA. Returns the number of DMA address segm= ents +mapped, which may be smaller than passed in if several consecutive +sglist entries are merged (e.g. with an IOMMU, or if some adjacent segments +just happen to be physically contiguous). =20 Please note that the sg cannot be mapped again if it has been mapped once. The mapping process is allowed to destroy information in the sg. @@ -349,9 +349,8 @@ With scatterlists, you use the resulting mapping like t= his:: where nents is the number of entries in the sglist. =20 The implementation is free to merge several consecutive sglist entries -into one (e.g. with an IOMMU, or if several pages just happen to be -physically contiguous) and returns the actual number of sg entries it -mapped them to. On failure 0, is returned. +into one. The returned number is the actual number of sg entries it +mapped them to. On failure, 0 is returned. =20 Then you should loop count times (note: this can be less than nents times) and use sg_dma_address() and sg_dma_len() macros where you previously --=20 2.49.0