linux-kernel - [PATCH] Documentation/DMA-API.txt: Change "consistent" into "coherent"

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [day] [month] [year] [list]
Message-Id: <1431348062-31469-1-git-send-email-mike.looijmans@topic.nl>
Date:	Mon, 11 May 2015 14:41:02 +0200
From:	Mike Looijmans <mike.looijmans@...ic.nl>
To:	corbet@....net, linux-doc@...r.kernel.org
Cc:	linux-kernel@...r.kernel.org, rmk+kernel@....linux.org.uk,
	arnd@...db.de, Mike Looijmans <mike.looijmans@...ic.nl>
Subject: [PATCH] Documentation/DMA-API.txt: Change "consistent" into "coherent"

The DMA API document describes methods that all have "coherent" in
their names, but does so using the term "consistent".

Consistent memory is a more strict requirement than coherent memory,
and for a method called "dma_alloc_coherent()" to return consistent
memory is just confusing. Replace the word "consistent" in the
descriptions into "coherent" to be clear about this. Most hardware
will offer "coherent" memory, so the logical choice here is to adapt
the description to match reality.

Signed-off-by: Mike Looijmans <mike.looijmans@...ic.nl>
---
 Documentation/DMA-API.txt | 27 +++++++++++++--------------
 1 file changed, 13 insertions(+), 14 deletions(-)

diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt
index 5208840..32c38d6 100644
--- a/Documentation/DMA-API.txt
+++ b/Documentation/DMA-API.txt
@@ -7,9 +7,9 @@ This document describes the DMA API.  For a more gentle introduction
 of the API (and actual examples), see Documentation/DMA-API-HOWTO.txt.
 
 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
@@ -36,7 +36,7 @@ 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 <size> bytes of consistent memory.
+This routine allocates a region of <size> 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.
@@ -45,9 +45,9 @@ It also returns a <dma_handle> which may be cast to an unsigned integer the
 same width as the bus and given to the device as the bus 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
@@ -66,7 +66,7 @@ void
 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().
@@ -454,26 +454,25 @@ dma_alloc_noncoherent(struct device *dev, size_t size,
 			       dma_addr_t *dma_handle, gfp_t flag)
 
 Identical to dma_alloc_coherent() except that the platform will
-choose to return either consistent or non-consistent memory as it sees
+choose to return either coherent or non-coherent memory as it sees
 fit.  By using this API, you are guaranteeing to the platform that you
 have all the correct and necessary sync points for this memory in the
-driver should it choose to return non-consistent memory.
+driver should it choose to return non-coherent memory.
 
-Note: where the platform can return consistent memory, it will
+Note: where the platform can return coherent memory, it will
 guarantee that the sync points become nops.
 
-Warning:  Handling non-consistent memory is a real pain.  You should
+Warning:  Handling non-coherent memory is a real pain.  You should
 only use this API if you positively know your driver will be
 required to work on one of the rare (usually non-PCI) architectures
-that simply cannot make consistent memory.
+that simply cannot make coherent memory.
 
 void
 dma_free_noncoherent(struct device *dev, size_t size, void *cpu_addr,
 			      dma_addr_t dma_handle)
 
-Free memory allocated by the nonconsistent API.  All parameters must
-be identical to those passed in (and returned by
-dma_alloc_noncoherent()).
+Free memory allocated by the non-coherent API. All parameters must be
+identical to those passed in (and returned by dma_alloc_noncoherent()).
 
 int
 dma_get_cache_alignment(void)
-- 
1.9.1

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/