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 07A06C7115B for ; Thu, 26 Jun 2025 04:51:32 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 93EE86B00BC; Thu, 26 Jun 2025 00:51:32 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 916646B00C1; Thu, 26 Jun 2025 00:51:32 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 82BE16B00C4; Thu, 26 Jun 2025 00:51:32 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0017.hostedemail.com [216.40.44.17]) by kanga.kvack.org (Postfix) with ESMTP id 743236B00BC for ; Thu, 26 Jun 2025 00:51:32 -0400 (EDT) Received: from smtpin22.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay06.hostedemail.com (Postfix) with ESMTP id 68DBC104A91 for ; Thu, 26 Jun 2025 04:51:31 +0000 (UTC) X-FDA: 83596328382.22.D4D4CAC Received: from mail-ed1-f44.google.com (mail-ed1-f44.google.com [209.85.208.44]) by imf30.hostedemail.com (Postfix) with ESMTP id 5FDA98000F for ; Thu, 26 Jun 2025 04:51:29 +0000 (UTC) Authentication-Results: imf30.hostedemail.com; dkim=pass header.d=suse.com header.s=google header.b=U6gWX3Yq; dmarc=pass (policy=quarantine) header.from=suse.com; spf=pass (imf30.hostedemail.com: domain of ptesarik@suse.com designates 209.85.208.44 as permitted sender) smtp.mailfrom=ptesarik@suse.com ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1750913489; a=rsa-sha256; cv=none; b=2898eWOMWyhZos6Def1Xc5/m8HrzYRcNIi6dM6R8FNVcXPsquy4VQKSt2ZVUmviJakKBhr OWd9tFX5FaVbNJkYAn3DzKZTvo1IXWJTsg0tWXiPuHl2ABeiBlL2a5RwG6qxdgfSCtQp9e e2rkye8kC77olpZBSNTn0RRekb9gSfs= ARC-Authentication-Results: i=1; imf30.hostedemail.com; dkim=pass header.d=suse.com header.s=google header.b=U6gWX3Yq; dmarc=pass (policy=quarantine) header.from=suse.com; spf=pass (imf30.hostedemail.com: domain of ptesarik@suse.com designates 209.85.208.44 as permitted sender) smtp.mailfrom=ptesarik@suse.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1750913489; 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=fWC7HBqSFUGlEPGH7aS8ihpBdyH7ak4aV8RQ6csJ+OY=; b=7Uzt9NpqZJ/GZVBK8AzhXQD1UxucSQN4JZtUUoG2IJZFPpD6apCw9/W/1z5b71WpbjcojE G4N0hiriqgVVkC3sL8NeCPjJrwaM/VB6EQJdQsiX6z75tQWaSlryknchE8qT6zwLMy2i0+ xrBL7sxtYPXRMuBPxwANMLKavHe/mPs= Received: by mail-ed1-f44.google.com with SMTP id 4fb4d7f45d1cf-608964359f9so126843a12.1 for ; Wed, 25 Jun 2025 21:51:29 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=suse.com; s=google; t=1750913488; x=1751518288; darn=kvack.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:subject:cc:to:from:date:from:to:cc:subject:date :message-id:reply-to; bh=fWC7HBqSFUGlEPGH7aS8ihpBdyH7ak4aV8RQ6csJ+OY=; b=U6gWX3Yq2sCDCco456ni/XoW2Smhlf4Ms4QyFBeVybnt015FSPMgKUAQ7HCIsADaFx DY08irwXqo8biLuFInapDkN/q1ghNJoX5x+lyqNb2Pkl1pKctfC85HqhL11PiDSBZPCV fg0Kbxv11EX0In+kvm6fFQ+azJ8vtNRR9fMA2bzI9zCApojSvOHj3klzFzvoDkUEYfR1 QfiSEPkfzj2IQDPQVEZlt6HrH9lkvCVXUbAMNCtFFl1yKoCu66arOXNDHBnBMfKov53n NM571TXkra9h+/mrtU74lR5EGithPlyjlT7aJ7mu/aOJSdNkZAs8Czb2m+LxJsclOmiM AmqQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1750913488; x=1751518288; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:subject:cc:to:from:date:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=fWC7HBqSFUGlEPGH7aS8ihpBdyH7ak4aV8RQ6csJ+OY=; b=Rz4E/2R87unYr/cx44ccbl3ejB0SKBHNL9GhfWxrIn+KJ0BINJhOOqYdH94zJs6fxw GhAMYHnhYVwUw9kXucl9Rso7kDL13U4FtQcZ23D/lBkwEQBVy6D7r2NXIJjWP+zzNavc bkQr71FFLF4mgx+S1TPmiPA3msvwQY500DKxr9w+OYZkyQywpp16nXE8VRkBl3HiHhMt YnxopzNXx5gP86hXpALqLYA5q7FS7esPMxUU6CKRelcybgpdJzFbITW8wL1wMX060YFU 23bLKsQcJFt+vTgIut957VnQtIVfKKLZ+gBHbRaat/AIVUVII8d8QG1KC7k8oMHiQO5a VoiA== X-Forwarded-Encrypted: i=1; AJvYcCUK3Db8mfDHdz1rvfkpa1YLqrJpkeneEYkT6wlOf8m+MlJ+hBqIeW1V5qS9QoNsbD8zdFk6tO07fw==@kvack.org X-Gm-Message-State: AOJu0Yw4EO2zrjIVn999rmk1btL1j8Y4YRESYtAlQK/uqd3tjO+mjA/l 15prxc95dzeKNeo6+04ISU6qLY7PSvVtDOpk5HDHqfAADpzEtOzgGw+0jCzxcfMyZsQ= X-Gm-Gg: ASbGncuSELJFdws9RugMFv7ECltv59x8r9OK57cxbJOm8PZiYGqfLNrlGkPzAHg8AB/ hV+ha2QQAbq49LbR14V8FG6uZR9XxTARBGzKjDRySZt83fWU8vjHCMCkSGy0hgDmlwCJj1SZY0r WGOFAA4vljVjjfmJjsEruvEPf/IwBSbiwyEwNzXjGF2C//W5yuyJdOC+2c29slwWWO+3vZbVg7U r5eF+NNxKlFr93VrWfpgvTfGHLRY5B/6qhErV+HudQgL5YIU+AvHWo6FePgyViiV9r87McHODGQ k8y7eCDnnmSDDh+Vx2QEJ7f0L0aTRz9enF/Dr2yhD+rfLg== X-Google-Smtp-Source: AGHT+IEZlq6eUrM1lQ3SGemnqkMSipc938+0VRxHvwMg1lalNKduhac6t/8hXwjkIGMnsXPZ7dnJlw== X-Received: by 2002:a17:907:9691:b0:ae0:d83c:bcc3 with SMTP id a640c23a62f3a-ae0d83cc2f6mr28824866b.7.1750913487561; Wed, 25 Jun 2025 21:51:27 -0700 (PDT) Received: from mordecai.tesarici.cz ([213.235.133.108]) by smtp.gmail.com with ESMTPSA id a640c23a62f3a-ae054080e8esm1149691466b.82.2025.06.25.21.51.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 25 Jun 2025 21:51:27 -0700 (PDT) Date: Thu, 26 Jun 2025 06:51:23 +0200 From: Petr Tesarik To: Marek Szyprowski , Robin@kvack.org, "Murphy Cc: Jonathan Corbet , Andrew Morton , Leon Romanovsky , Keith Busch , Caleb Sander Mateos , Sagi Grimberg , Jens Axboe , John Garry , linux-doc@vger.kernel.org (open list:DOCUMENTATION), linux-kernel@vger.kernel.org (open list), linux-mm@kvack.org (open list:MEMORY MANAGEMENT), iommu@lists.linux.dev Subject: Re: [PATCH 2/8] docs: dma-api: replace consistent with coherent Message-ID: <20250626065123.646bd954@mordecai.tesarici.cz> In-Reply-To: <20250624133923.1140421-3-ptesarik@suse.com> References: <20250624133923.1140421-1-ptesarik@suse.com> <20250624133923.1140421-3-ptesarik@suse.com> X-Mailer: Claws Mail 4.3.1 (GTK 3.24.50; x86_64-suse-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-Rspam-User: X-Rspamd-Queue-Id: 5FDA98000F X-Rspamd-Server: rspam10 X-Stat-Signature: 6qyqx4mfsnbx3o63i7xchoaumo17ecob X-HE-Tag: 1750913489-374569 X-HE-Meta: U2FsdGVkX19p1C5NefIzlYfOre4pnb9TZ31fp7d0izL/HpaOLFFBMt3zJWPp/9ucWVJjh0Eyn12uCQ0UzB6xQYeKdLeb9a5E9SIqnCpH1Su5+LKzwA/n3SkesITPl8Fd7+pjJqMxiNWfAYqqMJB9mTfBI9Akrsb3P+pwXMVyfccbBolyPduusrdiIXWL0dAAzSAaCp2EjhUNtmWchkjpOpm0GUnLEbZU4/hEZ3wgWsGLIIEfHVkCefbb9NQe0wzVjBpfxvfudwr0Jv7+3cHOHgLakoOixTaSwL5fPqtXXH0YxBfYHWZ25g+I5BSQWufLd50N1Zk6gkY2tLHGRW7SCfMsrvIyfyI9M/08j0f3rn009TC7ZeIf+tyIjiIbpkKEqQCeen0QVq7tyxxazmwgJJtz6PC8iEjAzOo4u7Y1dNbz6q4fsZm/gKI298vzYIDdN6/Yw1ReOZRep0JPiaxKbX2R6YsoT9kA9ibMcVtvsV/D9z+sFByI7PQ9aRAqRREZsDU4umBdi1MgLBW0CW/SuKLqMMXX6cUh9PiD1KFWl/h3KrgVOWgsmMKxeAax5ntH0hXkYzVF9yUqJh/B2OzTjO++EZGC3OIVahz7vMy9ysVcdW3zCNH7CdasVUf9aViP8eeB39hwuE9MzDEmAEFbZnzddnCgYGjgjFzBBoNTtwbEGzNjpYZlX6b/bNetXZpkGKSPWRJMywqqGY4/tW+J732gGLR11MYlXUrbX6i0GzMCVMq4ZLD7Dj98OoTm2i+BPCs3GdeVjAaI5K9+oRbO/DKCCtNxeliLaeFjgRrzdq+NQWyhNyIPGnkuyBt1HcN2RT5QlZBnd8L8ARRYSxpbflrFXq2ODt2xWXhiUsU0esqJ2HCTlQZDOw== 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 Tue, 24 Jun 2025 15:39:17 +0200 Petr Tesarik wrote: > 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_alloc_consistent() function. I realize that I'm not an authoritative source for this, but I forgot to add more trusted maintainers to the recipient list. Now, all you DMA experts, do you agree that the word "consistent" should be finally eradicated from DMA API documentation? Petr T > Signed-off-by: Petr Tesarik > --- > 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 0bf31b6c4383..96fce2a9aa90 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. > > Special note about PCI: PCI-X specification requires PCI-X devices to support > 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. > > For correct operation, you must set the DMA mask to inform the kernel about > @@ -174,7 +174,7 @@ used instead: > > int dma_set_mask(struct device *dev, u64 mask); > > - 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():: > > int dma_set_coherent_mask(struct device *dev, u64 mask); > @@ -241,7 +241,7 @@ it would look like this:: > > 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(). > > Finally, if your device can only drive the low 24-bits of > @@ -298,20 +298,20 @@ Types of DMA mappings > > There are two types of DMA mappings: > > -- 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. > > - Think of "consistent" as "synchronous" or "coherent". > + Think of "coherent" as "synchronous". > > - 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. > > - Good examples of what to use consistent mappings for are: > + Good examples of what to use coherent mappings for are: > > - Network card DMA ring descriptors. > - SCSI adapter mailbox command data structures. > @@ -320,13 +320,13 @@ There are two types of DMA mappings: > > 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. > > .. important:: > > - 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 will work better > when the underlying buffers don't share cache lines with other data. > > > -Using Consistent DMA mappings > -============================= > +Using Coherent DMA mappings > +=========================== > > -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:: > > 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. > > -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 mask) > -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. > > @@ -497,7 +497,7 @@ program address space. Such platforms can and do report errors in the > kernel logs when the DMA controller hardware detects violation of the > permission setting. > > -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. > > diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst > index 97f42c15f5e4..c0a2cc7d0b95 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 introduction > of the API (and actual examples), see Documentation/core-api/dma-api-howto.rst. > > 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. > > 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) > > -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.) > > -This routine allocates a region of bytes of consistent memory. > +This routine allocates a region of bytes of coherent memory. > > 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 unsigned integer the > same width as the bus and given to the device as the DMA address base of > the region. > > -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). > > 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) > > -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 5be8cc1c6529..5d8af6e29127 100644 > --- a/mm/dmapool.c > +++ b/mm/dmapool.c > @@ -200,7 +200,7 @@ static void pool_block_push(struct dma_pool *pool, struct dma_block *block, > > > /** > - * 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, struct 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); > > /** > - * 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