1 Dynamic DMA mapping using the generic device
2 ============================================
4 James E.J. Bottomley <James.Bottomley@HansenPartnership.com>
6 This document describes the DMA API. For a more gentle introduction
7 phrased in terms of the pci_ equivalents (and actual examples) see
10 This API is split into two pieces. Part I describes the API and the
11 corresponding pci_ API. Part II describes the extensions to the API
12 for supporting non-consistent memory machines. Unless you know that
13 your driver absolutely has to support non-consistent platforms (this
14 is usually only legacy platforms) you should only use the API
17 Part I - pci_ and dma_ Equivalent API
18 -------------------------------------
20 To get the pci_ API, you must #include <linux/pci.h>
21 To get the dma_ API, you must #include <linux/dma-mapping.h>
24 Part Ia - Using large dma-coherent buffers
25 ------------------------------------------
28 dma_alloc_coherent(struct device *dev, size_t size,
29 dma_addr_t *dma_handle, int flag)
31 pci_alloc_consistent(struct pci_dev *dev, size_t size,
32 dma_addr_t *dma_handle)
34 Consistent memory is memory for which a write by either the device or
35 the processor can immediately be read by the processor or device
36 without having to worry about caching effects.
38 This routine allocates a region of <size> bytes of consistent memory.
39 it also returns a <dma_handle> which may be cast to an unsigned
40 integer the same width as the bus and used as the physical address
43 Returns: a pointer to the allocated region (in the processor's virtual
44 address space) or NULL if the allocation failed.
46 Note: consistent memory can be expensive on some platforms, and the
47 minimum allocation length may be as big as a page, so you should
48 consolidate your requests for consistent memory as much as possible.
49 The simplest way to do that is to use the dma_pool calls (see below).
51 The flag parameter (dma_alloc_coherent only) allows the caller to
52 specify the GFP_ flags (see kmalloc) for the allocation (the
53 implementation may chose to ignore flags that affect the location of
54 the returned memory, like GFP_DMA). For pci_alloc_consistent, you
55 must assume GFP_ATOMIC behaviour.
58 dma_free_coherent(struct device *dev, size_t size, void *cpu_addr
59 dma_addr_t dma_handle)
61 pci_free_consistent(struct pci_dev *dev, size_t size, void *cpu_addr
62 dma_addr_t dma_handle)
64 Free the region of consistent memory you previously allocated. dev,
65 size and dma_handle must all be the same as those passed into the
66 consistent allocate. cpu_addr must be the virtual address returned by
67 the consistent allocate
70 Part Ib - Using small dma-coherent buffers
71 ------------------------------------------
73 To get this part of the dma_ API, you must #include <linux/dmapool.h>
75 Many drivers need lots of small dma-coherent memory regions for DMA
76 descriptors or I/O buffers. Rather than allocating in units of a page
77 or more using dma_alloc_coherent(), you can use DMA pools. These work
78 much like a kmem_cache_t, except that they use the dma-coherent allocator
79 not __get_free_pages(). Also, they understand common hardware constraints
80 for alignment, like queue heads needing to be aligned on N byte boundaries.
84 dma_pool_create(const char *name, struct device *dev,
85 size_t size, size_t align, size_t alloc);
88 pci_pool_create(const char *name, struct pci_device *dev,
89 size_t size, size_t align, size_t alloc);
91 The pool create() routines initialize a pool of dma-coherent buffers
92 for use with a given device. It must be called in a context which
95 The "name" is for diagnostics (like a kmem_cache_t name); dev and size
96 are like what you'd pass to dma_alloc_coherent(). The device's hardware
97 alignment requirement for this type of data is "align" (which is expressed
98 in bytes, and must be a power of two). If your device has no boundary
99 crossing restrictions, pass 0 for alloc; passing 4096 says memory allocated
100 from this pool must not cross 4KByte boundaries.
103 void *dma_pool_alloc(struct dma_pool *pool, int gfp_flags,
104 dma_addr_t *dma_handle);
106 void *pci_pool_alloc(struct pci_pool *pool, int gfp_flags,
107 dma_addr_t *dma_handle);
109 This allocates memory from the pool; the returned memory will meet the size
110 and alignment requirements specified at creation time. Pass GFP_ATOMIC to
111 prevent blocking, or if it's permitted (not in_interrupt, not holding SMP locks)
112 pass GFP_KERNEL to allow blocking. Like dma_alloc_coherent(), this returns
113 two values: an address usable by the cpu, and the dma address usable by the
117 void dma_pool_free(struct dma_pool *pool, void *vaddr,
120 void pci_pool_free(struct pci_pool *pool, void *vaddr,
123 This puts memory back into the pool. The pool is what was passed to
124 the the pool allocation routine; the cpu and dma addresses are what
125 were returned when that routine allocated the memory being freed.
128 void dma_pool_destroy(struct dma_pool *pool);
130 void pci_pool_destroy(struct pci_pool *pool);
132 The pool destroy() routines free the resources of the pool. They must be
133 called in a context which can sleep. Make sure you've freed all allocated
134 memory back to the pool before you destroy it.
137 Part Ic - DMA addressing limitations
138 ------------------------------------
141 dma_supported(struct device *dev, u64 mask)
143 pci_dma_supported(struct device *dev, u64 mask)
145 Checks to see if the device can support DMA to the memory described by
148 Returns: 1 if it can and 0 if it can't.
150 Notes: This routine merely tests to see if the mask is possible. It
151 won't change the current mask settings. It is more intended as an
152 internal API for use by the platform than an external API for use by
156 dma_set_mask(struct device *dev, u64 mask)
158 pci_set_dma_mask(struct pci_device *dev, u64 mask)
160 Checks to see if the mask is possible and updates the device
163 Returns: 1 if successful and 0 if not
166 Part Id - Streaming DMA mappings
167 --------------------------------
170 dma_map_single(struct device *dev, void *cpu_addr, size_t size,
171 enum dma_data_direction direction)
173 pci_map_single(struct device *dev, void *cpu_addr, size_t size,
176 Maps a piece of processor virtual memory so it can be accessed by the
177 device and returns the physical handle of the memory.
179 The direction for both api's may be converted freely by casting.
180 However the dma_ API uses a strongly typed enumerator for its
183 DMA_NONE = PCI_DMA_NONE no direction (used for
185 DMA_TO_DEVICE = PCI_DMA_TODEVICE data is going from the
187 DMA_FROM_DEVICE = PCI_DMA_FROMDEVICE data is coming from
190 DMA_BIDIRECTIONAL = PCI_DMA_BIDIRECTIONAL direction isn't known
192 Notes: Not all memory regions in a machine can be mapped by this
193 API. Further, regions that appear to be physically contiguous in
194 kernel virtual space may not be contiguous as physical memory. Since
195 this API does not provide any scatter/gather capability, it will fail
196 if the user tries to map a non physically contiguous piece of memory.
197 For this reason, it is recommended that memory mapped by this API be
198 obtained only from sources which guarantee to be physically contiguous
201 Further, the physical address of the memory must be within the
202 dma_mask of the device (the dma_mask represents a bit mask of the
203 addressable region for the device. i.e. if the physical address of
204 the memory anded with the dma_mask is still equal to the physical
205 address, then the device can perform DMA to the memory). In order to
206 ensure that the memory allocated by kmalloc is within the dma_mask,
207 the driver may specify various platform dependent flags to restrict
208 the physical memory range of the allocation (e.g. on x86, GFP_DMA
209 guarantees to be within the first 16Mb of available physical memory,
210 as required by ISA devices).
212 Note also that the above constraints on physical contiguity and
213 dma_mask may not apply if the platform has an IOMMU (a device which
214 supplies a physical to virtual mapping between the I/O memory bus and
215 the device). However, to be portable, device driver writers may *not*
216 assume that such an IOMMU exists.
218 Warnings: Memory coherency operates at a granularity called the cache
219 line width. In order for memory mapped by this API to operate
220 correctly, the mapped region must begin exactly on a cache line
221 boundary and end exactly on one (to prevent two separately mapped
222 regions from sharing a single cache line). Since the cache line size
223 may not be known at compile time, the API will not enforce this
224 requirement. Therefore, it is recommended that driver writers who
225 don't take special care to determine the cache line size at run time
226 only map virtual regions that begin and end on page boundaries (which
227 are guaranteed also to be cache line boundaries).
229 DMA_TO_DEVICE synchronisation must be done after the last modification
230 of the memory region by the software and before it is handed off to
231 the driver. Once this primitive is used. Memory covered by this
232 primitive should be treated as read only by the device. If the device
233 may write to it at any point, it should be DMA_BIDIRECTIONAL (see
236 DMA_FROM_DEVICE synchronisation must be done before the driver
237 accesses data that may be changed by the device. This memory should
238 be treated as read only by the driver. If the driver needs to write
239 to it at any point, it should be DMA_BIDIRECTIONAL (see below).
241 DMA_BIDIRECTIONAL requires special handling: it means that the driver
242 isn't sure if the memory was modified before being handed off to the
243 device and also isn't sure if the device will also modify it. Thus,
244 you must always sync bidirectional memory twice: once before the
245 memory is handed off to the device (to make sure all memory changes
246 are flushed from the processor) and once before the data may be
247 accessed after being used by the device (to make sure any processor
248 cache lines are updated with data that the device may have changed.
251 dma_unmap_single(struct device *dev, dma_addr_t dma_addr, size_t size,
252 enum dma_data_direction direction)
254 pci_unmap_single(struct pci_dev *hwdev, dma_addr_t dma_addr,
255 size_t size, int direction)
257 Unmaps the region previously mapped. All the parameters passed in
258 must be identical to those passed in (and returned) by the mapping
262 dma_map_page(struct device *dev, struct page *page,
263 unsigned long offset, size_t size,
264 enum dma_data_direction direction)
266 pci_map_page(struct pci_dev *hwdev, struct page *page,
267 unsigned long offset, size_t size, int direction)
269 dma_unmap_page(struct device *dev, dma_addr_t dma_address, size_t size,
270 enum dma_data_direction direction)
272 pci_unmap_page(struct pci_dev *hwdev, dma_addr_t dma_address,
273 size_t size, int direction)
275 API for mapping and unmapping for pages. All the notes and warnings
276 for the other mapping APIs apply here. Also, although the <offset>
277 and <size> parameters are provided to do partial page mapping, it is
278 recommended that you never use these unless you really know what the
282 dma_mapping_error(dma_addr_t dma_addr)
285 pci_dma_mapping_error(dma_addr_t dma_addr)
287 In some circumstances dma_map_single and dma_map_page will fail to create
288 a mapping. A driver can check for these errors by testing the returned
289 dma address with dma_mapping_error(). A non zero return value means the mapping
290 could not be created and the driver should take appropriate action (eg
291 reduce current DMA mapping usage or delay and try again later).
294 dma_map_sg(struct device *dev, struct scatterlist *sg, int nents,
295 enum dma_data_direction direction)
297 pci_map_sg(struct pci_dev *hwdev, struct scatterlist *sg,
298 int nents, int direction)
300 Maps a scatter gather list from the block layer.
302 Returns: the number of physical segments mapped (this may be shorted
303 than <nents> passed in if the block layer determines that some
304 elements of the scatter/gather list are physically adjacent and thus
305 may be mapped with a single entry).
307 Please note that the sg cannot be mapped again if it has been mapped once.
308 The mapping process is allowed to destroy information in the sg.
310 As with the other mapping interfaces, dma_map_sg can fail. When it
311 does, 0 is returned and a driver must take appropriate action. It is
312 critical that the driver do something, in the case of a block driver
313 aborting the request or even oopsing is better than doing nothing and
314 corrupting the filesystem.
317 dma_unmap_sg(struct device *dev, struct scatterlist *sg, int nhwentries,
318 enum dma_data_direction direction)
320 pci_unmap_sg(struct pci_dev *hwdev, struct scatterlist *sg,
321 int nents, int direction)
323 unmap the previously mapped scatter/gather list. All the parameters
324 must be the same as those and passed in to the scatter/gather mapping
327 Note: <nents> must be the number you passed in, *not* the number of
328 physical entries returned.
331 dma_sync_single(struct device *dev, dma_addr_t dma_handle, size_t size,
332 enum dma_data_direction direction)
334 pci_dma_sync_single(struct pci_dev *hwdev, dma_addr_t dma_handle,
335 size_t size, int direction)
337 dma_sync_sg(struct device *dev, struct scatterlist *sg, int nelems,
338 enum dma_data_direction direction)
340 pci_dma_sync_sg(struct pci_dev *hwdev, struct scatterlist *sg,
341 int nelems, int direction)
343 synchronise a single contiguous or scatter/gather mapping. All the
344 parameters must be the same as those passed into the single mapping
347 Notes: You must do this:
349 - Before reading values that have been written by DMA from the device
350 (use the DMA_FROM_DEVICE direction)
351 - After writing values that will be written to the device using DMA
352 (use the DMA_TO_DEVICE) direction
353 - before *and* after handing memory to the device if the memory is
356 See also dma_map_single().
359 Part II - Advanced dma_ usage
360 -----------------------------
362 Warning: These pieces of the DMA API have no PCI equivalent. They
363 should also not be used in the majority of cases, since they cater for
364 unlikely corner cases that don't belong in usual drivers.
366 If you don't understand how cache line coherency works between a
367 processor and an I/O device, you should not be using this part of the
371 dma_alloc_noncoherent(struct device *dev, size_t size,
372 dma_addr_t *dma_handle, int flag)
374 Identical to dma_alloc_coherent() except that the platform will
375 choose to return either consistent or non-consistent memory as it sees
376 fit. By using this API, you are guaranteeing to the platform that you
377 have all the correct and necessary sync points for this memory in the
378 driver should it choose to return non-consistent memory.
380 Note: where the platform can return consistent memory, it will
381 guarantee that the sync points become nops.
383 Warning: Handling non-consistent memory is a real pain. You should
384 only ever use this API if you positively know your driver will be
385 required to work on one of the rare (usually non-PCI) architectures
386 that simply cannot make consistent memory.
389 dma_free_noncoherent(struct device *dev, size_t size, void *cpu_addr,
390 dma_addr_t dma_handle)
392 free memory allocated by the nonconsistent API. All parameters must
393 be identical to those passed in (and returned by
394 dma_alloc_noncoherent()).
397 dma_is_consistent(dma_addr_t dma_handle)
399 returns true if the memory pointed to by the dma_handle is actually
403 dma_get_cache_alignment(void)
405 returns the processor cache alignment. This is the absolute minimum
406 alignment *and* width that you must observe when either mapping
407 memory or doing partial flushes.
409 Notes: This API may return a number *larger* than the actual cache
410 line, but it will guarantee that one or more cache lines fit exactly
411 into the width returned by this call. It will also always be a power
412 of two for easy alignment
415 dma_sync_single_range(struct device *dev, dma_addr_t dma_handle,
416 unsigned long offset, size_t size,
417 enum dma_data_direction direction)
419 does a partial sync. starting at offset and continuing for size. You
420 must be careful to observe the cache alignment and width when doing
421 anything like this. You must also be extra careful about accessing
422 memory you intend to sync partially.
425 dma_cache_sync(void *vaddr, size_t size,
426 enum dma_data_direction direction)
428 Do a partial sync of memory that was allocated by
429 dma_alloc_noncoherent(), starting at virtual address vaddr and
430 continuing on for size. Again, you *must* observe the cache line
431 boundaries when doing this.