Specifications

This is the Title of the Book, eMatter Edition

Direct Memory Access

447

this function so that the buffer is placed in a location that works with DMA; usually

the memory is just allocated with get_free_pages (but note that the size is in bytes,

rather than an order value). The

flag argument is the usual GFP_ value describing how

the memory is to be allocated; it should usually be GFP_KERNEL (usually) or GFP_ATOMIC

(when running in atomic context).

When the buffer is no longer needed (usually at module unload time), it should be

returned to the system with dma_free_coherent:

void dma_free_coherent(struct device *dev, size_t size,

void *vaddr, dma_addr_t dma_handle);

Note that this function, like many of the generic DMA functions, requires that all of

the size, CPU address, and bus address arguments be provided.

DMA pools

A DMA pool is an allocation mechanism for small, coherent DMA mappings. Map-

pings obtained from dma_alloc_coherent may have a minimum size of one page. If

your device needs smaller DMA areas than that, you should probably be using a

DMA pool. DMA pools are also useful in situations where you may be tempted to

perform DMA to small areas embedded within a larger structure. Some very obscure

driver bugs have been traced down to cache coherency problems with structure fields

adjacent to small DMA areas. To avoid this problem, you should always allocate

areas for DMA operations explicitly, away from other, non-DMA data structures.

The DMA pool functions are defined in <linux/dmapool.h>.

A DMA pool must be created before use with a call to:

struct dma_pool *dma_pool_create(const char *name, struct device *dev,

size_t size, size_t align,

size_t allocation);

Here, name is a name for the pool, dev is your device structure, size is the size of the

buffers to be allocated from this pool,

align is the required hardware alignment for

allocations from the pool (expressed in bytes), and

allocation is, if nonzero, a mem-

ory boundary that allocations should not exceed. If

allocation is passed as 4096, for

example, the buffers allocated from this pool do not cross 4-KB boundaries.

When you are done with a pool, it can be freed with:

void dma_pool_destroy(struct dma_pool *pool);

You should return all allocations to the pool before destroying it.

Allocations are handled with dma_pool_alloc:

void *dma_pool_alloc(struct dma_pool *pool, int mem_flags,

dma_addr_t *handle);

For this call, mem_flags is the usual set of GFP_ allocation flags. If all goes well, a

region of memory (of the size specified when the pool was created) is allocated and

,ch15.13676 Page 447 Friday, January 21, 2005 11:04 AM