aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DMA-API.txt
diff options
context:
space:
mode:
authorBjorn Helgaas <bhelgaas@google.com>2014-04-30 13:20:53 -0400
committerBjorn Helgaas <bhelgaas@google.com>2014-05-20 18:54:21 -0400
commit77f2ea2f8d0833f9e976368481fb9a0775acf9e7 (patch)
tree007a1fb1dcfa6f9cb0baa26548af80b90148fabd /Documentation/DMA-API.txt
parentc9eaa447e77efe77b7fa4c953bd62de8297fd6c5 (diff)
DMA-API: Clarify physical/bus address distinction
The DMA-API documentation sometimes refers to "physical addresses" when it really means "bus addresses." Sometimes these are identical, but they may be different if the bridge leading to the bus performs address translation. Update the documentation to use "bus address" when appropriate. Also, consistently capitalize "DMA", use parens with function names, use dev_printk() in examples, and reword a few sections for clarity. No functional change; documentation changes only. Signed-off-by: Bjorn Helgaas <bhelgaas@google.com> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Acked-by: Arnd Bergmann <arnd@arndb.de> Acked-by: James Bottomley <jbottomley@Parallels.com> Acked-by: Randy Dunlap <rdunlap@infradead.org>
Diffstat (limited to 'Documentation/DMA-API.txt')
-rw-r--r--Documentation/DMA-API.txt139
1 files changed, 72 insertions, 67 deletions
diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt
index e865279cec58..1147eba43128 100644
--- a/Documentation/DMA-API.txt
+++ b/Documentation/DMA-API.txt
@@ -4,22 +4,26 @@
4 James E.J. Bottomley <James.Bottomley@HansenPartnership.com> 4 James E.J. Bottomley <James.Bottomley@HansenPartnership.com>
5 5
6This document describes the DMA API. For a more gentle introduction 6This document describes the DMA API. For a more gentle introduction
7of the API (and actual examples) see 7of the API (and actual examples), see Documentation/DMA-API-HOWTO.txt.
8Documentation/DMA-API-HOWTO.txt.
9 8
10This API is split into two pieces. Part I describes the API. Part II 9This API is split into two pieces. Part I describes the basic API.
11describes the extensions to the API for supporting non-consistent 10Part II describes extensions for supporting non-consistent memory
12memory machines. Unless you know that your driver absolutely has to 11machines. Unless you know that your driver absolutely has to support
13support non-consistent platforms (this is usually only legacy 12non-consistent platforms (this is usually only legacy platforms) you
14platforms) you should only use the API described in part I. 13should only use the API described in part I.
15 14
16Part I - dma_ API 15Part I - dma_ API
17------------------------------------- 16-------------------------------------
18 17
19To get the dma_ API, you must #include <linux/dma-mapping.h> 18To get the dma_ API, you must #include <linux/dma-mapping.h>. This
19provides dma_addr_t and the interfaces described below.
20 20
21A dma_addr_t can hold any valid DMA or bus address for the platform. It
22can be given to a device to use as a DMA source or target. A cpu cannot
23reference a dma_addr_t directly because there may be translation between
24its physical address space and the bus address space.
21 25
22Part Ia - Using large dma-coherent buffers 26Part Ia - Using large DMA-coherent buffers
23------------------------------------------ 27------------------------------------------
24 28
25void * 29void *
@@ -33,20 +37,21 @@ to make sure to flush the processor's write buffers before telling
33devices to read that memory.) 37devices to read that memory.)
34 38
35This routine allocates a region of <size> bytes of consistent memory. 39This routine allocates a region of <size> bytes of consistent memory.
36It also returns a <dma_handle> which may be cast to an unsigned
37integer the same width as the bus and used as the physical address
38base of the region.
39 40
40Returns: a pointer to the allocated region (in the processor's virtual 41It returns a pointer to the allocated region (in the processor's virtual
41address space) or NULL if the allocation failed. 42address space) or NULL if the allocation failed.
42 43
44It also returns a <dma_handle> which may be cast to an unsigned integer the
45same width as the bus and given to the device as the bus address base of
46the region.
47
43Note: consistent memory can be expensive on some platforms, and the 48Note: consistent memory can be expensive on some platforms, and the
44minimum allocation length may be as big as a page, so you should 49minimum allocation length may be as big as a page, so you should
45consolidate your requests for consistent memory as much as possible. 50consolidate your requests for consistent memory as much as possible.
46The simplest way to do that is to use the dma_pool calls (see below). 51The simplest way to do that is to use the dma_pool calls (see below).
47 52
48The flag parameter (dma_alloc_coherent only) allows the caller to 53The flag parameter (dma_alloc_coherent() only) allows the caller to
49specify the GFP_ flags (see kmalloc) for the allocation (the 54specify the GFP_ flags (see kmalloc()) for the allocation (the
50implementation may choose to ignore flags that affect the location of 55implementation may choose to ignore flags that affect the location of
51the returned memory, like GFP_DMA). 56the returned memory, like GFP_DMA).
52 57
@@ -61,24 +66,24 @@ void
61dma_free_coherent(struct device *dev, size_t size, void *cpu_addr, 66dma_free_coherent(struct device *dev, size_t size, void *cpu_addr,
62 dma_addr_t dma_handle) 67 dma_addr_t dma_handle)
63 68
64Free the region of consistent memory you previously allocated. dev, 69Free a region of consistent memory you previously allocated. dev,
65size and dma_handle must all be the same as those passed into the 70size and dma_handle must all be the same as those passed into
66consistent allocate. cpu_addr must be the virtual address returned by 71dma_alloc_coherent(). cpu_addr must be the virtual address returned by
67the consistent allocate. 72the dma_alloc_coherent().
68 73
69Note that unlike their sibling allocation calls, these routines 74Note that unlike their sibling allocation calls, these routines
70may only be called with IRQs enabled. 75may only be called with IRQs enabled.
71 76
72 77
73Part Ib - Using small dma-coherent buffers 78Part Ib - Using small DMA-coherent buffers
74------------------------------------------ 79------------------------------------------
75 80
76To get this part of the dma_ API, you must #include <linux/dmapool.h> 81To get this part of the dma_ API, you must #include <linux/dmapool.h>
77 82
78Many drivers need lots of small dma-coherent memory regions for DMA 83Many drivers need lots of small DMA-coherent memory regions for DMA
79descriptors or I/O buffers. Rather than allocating in units of a page 84descriptors or I/O buffers. Rather than allocating in units of a page
80or more using dma_alloc_coherent(), you can use DMA pools. These work 85or more using dma_alloc_coherent(), you can use DMA pools. These work
81much like a struct kmem_cache, except that they use the dma-coherent allocator, 86much like a struct kmem_cache, except that they use the DMA-coherent allocator,
82not __get_free_pages(). Also, they understand common hardware constraints 87not __get_free_pages(). Also, they understand common hardware constraints
83for alignment, like queue heads needing to be aligned on N-byte boundaries. 88for alignment, like queue heads needing to be aligned on N-byte boundaries.
84 89
@@ -87,7 +92,7 @@ for alignment, like queue heads needing to be aligned on N-byte boundaries.
87 dma_pool_create(const char *name, struct device *dev, 92 dma_pool_create(const char *name, struct device *dev,
88 size_t size, size_t align, size_t alloc); 93 size_t size, size_t align, size_t alloc);
89 94
90The pool create() routines initialize a pool of dma-coherent buffers 95dma_pool_create() initializes a pool of DMA-coherent buffers
91for use with a given device. It must be called in a context which 96for use with a given device. It must be called in a context which
92can sleep. 97can sleep.
93 98
@@ -102,25 +107,26 @@ from this pool must not cross 4KByte boundaries.
102 void *dma_pool_alloc(struct dma_pool *pool, gfp_t gfp_flags, 107 void *dma_pool_alloc(struct dma_pool *pool, gfp_t gfp_flags,
103 dma_addr_t *dma_handle); 108 dma_addr_t *dma_handle);
104 109
105This allocates memory from the pool; the returned memory will meet the size 110This allocates memory from the pool; the returned memory will meet the
106and alignment requirements specified at creation time. Pass GFP_ATOMIC to 111size and alignment requirements specified at creation time. Pass
107prevent blocking, or if it's permitted (not in_interrupt, not holding SMP locks), 112GFP_ATOMIC to prevent blocking, or if it's permitted (not
108pass GFP_KERNEL to allow blocking. Like dma_alloc_coherent(), this returns 113in_interrupt, not holding SMP locks), pass GFP_KERNEL to allow
109two values: an address usable by the cpu, and the dma address usable by the 114blocking. Like dma_alloc_coherent(), this returns two values: an
110pool's device. 115address usable by the cpu, and the DMA address usable by the pool's
116device.
111 117
112 118
113 void dma_pool_free(struct dma_pool *pool, void *vaddr, 119 void dma_pool_free(struct dma_pool *pool, void *vaddr,
114 dma_addr_t addr); 120 dma_addr_t addr);
115 121
116This puts memory back into the pool. The pool is what was passed to 122This puts memory back into the pool. The pool is what was passed to
117the pool allocation routine; the cpu (vaddr) and dma addresses are what 123dma_pool_alloc(); the cpu (vaddr) and DMA addresses are what
118were returned when that routine allocated the memory being freed. 124were returned when that routine allocated the memory being freed.
119 125
120 126
121 void dma_pool_destroy(struct dma_pool *pool); 127 void dma_pool_destroy(struct dma_pool *pool);
122 128
123The pool destroy() routines free the resources of the pool. They must be 129dma_pool_destroy() frees the resources of the pool. It must be
124called in a context which can sleep. Make sure you've freed all allocated 130called in a context which can sleep. Make sure you've freed all allocated
125memory back to the pool before you destroy it. 131memory back to the pool before you destroy it.
126 132
@@ -187,9 +193,9 @@ dma_map_single(struct device *dev, void *cpu_addr, size_t size,
187 enum dma_data_direction direction) 193 enum dma_data_direction direction)
188 194
189Maps a piece of processor virtual memory so it can be accessed by the 195Maps a piece of processor virtual memory so it can be accessed by the
190device and returns the physical handle of the memory. 196device and returns the bus address of the memory.
191 197
192The direction for both api's may be converted freely by casting. 198The direction for both APIs may be converted freely by casting.
193However the dma_ API uses a strongly typed enumerator for its 199However the dma_ API uses a strongly typed enumerator for its
194direction: 200direction:
195 201
@@ -198,31 +204,30 @@ DMA_TO_DEVICE data is going from the memory to the device
198DMA_FROM_DEVICE data is coming from the device to the memory 204DMA_FROM_DEVICE data is coming from the device to the memory
199DMA_BIDIRECTIONAL direction isn't known 205DMA_BIDIRECTIONAL direction isn't known
200 206
201Notes: Not all memory regions in a machine can be mapped by this 207Notes: Not all memory regions in a machine can be mapped by this API.
202API. Further, regions that appear to be physically contiguous in 208Further, contiguous kernel virtual space may not be contiguous as
203kernel virtual space may not be contiguous as physical memory. Since 209physical memory. Since this API does not provide any scatter/gather
204this API does not provide any scatter/gather capability, it will fail 210capability, it will fail if the user tries to map a non-physically
205if the user tries to map a non-physically contiguous piece of memory. 211contiguous piece of memory. For this reason, memory to be mapped by
206For this reason, it is recommended that memory mapped by this API be 212this API should be obtained from sources which guarantee it to be
207obtained only from sources which guarantee it to be physically contiguous 213physically contiguous (like kmalloc).
208(like kmalloc). 214
209 215Further, the bus address of the memory must be within the
210Further, the physical address of the memory must be within the 216dma_mask of the device (the dma_mask is a bit mask of the
211dma_mask of the device (the dma_mask represents a bit mask of the 217addressable region for the device, i.e., if the bus address of
212addressable region for the device. I.e., if the physical address of 218the memory ANDed with the dma_mask is still equal to the bus
213the memory anded with the dma_mask is still equal to the physical 219address, then the device can perform DMA to the memory). To
214address, then the device can perform DMA to the memory). In order to
215ensure that the memory allocated by kmalloc is within the dma_mask, 220ensure that the memory allocated by kmalloc is within the dma_mask,
216the driver may specify various platform-dependent flags to restrict 221the driver may specify various platform-dependent flags to restrict
217the physical memory range of the allocation (e.g. on x86, GFP_DMA 222the bus address range of the allocation (e.g., on x86, GFP_DMA
218guarantees to be within the first 16Mb of available physical memory, 223guarantees to be within the first 16MB of available bus addresses,
219as required by ISA devices). 224as required by ISA devices).
220 225
221Note also that the above constraints on physical contiguity and 226Note also that the above constraints on physical contiguity and
222dma_mask may not apply if the platform has an IOMMU (a device which 227dma_mask may not apply if the platform has an IOMMU (a device which
223supplies a physical to virtual mapping between the I/O memory bus and 228maps an I/O bus address to a physical memory address). However, to be
224the device). However, to be portable, device driver writers may *not* 229portable, device driver writers may *not* assume that such an IOMMU
225assume that such an IOMMU exists. 230exists.
226 231
227Warnings: Memory coherency operates at a granularity called the cache 232Warnings: Memory coherency operates at a granularity called the cache
228line width. In order for memory mapped by this API to operate 233line width. In order for memory mapped by this API to operate
@@ -281,9 +286,9 @@ cache width is.
281int 286int
282dma_mapping_error(struct device *dev, dma_addr_t dma_addr) 287dma_mapping_error(struct device *dev, dma_addr_t dma_addr)
283 288
284In some circumstances dma_map_single and dma_map_page will fail to create 289In some circumstances dma_map_single() and dma_map_page() will fail to create
285a mapping. A driver can check for these errors by testing the returned 290a mapping. A driver can check for these errors by testing the returned
286dma address with dma_mapping_error(). A non-zero return value means the mapping 291DMA address with dma_mapping_error(). A non-zero return value means the mapping
287could not be created and the driver should take appropriate action (e.g. 292could not be created and the driver should take appropriate action (e.g.
288reduce current DMA mapping usage or delay and try again later). 293reduce current DMA mapping usage or delay and try again later).
289 294
@@ -291,7 +296,7 @@ reduce current DMA mapping usage or delay and try again later).
291 dma_map_sg(struct device *dev, struct scatterlist *sg, 296 dma_map_sg(struct device *dev, struct scatterlist *sg,
292 int nents, enum dma_data_direction direction) 297 int nents, enum dma_data_direction direction)
293 298
294Returns: the number of physical segments mapped (this may be shorter 299Returns: the number of bus address segments mapped (this may be shorter
295than <nents> passed in if some elements of the scatter/gather list are 300than <nents> passed in if some elements of the scatter/gather list are
296physically or virtually adjacent and an IOMMU maps them with a single 301physically or virtually adjacent and an IOMMU maps them with a single
297entry). 302entry).
@@ -299,7 +304,7 @@ entry).
299Please note that the sg cannot be mapped again if it has been mapped once. 304Please note that the sg cannot be mapped again if it has been mapped once.
300The mapping process is allowed to destroy information in the sg. 305The mapping process is allowed to destroy information in the sg.
301 306
302As with the other mapping interfaces, dma_map_sg can fail. When it 307As with the other mapping interfaces, dma_map_sg() can fail. When it
303does, 0 is returned and a driver must take appropriate action. It is 308does, 0 is returned and a driver must take appropriate action. It is
304critical that the driver do something, in the case of a block driver 309critical that the driver do something, in the case of a block driver
305aborting the request or even oopsing is better than doing nothing and 310aborting the request or even oopsing is better than doing nothing and
@@ -335,7 +340,7 @@ must be the same as those and passed in to the scatter/gather mapping
335API. 340API.
336 341
337Note: <nents> must be the number you passed in, *not* the number of 342Note: <nents> must be the number you passed in, *not* the number of
338physical entries returned. 343bus address entries returned.
339 344
340void 345void
341dma_sync_single_for_cpu(struct device *dev, dma_addr_t dma_handle, size_t size, 346dma_sync_single_for_cpu(struct device *dev, dma_addr_t dma_handle, size_t size,
@@ -391,10 +396,10 @@ The four functions above are just like the counterpart functions
391without the _attrs suffixes, except that they pass an optional 396without the _attrs suffixes, except that they pass an optional
392struct dma_attrs*. 397struct dma_attrs*.
393 398
394struct dma_attrs encapsulates a set of "dma attributes". For the 399struct dma_attrs encapsulates a set of "DMA attributes". For the
395definition of struct dma_attrs see linux/dma-attrs.h. 400definition of struct dma_attrs see linux/dma-attrs.h.
396 401
397The interpretation of dma attributes is architecture-specific, and 402The interpretation of DMA attributes is architecture-specific, and
398each attribute should be documented in Documentation/DMA-attributes.txt. 403each attribute should be documented in Documentation/DMA-attributes.txt.
399 404
400If struct dma_attrs* is NULL, the semantics of each of these 405If struct dma_attrs* is NULL, the semantics of each of these
@@ -458,7 +463,7 @@ Note: where the platform can return consistent memory, it will
458guarantee that the sync points become nops. 463guarantee that the sync points become nops.
459 464
460Warning: Handling non-consistent memory is a real pain. You should 465Warning: Handling non-consistent memory is a real pain. You should
461only ever use this API if you positively know your driver will be 466only use this API if you positively know your driver will be
462required to work on one of the rare (usually non-PCI) architectures 467required to work on one of the rare (usually non-PCI) architectures
463that simply cannot make consistent memory. 468that simply cannot make consistent memory.
464 469
@@ -496,26 +501,26 @@ dma_declare_coherent_memory(struct device *dev, dma_addr_t bus_addr,
496 dma_addr_t device_addr, size_t size, int 501 dma_addr_t device_addr, size_t size, int
497 flags) 502 flags)
498 503
499Declare region of memory to be handed out by dma_alloc_coherent when 504Declare region of memory to be handed out by dma_alloc_coherent() when
500it's asked for coherent memory for this device. 505it's asked for coherent memory for this device.
501 506
502bus_addr is the physical address to which the memory is currently 507bus_addr is the physical address to which the memory is currently
503assigned in the bus responding region (this will be used by the 508assigned in the bus responding region (this will be used by the
504platform to perform the mapping). 509platform to perform the mapping).
505 510
506device_addr is the physical address the device needs to be programmed 511device_addr is the bus address the device needs to be programmed
507with actually to address this memory (this will be handed out as the 512with actually to address this memory (this will be handed out as the
508dma_addr_t in dma_alloc_coherent()). 513dma_addr_t in dma_alloc_coherent()).
509 514
510size is the size of the area (must be multiples of PAGE_SIZE). 515size is the size of the area (must be multiples of PAGE_SIZE).
511 516
512flags can be or'd together and are: 517flags can be ORed together and are:
513 518
514DMA_MEMORY_MAP - request that the memory returned from 519DMA_MEMORY_MAP - request that the memory returned from
515dma_alloc_coherent() be directly writable. 520dma_alloc_coherent() be directly writable.
516 521
517DMA_MEMORY_IO - request that the memory returned from 522DMA_MEMORY_IO - request that the memory returned from
518dma_alloc_coherent() be addressable using read/write/memcpy_toio etc. 523dma_alloc_coherent() be addressable using read()/write()/memcpy_toio() etc.
519 524
520One or both of these flags must be present. 525One or both of these flags must be present.
521 526
@@ -572,7 +577,7 @@ region is occupied.
572Part III - Debug drivers use of the DMA-API 577Part III - Debug drivers use of the DMA-API
573------------------------------------------- 578-------------------------------------------
574 579
575The DMA-API as described above as some constraints. DMA addresses must be 580The DMA-API as described above has some constraints. DMA addresses must be
576released with the corresponding function with the same size for example. With 581released with the corresponding function with the same size for example. With
577the advent of hardware IOMMUs it becomes more and more important that drivers 582the advent of hardware IOMMUs it becomes more and more important that drivers
578do not violate those constraints. In the worst case such a violation can 583do not violate those constraints. In the worst case such a violation can
@@ -690,11 +695,11 @@ architectural default.
690void debug_dmap_mapping_error(struct device *dev, dma_addr_t dma_addr); 695void debug_dmap_mapping_error(struct device *dev, dma_addr_t dma_addr);
691 696
692dma-debug interface debug_dma_mapping_error() to debug drivers that fail 697dma-debug interface debug_dma_mapping_error() to debug drivers that fail
693to check dma mapping errors on addresses returned by dma_map_single() and 698to check DMA mapping errors on addresses returned by dma_map_single() and
694dma_map_page() interfaces. This interface clears a flag set by 699dma_map_page() interfaces. This interface clears a flag set by
695debug_dma_map_page() to indicate that dma_mapping_error() has been called by 700debug_dma_map_page() to indicate that dma_mapping_error() has been called by
696the driver. When driver does unmap, debug_dma_unmap() checks the flag and if 701the driver. When driver does unmap, debug_dma_unmap() checks the flag and if
697this flag is still set, prints warning message that includes call trace that 702this flag is still set, prints warning message that includes call trace that
698leads up to the unmap. This interface can be called from dma_mapping_error() 703leads up to the unmap. This interface can be called from dma_mapping_error()
699routines to enable dma mapping error check debugging. 704routines to enable DMA mapping error check debugging.
700 705