1 Dynamic DMA mapping using the generic device 2 ============================================ 3 4 James E.J. Bottomley <James.Bottomley@HansenPartnership.com> 5 6This document describes the DMA API. For a more gentle introduction 7phrased in terms of the pci_ equivalents (and actual examples) see 8DMA-mapping.txt 9 10This API is split into two pieces. Part I describes the API and the 11corresponding pci_ API. Part II describes the extensions to the API 12for supporting non-consistent memory machines. Unless you know that 13your driver absolutely has to support non-consistent platforms (this 14is usually only legacy platforms) you should only use the API 15described in part I. 16 17Part I - pci_ and dma_ Equivalent API 18------------------------------------- 19 20To get the pci_ API, you must #include <linux/pci.h> 21To get the dma_ API, you must #include <linux/dma-mapping.h> 22 23void * 24dma_alloc_coherent(struct device *dev, size_t size, 25 dma_addr_t *dma_handle, int flag) 26void * 27pci_alloc_consistent(struct pci_dev *dev, size_t size, 28 dma_addr_t *dma_handle) 29 30Consistent memory is memory for which a write by either the device or 31the processor can immediately be read by the processor or device 32without having to worry about caching effects. 33 34This routine allocates a region of <size> bytes of consistent memory. 35it also returns a <dma_handle> which may be cast to an unsigned 36integer the same width as the bus and used as the physical address 37base of the region. 38 39Returns: a pointer to the allocated region (in the processor's virtual 40address space) or NULL if the allocation failed. 41 42Note: consistent memory can be expensive on some platforms, and the 43minimum allocation length may be as big as a page, so you should 44consolidate your requests for consistent memory as much as possible. 45 46The flag parameter (dma_alloc_coherent only) allows the caller to 47specify the GFP_ flags (see kmalloc) for the allocation (the 48implementation may chose to ignore flags that affect the location of 49the returned memory, like GFP_DMA). For pci_alloc_consistent, you 50must assume GFP_ATOMIC behaviour. 51 52void 53dma_free_coherent(struct device *dev, size_t size, void *cpu_addr 54 dma_addr_t dma_handle) 55void 56pci_free_consistent(struct pci_dev *dev, size_t size, void *cpu_addr 57 dma_addr_t dma_handle) 58 59Free the region of consistent memory you previously allocated. dev, 60size and dma_handle must all be the same as those passed into the 61consistent allocate. cpu_addr must be the virtual address returned by 62the consistent allocate 63 64int 65dma_supported(struct device *dev, u64 mask) 66int 67pci_dma_supported(struct device *dev, u64 mask) 68 69Checks to see if the device can support DMA to the memory described by 70mask. 71 72Returns: 1 if it can and 0 if it can't. 73 74Notes: This routine merely tests to see if the mask is possible. It 75won't change the current mask settings. It is more intended as an 76internal API for use by the platform than an external API for use by 77driver writers. 78 79int 80dma_set_mask(struct device *dev, u64 mask) 81int 82pci_set_dma_mask(struct pci_device *dev, u64 mask) 83 84Checks to see if the mask is possible and updates the device 85parameters if it is. 86 87Returns: 1 if successful and 0 if not 88 89dma_addr_t 90dma_map_single(struct device *dev, void *cpu_addr, size_t size, 91 enum dma_data_direction direction) 92dma_addr_t 93pci_map_single(struct device *dev, void *cpu_addr, size_t size, 94 int direction) 95 96Maps a piece of processor virtual memory so it can be accessed by the 97device and returns the physical handle of the memory. 98 99The direction for both api's may be converted freely by casting. 100However the dma_ API uses a strongly typed enumerator for its 101direction: 102 103DMA_NONE = PCI_DMA_NONE no direction (used for 104 debugging) 105DMA_TO_DEVICE = PCI_DMA_TODEVICE data is going from the 106 memory to the device 107DMA_FROM_DEVICE = PCI_DMA_FROMDEVICE data is coming from 108 the device to the 109 memory 110DMA_BIDIRECTIONAL = PCI_DMA_BIDIRECTIONAL direction isn't known 111 112Notes: Not all memory regions in a machine can be mapped by this 113API. Further, regions that appear to be physically contiguous in 114kernel virtual space may not be contiguous as physical memory. Since 115this API does not provide any scatter/gather capability, it will fail 116if the user tries to map a non physically contiguous piece of memory. 117For this reason, it is recommended that memory mapped by this API be 118obtained only from sources which guarantee to be physically contiguous 119(like kmalloc). 120 121Further, the physical address of the memory must be within the 122dma_mask of the device (the dma_mask represents a bit mask of the 123addressable region for the device. i.e. if the physical address of 124the memory anded with the dma_mask is still equal to the physical 125address, then the device can perform DMA to the memory). In order to 126ensure that the memory allocated by kmalloc is within the dma_mask, 127the driver may specify various platform dependent flags to restrict 128the physical memory range of the allocation (e.g. on x86, GFP_DMA 129guarantees to be within the first 16Mb of available physical memory, 130as required by ISA devices). 131 132Note also that the above constraints on physical contiguity and 133dma_mask may not apply if the platform has an IOMMU (a device which 134supplies a physical to virtual mapping between the I/O memory bus and 135the device). However, to be portable, device driver writers may *not* 136assume that such an IOMMU exists. 137 138Warnings: Memory coherency operates at a granularity called the cache 139line width. In order for memory mapped by this API to operate 140correctly, the mapped region must begin exactly on a cache line 141boundary and end exactly on one (to prevent two separately mapped 142regions from sharing a single cache line). Since the cache line size 143may not be known at compile time, the API will not enforce this 144requirement. Therefore, it is recommended that driver writers who 145don't take special care to determine the cache line size at run time 146only map virtual regions that begin and end on page boundaries (which 147are guaranteed also to be cache line boundaries). 148 149DMA_TO_DEVICE synchronisation must be done after the last modification 150of the memory region by the software and before it is handed off to 151the driver. Once this primitive is used. Memory covered by this 152primitive should be treated as read only by the device. If the device 153may write to it at any point, it should be DMA_BIDIRECTIONAL (see 154below). 155 156DMA_FROM_DEVICE synchronisation must be done before the driver 157accesses data that may be changed by the device. This memory should 158be treated as read only by the driver. If the driver needs to write 159to it at any point, it should be DMA_BIDIRECTIONAL (see below). 160 161DMA_BIDIRECTIONAL requires special handling: it means that the driver 162isn't sure if the memory was modified before being handed off to the 163device and also isn't sure if the device will also modify it. Thus, 164you must always sync bidirectional memory twice: once before the 165memory is handed off to the device (to make sure all memory changes 166are flushed from the processor) and once before the data may be 167accessed after being used by the device (to make sure any processor 168cache lines are updated with data that the device may have changed. 169 170void 171dma_unmap_single(struct device *dev, dma_addr_t dma_addr, size_t size, 172 enum dma_data_direction direction) 173void 174pci_unmap_single(struct pci_dev *hwdev, dma_addr_t dma_addr, 175 size_t size, int direction) 176 177Unmaps the region previously mapped. All the parameters passed in 178must be identical to those passed in (and returned) by the mapping 179API. 180 181dma_addr_t 182dma_map_page(struct device *dev, struct page *page, 183 unsigned long offset, size_t size, 184 enum dma_data_direction direction) 185dma_addr_t 186pci_map_page(struct pci_dev *hwdev, struct page *page, 187 unsigned long offset, size_t size, int direction) 188void 189dma_unmap_page(struct device *dev, dma_addr_t dma_address, size_t size, 190 enum dma_data_direction direction) 191void 192pci_unmap_page(struct pci_dev *hwdev, dma_addr_t dma_address, 193 size_t size, int direction) 194 195API for mapping and unmapping for pages. All the notes and warnings 196for the other mapping APIs apply here. Also, although the <offset> 197and <size> parameters are provided to do partial page mapping, it is 198recommended that you never use these unless you really know what the 199cache width is. 200 201int 202dma_map_sg(struct device *dev, struct scatterlist *sg, int nents, 203 enum dma_data_direction direction) 204int 205pci_map_sg(struct pci_dev *hwdev, struct scatterlist *sg, 206 int nents, int direction) 207 208Maps a scatter gather list from the block layer. 209 210Returns: the number of physical segments mapped (this may be shorted 211than <nents> passed in if the block layer determines that some 212elements of the scatter/gather list are physically adjacent and thus 213may be mapped with a single entry). 214 215void 216dma_unmap_sg(struct device *dev, struct scatterlist *sg, int nhwentries, 217 enum dma_data_direction direction) 218void 219pci_unmap_sg(struct pci_dev *hwdev, struct scatterlist *sg, 220 int nents, int direction) 221 222unmap the previously mapped scatter/gather list. All the parameters 223must be the same as those and passed in to the scatter/gather mapping 224API. 225 226Note: <nents> must be the number you passed in, *not* the number of 227physical entries returned. 228 229void 230dma_sync_single(struct device *dev, dma_addr_t dma_handle, size_t size, 231 enum dma_data_direction direction) 232void 233pci_dma_sync_single(struct pci_dev *hwdev, dma_addr_t dma_handle, 234 size_t size, int direction) 235void 236dma_sync_sg(struct device *dev, struct scatterlist *sg, int nelems, 237 enum dma_data_direction direction) 238void 239pci_dma_sync_sg(struct pci_dev *hwdev, struct scatterlist *sg, 240 int nelems, int direction) 241 242synchronise a single contiguous or scatter/gather mapping. All the 243parameters must be the same as those passed into the single mapping 244API. 245 246Notes: You must do this: 247 248- Before reading values that have been written by DMA from the device 249 (use the DMA_FROM_DEVICE direction) 250- After writing values that will be written to the device using DMA 251 (use the DMA_TO_DEVICE) direction 252- before *and* after handing memory to the device if the memory is 253 DMA_BIDIRECTIONAL 254 255See also dma_map_single(). 256 257Part II - Advanced dma_ usage 258----------------------------- 259 260Warning: These pieces of the DMA API have no PCI equivalent. They 261should also not be used in the majority of cases, since they cater for 262unlikely corner cases that don't belong in usual drivers. 263 264If you don't understand how cache line coherency works between a 265processor and an I/O device, you should not be using this part of the 266API at all. 267 268void * 269dma_alloc_noncoherent(struct device *dev, size_t size, 270 dma_addr_t *dma_handle, int flag) 271 272Identical to dma_alloc_coherent() except that the platform will 273choose to return either consistent or non-consistent memory as it sees 274fit. By using this API, you are guaranteeing to the platform that you 275have all the correct and necessary sync points for this memory in the 276driver should it choose to return non-consistent memory. 277 278Note: where the platform can return consistent memory, it will 279guarantee that the sync points become nops. 280 281Warning: Handling non-consistent memory is a real pain. You should 282only ever use this API if you positively know your driver will be 283required to work on one of the rare (usually non-PCI) architectures 284that simply cannot make consistent memory. 285 286void 287dma_free_noncoherent(struct device *dev, size_t size, void *cpu_addr, 288 dma_addr_t dma_handle) 289 290free memory allocated by the nonconsistent API. All parameters must 291be identical to those passed in (and returned by 292dma_alloc_noncoherent()). 293 294int 295dma_is_consistent(dma_addr_t dma_handle) 296 297returns true if the memory pointed to by the dma_handle is actually 298consistent. 299 300int 301dma_get_cache_alignment(void) 302 303returns the processor cache alignment. This is the absolute minimum 304alignment *and* width that you must observe when either mapping 305memory or doing partial flushes. 306 307Notes: This API may return a number *larger* than the actual cache 308line, but it will guarantee that one or more cache lines fit exactly 309into the width returned by this call. It will also always be a power 310of two for easy alignment 311 312void 313dma_sync_single_range(struct device *dev, dma_addr_t dma_handle, 314 unsigned long offset, size_t size, 315 enum dma_data_direction direction) 316 317does a partial sync. starting at offset and continuing for size. You 318must be careful to observe the cache alignment and width when doing 319anything like this. You must also be extra careful about accessing 320memory you intend to sync partially. 321 322void 323dma_cache_sync(void *vaddr, size_t size, 324 enum dma_data_direction direction) 325 326Do a partial sync of memory that was allocated by 327dma_alloc_noncoherent(), starting at virtual address vaddr and 328continuing on for size. Again, you *must* observe the cache line 329boundaries when doing this. 330 331 332