Lines Matching +full:dma +full:- +full:safe +full:- +full:map
2 Dynamic DMA mapping Guide
9 This is a guide to device driver writers on how to use the DMA API
10 with example pseudo-code. For a concise description of the API, see
11 Documentation/core-api/dma-api.rst.
13 CPU and DMA addresses
16 There are several kinds of addresses involved in the DMA API, and it's
27 address is not directly useful to a driver; it must use ioremap() to map
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
39 supports 64-bit addresses for main memory and PCI BARs, it may use an IOMMU
40 so devices only need to use 32-bit DMA addresses.
49 +-------+ +------+ +------+
52 C +-------+ --------> B +------+ ----------> +------+ A
54 +-----+ | | | | bridge | | +--------+
55 | | | | +------+ | | | |
58 +-----+ +-------+ +------+ +------+ +--------+
60 X +-------+ --------> Y +------+ <---------- +------+ Z
64 +-------+ +------+
71 driver claims a device, it typically uses ioremap() to map physical address
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
105 #include <linux/dma-mapping.h>
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
137 buffers were cacheline-aligned. Without that, you'd see cacheline
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
153 addressing. For a 64-bit capable device, this needs to be increased, and for
156 Special note about PCI: PCI-X specification requires PCI-X devices to support
157 64-bit addressing (DAC) for all transactions. And at least one platform (SGI
158 SN2) requires 64-bit consistent allocations to operate correctly when the IO
159 bus is in PCI-X mode.
161 For correct operation, you must set the DMA mask to inform the kernel about
162 your devices DMA addressing capabilities.
184 device struct of your device is embedded in the bus-specific device struct of
185 your device. For example, &pdev->dev is a pointer to the device struct of a
188 These calls usually return zero to indicate 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
206 The 24-bit addressing device would do something like this::
209 dev_warn(dev, "mydev: No suitable DMA available\n");
213 The standard 64-bit addressing device would do something like this::
233 If the device only supports 32-bit addressing for descriptors in the
234 coherent allocations, but supports full 64-bits for streaming mappings
238 dev_warn(dev, "mydev: No suitable DMA available\n");
247 Finally, if your device can only drive the low 24-bits of
251 dev_warn(dev, "mydev: 24-bit DMA addressing not available\n");
257 kernel will use this information later when you make DMA mappings.
263 DMA addressing limitations, you may wish to probe each mask and
268 Here is pseudo-code showing how this might be done::
278 card->playback_enabled = 1;
280 card->playback_enabled = 0;
281 dev_warn(dev, "%s: Playback disabled due to DMA limitations\n",
282 card->name);
285 card->record_enabled = 1;
287 card->record_enabled = 0;
288 dev_warn(dev, "%s: Record disabled due to DMA limitations\n",
289 card->name);
294 and thus retaining the 16MB DMA addressing limitations of ISA.
296 Types of DMA mappings
299 There are two types of DMA mappings:
301 - Consistent DMA mappings which are usually mapped at driver
310 bits of the DMA space. However, for future compatibility you should
316 - Network card DMA ring descriptors.
317 - SCSI adapter mailbox command data structures.
318 - Device firmware microcode executed out of
327 Consistent DMA memory does not preclude the usage of
334 desc->word0 = address;
336 desc->word1 = DESC_VALID;
345 - Streaming DMA mappings which are usually mapped for one DMA
354 - Networking buffers transmitted/received by a device.
355 - Filesystem buffers written/read by a SCSI device.
362 Neither type of DMA mapping has alignment restrictions that come from
364 Also, systems with caches that aren't DMA-coherent will work better
368 Using Consistent DMA mappings
371 To allocate and map large (PAGE_SIZE or so) consistent DMA regions,
388 The consistent DMA mapping interfaces, will by default return a DMA address
389 which is 32-bit addressable. Even if the device indicates (via the DMA mask)
390 that it may address the upper 32-bits, consistent allocation will only
391 return > 32-bit addresses for DMA if the consistent DMA mask has been
399 The CPU virtual address and the DMA address are both
406 To unmap and free such a DMA region, you call::
435 Allocate memory from a DMA pool like this::
459 DMA Direction
463 take a DMA direction argument, which is an integer and takes on
471 You should provide the exact DMA direction if you know it.
475 It is the direction in which the data moves during the DMA
481 If you absolutely cannot know the direction of the DMA transfer,
482 specify DMA_BIDIRECTIONAL. It means that the DMA can go in
493 potential platform-specific optimizations of such) is for debugging.
494 Some platforms actually have a write permission boolean which DMA
497 kernel logs when the DMA controller hardware detects violation of the
509 packets, map/unmap them with the DMA_TO_DEVICE direction
510 specifier. For receive packets, just the opposite, map/unmap them
513 Using Streaming DMA mappings
516 The streaming DMA mapping routines can be called from interrupt
517 context. There are two versions of each map/unmap, one which will
518 map/unmap a single memory region, and one which will map/unmap a
521 To map a single region, you do::
523 struct device *dev = &my_dev->dev;
525 void *addr = buffer->ptr;
526 size_t size = buffer->len;
531 * reduce current DMA mapping usage,
544 DMA implementations without any dependency on the specifics of the underlying
549 You should call dma_unmap_single() when the DMA activity is finished, e.g.,
550 from the interrupt which told you that the DMA transfer is done.
554 map/unmap interface pair akin to dma_{map,unmap}_single(). These
558 struct device *dev = &my_dev->dev;
560 struct page *page = buffer->page;
561 unsigned long offset = buffer->offset;
562 size_t size = buffer->len;
567 * reduce current DMA mapping usage,
583 You should call dma_unmap_page() when the DMA activity is finished, e.g.,
584 from the interrupt which told you that the DMA transfer is done.
586 With scatterlists, you map a region gathered from several regions by::
599 into one (e.g. if DMA mapping is done with PAGE_SIZE granularity, any
601 ends and the second one starts on a page boundary - in fact this is a huge
602 advantage for cards which either cannot do scatter-gather or have very
603 limited number of scatter-gather entries) and returns the actual number
608 accessed sg->address and sg->length as shown above.
614 Again, make sure DMA activity has already finished.
624 counterpart, because the DMA address space is a shared resource and
625 you could render the machine unusable by consuming all DMA addresses.
627 If you need to use the same streaming DMA region multiple times and touch
628 the data in between the DMA transfers, the buffer needs to be synced
629 properly in order for the CPU and device to see the most up-to-date and
630 correct copy of the DMA buffer.
632 So, firstly, just map it with dma_map_{single,sg}(), and after each DMA
643 Then, if you wish to let the device get at the DMA area again,
662 After the last DMA transfer call one of the DMA unmap routines
674 mapping = dma_map_single(cp->dev, buffer, len, DMA_FROM_DEVICE);
675 if (dma_mapping_error(cp->dev, mapping)) {
677 * reduce current DMA mapping usage,
684 cp->rx_buf = buffer;
685 cp->rx_len = len;
686 cp->rx_dma = mapping;
703 * the DMA transfer with the CPU first
706 dma_sync_single_for_cpu(&cp->dev, cp->rx_dma,
707 cp->rx_len,
710 /* Now it is safe to examine the buffer. */
711 hp = (struct my_card_header *) cp->rx_buf;
713 dma_unmap_single(&cp->dev, cp->rx_dma, cp->rx_len,
715 pass_to_upper_layers(cp->rx_buf);
719 * DMA_FROM_DEVICE-mapped area,
733 DMA address space is limited on some architectures and an allocation
736 - checking if dma_alloc_coherent() returns NULL or dma_map_sg returns 0
738 - checking the dma_addr_t returned from dma_map_single() and dma_map_page()
746 * reduce current DMA mapping usage,
753 - unmap pages that are already mapped, when mapping error occurs in the middle
765 * reduce current DMA mapping usage,
774 * reduce current DMA mapping usage,
805 * reduce current DMA mapping usage,
827 and return NETDEV_TX_OK if the DMA mapping fails on the transmit hook
831 SCSI drivers must return SCSI_MLQUEUE_HOST_BUSY if the DMA mapping
867 ringp->mapping = FOO;
868 ringp->len = BAR;
878 dma_unmap_single(dev, ringp->mapping, ringp->len,
888 It really should be self-explanatory. We treat the ADDR and LEN
907 DMA-safe. Drivers and subsystems depend on it. If an architecture
908 isn't fully DMA-coherent (i.e. hardware doesn't ensure that data in
914 Note that ARCH_DMA_MINALIGN is about DMA memory alignment
916 alignment constraints (e.g. the alignment constraints about 64-bit
935 David Mosberger-Tang <davidm@hpl.hp.com>