Documentation/core-api/dma-api-howto.rst

2 Dynamic DMA mapping Guide
9 This is a guide to device driver writers on how to use the DMA API
11 DMA-API.txt.
13 CPU and DMA addresses
16 There are several kinds of addresses involved in the DMA API, and it's
31 registers at an MMIO address, or if it performs DMA to read or write system
37 From a device's point of view, DMA uses the bus address space, but it may
40 so devices only need to use 32-bit DMA addresses.
75 If the device supports DMA, the driver sets up a buffer using kmalloc() or
79 cannot because DMA doesn't go through the CPU virtual memory system.
81 In some simple systems, the device can do DMA directly to physical address
82 Y.  But in many others, there is IOMMU hardware that translates DMA
84 of the reason for the DMA API: the driver can give a virtual address X to
86 mapping and returns the DMA address Z.  The driver then tells the device to
87 do DMA to Z, and the IOMMU maps it to the buffer at address Y in system
90 So that Linux can use the dynamic DMA mapping, it needs some help from the
91 drivers, namely it has to take into account that DMA addresses should be
92 mapped only for the time they are actually used and unmapped after the DMA
98 Note that the DMA API works with any bus independent of the underlying
99 microprocessor architecture. You should use the DMA API rather than the
100 bus-specific DMA API, i.e., use the dma_map_*() interfaces rather than the
108 can hold any valid DMA address for the platform and should be used
109 everywhere you hold a DMA address returned from the DMA mapping functions.
111 What memory is DMA'able?
115 be used with the DMA mapping facilities.  There has been an unwritten
121 (i.e. kmalloc() or kmem_cache_alloc()) then you may DMA to/from
125 returned from vmalloc() for DMA.  It is possible to DMA to the
134 stack addresses for DMA.  These could all be mapped somewhere entirely
136 memory could physically work with DMA, you'd need to ensure the I/O
138 sharing problems (data corruption) on CPUs with DMA-incoherent caches.
139 (The CPU could write to one word, DMA would write to a different one
143 call and DMA to/from that.  This is similar to vmalloc().
147 for you to DMA from/to.
149 DMA addressing capabilities
152 By default, the kernel assumes that your device can address 32-bits of DMA
161 For correct operation, you must set the DMA mask to inform the kernel about
162 your devices DMA addressing capabilities.
188 These calls usually return zero to indicated your device can perform DMA
191 system.  If it returns non-zero, your device cannot perform DMA properly on
193 You must not use DMA on this device unless the dma_set_mask family of
198 1) Use some non-DMA mode for data transfer, if possible.
202 setting the DMA mask fails.  In this manner, if a user of your driver reports
209 		dev_warn(dev, "mydev: No suitable DMA available\n");
218 		dev_warn(dev, "mydev: No suitable DMA available\n");
231 		dev_warn(dev, "mydev: 24-bit DMA addressing not available\n");
237 kernel will use this information later when you make DMA mappings.
243 DMA addressing limitations, you may wish to probe each mask and
261 		dev_warn(dev, "%s: Playback disabled due to DMA limitations\n",
268 		dev_warn(dev, "%s: Record disabled due to DMA limitations\n",
274 and thus retaining the 16MB DMA addressing limitations of ISA.
276 Types of DMA mappings
279 There are two types of DMA mappings:
281 - Consistent DMA mappings which are usually mapped at driver
290   bits of the DMA space.  However, for future compatibility you should
296 	- Network card DMA ring descriptors.
307 	     Consistent DMA memory does not preclude the usage of
325 - Streaming DMA mappings which are usually mapped for one DMA
342 Neither type of DMA mapping has alignment restrictions that come from
344 Also, systems with caches that aren't DMA-coherent will work better
348 Using Consistent DMA mappings
351 To allocate and map large (PAGE_SIZE or so) consistent DMA regions,
368 The consistent DMA mapping interfaces, will by default return a DMA address
369 which is 32-bit addressable.  Even if the device indicates (via the DMA mask)
371 return > 32-bit addresses for DMA if the consistent DMA mask has been
379 The CPU virtual address and the DMA address are both
386 To unmap and free such a DMA region, you call::
415 Allocate memory from a DMA pool like this::
439 DMA Direction
443 take a DMA direction argument, which is an integer and takes on
451 You should provide the exact DMA direction if you know it.
455 It is the direction in which the data moves during the DMA
461 If you absolutely cannot know the direction of the DMA transfer,
462 specify DMA_BIDIRECTIONAL.  It means that the DMA can go in
474 Some platforms actually have a write permission boolean which DMA
477 kernel logs when the DMA controller hardware detects violation of the
493 Using Streaming DMA mappings
496 The streaming DMA mapping routines can be called from interrupt
511 		 * reduce current DMA mapping usage,
524 DMA implementations without any dependency on the specifics of the underlying
529 You should call dma_unmap_single() when the DMA activity is finished, e.g.,
530 from the interrupt which told you that the DMA transfer is done.
547 		 * reduce current DMA mapping usage,
563 You should call dma_unmap_page() when the DMA activity is finished, e.g.,
564 from the interrupt which told you that the DMA transfer is done.
579 into one (e.g. if DMA mapping is done with PAGE_SIZE granularity, any
594 Again, make sure DMA activity has already finished.
604 counterpart, because the DMA address space is a shared resource and
605 you could render the machine unusable by consuming all DMA addresses.
607 If you need to use the same streaming DMA region multiple times and touch
608 the data in between the DMA transfers, the buffer needs to be synced
610 correct copy of the DMA buffer.
612 So, firstly, just map it with dma_map_{single,sg}(), and after each DMA
623 Then, if you wish to let the device get at the DMA area again,
642 After the last DMA transfer call one of the DMA unmap routines
657 			 * reduce current DMA mapping usage,
683 			 * the DMA transfer with the CPU first
713 dynamic DMA mapping scheme - you have to always store the DMA addresses
716 supports dynamic DMA mapping in hardware) in your driver structures and/or
727 DMA address space is limited on some architectures and an allocation
740 		 * reduce current DMA mapping usage,
759 		 * reduce current DMA mapping usage,
768 		 * reduce current DMA mapping usage,
799 			 * reduce current DMA mapping usage,
821 and return NETDEV_TX_OK if the DMA mapping fails on the transmit hook
825 SCSI drivers must return SCSI_MLQUEUE_HOST_BUSY if the DMA mapping
901    DMA-safe. Drivers and subsystems depend on it. If an architecture
902    isn't fully DMA-coherent (i.e. hardware doesn't ensure that data in
908    Note that ARCH_DMA_MINALIGN is about DMA memory alignment