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@xxxxxxxx> --- 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-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
