linux-3.3/Documentation/DMA-API.txt

12 memory machines.  Unless you know that your driver absolutely has to
29 Consistent memory is memory for which a write by either the device or
33 devices to read that memory.)
35 This routine allocates a region of <size> bytes of consistent memory.
43 Note: consistent memory can be expensive on some platforms, and the
45 consolidate your requests for consistent memory as much as possible.
51 the returned memory, like GFP_DMA).
57 Wraps dma_alloc_coherent() and also zeroes the returned memory if the
64 Free the region of consistent memory you previously allocated.  dev,
78 Many drivers need lots of small dma-coherent memory regions for DMA
98 crossing restrictions, pass 0 for alloc; passing 4096 says memory allocated
105 This allocates memory from the pool; the returned memory will meet the size
116 This puts memory back into the pool.  The pool is what was passed to
118 were returned when that routine allocated the memory being freed.
125 memory back to the pool before you destroy it.
134 Checks to see if the device can support DMA to the memory described by
165 is the minimum required to cover all of memory.  Examining the
181 Maps a piece of processor virtual memory so it can be accessed by the
182 device and returns the physical handle of the memory.
189 DMA_TO_DEVICE		data is going from the memory to the device
190 DMA_FROM_DEVICE		data is coming from the device to the memory
193 Notes:  Not all memory regions in a machine can be mapped by this
195 kernel virtual space may not be contiguous as physical memory.  Since
197 if the user tries to map a non-physically contiguous piece of memory.
198 For this reason, it is recommended that memory mapped by this API be
202 Further, the physical address of the memory must be within the
205 the memory anded with the dma_mask is still equal to the physical
206 address, then the device can perform DMA to the memory).  In order to
207 ensure that the memory allocated by kmalloc is within the dma_mask,
209 the physical memory range of the allocation (e.g. on x86, GFP_DMA
210 guarantees to be within the first 16Mb of available physical memory,
215 supplies a physical to virtual mapping between the I/O memory bus and
219 Warnings:  Memory coherency operates at a granularity called the cache
220 line width.  In order for memory mapped by this API to operate
231 of the memory region by the software and before it is handed off to
232 the driver.  Once this primitive is used, memory covered by this
238 accesses data that may be changed by the device.  This memory should
243 isn't sure if the memory was modified before being handed off to the
245 you must always sync bidirectional memory twice: once before the
246 memory is handed off to the device (to make sure all memory changes
357 - before *and* after handing memory to the device if the memory is
398 you could pass an attribute DMA_ATTR_FOO when mapping memory
444 choose to return either consistent or non-consistent memory as it sees
446 have all the correct and necessary sync points for this memory in the
447 driver should it choose to return non-consistent memory.
449 Note: where the platform can return consistent memory, it will
452 Warning:  Handling non-consistent memory is a real pain.  You should
455 that simply cannot make consistent memory.
461 Free memory allocated by the nonconsistent API.  All parameters must
470 memory or doing partial flushes.
481 Do a partial sync of memory that was allocated by
491 Declare region of memory to be handed out by dma_alloc_coherent when
492 it's asked for coherent memory for this device.
494 bus_addr is the physical address to which the memory is currently
499 with actually to address this memory (this will be handed out as the
506 DMA_MEMORY_MAP - request that the memory returned from
509 DMA_MEMORY_IO - request that the memory returned from
514 DMA_MEMORY_INCLUDES_CHILDREN - make the declared memory be allocated by
515 dma_alloc_coherent of any child devices of this one (for memory residing
518 DMA_MEMORY_EXCLUSIVE - only allocate memory from the declared regions.
519 Do not allow dma_alloc_coherent() to fall back to system memory when
520 it's out of memory in the declared region.
527 Note, for DMA_MEMORY_IO returns, all subsequent memory returned by
534 memory may be declared per device.
543 Remove the memory region previously declared from the system.  This
546 driver's job to ensure that no parts of this memory region are
561 address of the memory, or an error (via PTR_ERR()) if any part of the
580 about what DMA memory was allocated for which device. If this code detects an
588 forcedeth 0000:00:08.0: DMA-API: device driver frees DMA memory with wrong
635 				happen when it runs out of memory or if it was