lkml.org 
[lkml]   [2015]   [May]   [11]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
From
Subject[PATCH] Documentation/DMA-API.txt: Change "consistent" into "coherent"
Date
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@topic.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


\
 
 \ /
  Last update: 2015-05-11 15:21    [W:0.029 / U:14.012 seconds]
©2003-2018 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site