Lines Matching refs:the
1 Dynamic DMA mapping using the generic device
6 This document describes the DMA API. For a more gentle introduction
7 of the API (and actual examples), see Documentation/DMA-API-HOWTO.txt.
9 This API is split into two pieces. Part I describes the basic API.
13 should only use the API described in part I.
18 To get the dma_ API, you must #include <linux/dma-mapping.h>. This
19 provides dma_addr_t and the interfaces described below.
21 A dma_addr_t can hold any valid DMA address for the platform. It can be
24 address space and the DMA address space.
33 Consistent memory is memory for which a write by either the device or
34 the processor can immediately be read by the processor or device
36 to make sure to flush the processor's write buffers before telling
41 It returns a pointer to the allocated region (in the processor's virtual
42 address space) or NULL if the allocation failed.
44 It also returns a <dma_handle> which may be cast to an unsigned integer the
45 same width as the bus and given to the device as the DMA address base of
46 the region.
48 Note: consistent memory can be expensive on some platforms, and the
51 The simplest way to do that is to use the dma_pool calls (see below).
53 The flag parameter (dma_alloc_coherent() only) allows the caller to
54 specify the GFP_ flags (see kmalloc()) for the allocation (the
55 implementation may choose to ignore flags that affect the location of
56 the returned memory, like GFP_DMA).
62 Wraps dma_alloc_coherent() and also zeroes the returned memory if the
70 size and dma_handle must all be the same as those passed into
71 dma_alloc_coherent(). cpu_addr must be the virtual address returned by
72 the dma_alloc_coherent().
81 To get this part of the dma_ API, you must #include <linux/dmapool.h>
86 much like a struct kmem_cache, except that they use the DMA-coherent allocator,
110 This allocates memory from the pool; the returned memory will meet the
115 address usable by the CPU, and the DMA address usable by the pool's
122 This puts memory back into the pool. The pool is what was passed to
123 dma_pool_alloc(); the CPU (vaddr) and DMA addresses are what
124 were returned when that routine allocated the memory being freed.
129 dma_pool_destroy() frees the resources of the pool. It must be
131 memory back to the pool before you destroy it.
140 Checks to see if the device can support DMA to the memory described by
145 Notes: This routine merely tests to see if the mask is possible. It
146 won't change the current mask settings. It is more intended as an
147 internal API for use by the platform than an external API for use by
153 Checks to see if the mask is possible and updates the device
161 Checks to see if the mask is possible and updates the device
169 Checks to see if the mask is possible and updates the device
177 This API returns the mask that the platform requires to
178 operate efficiently. Usually this means the returned mask
179 is the minimum required to cover all of memory. Examining the
180 required mask gives drivers with variable descriptor sizes the
183 Requesting the required mask does not alter the current mask. If you
185 call to set the mask to the value returned.
195 Maps a piece of processor virtual memory so it can be accessed by the
196 device and returns the DMA address of the memory.
199 However the dma_ API uses a strongly typed enumerator for its
203 DMA_TO_DEVICE data is going from the memory to the device
204 DMA_FROM_DEVICE data is coming from the device to the memory
210 capability, it will fail if the user tries to map a non-physically
215 Further, the DMA address of the memory must be within the
216 dma_mask of the device (the dma_mask is a bit mask of the
217 addressable region for the device, i.e., if the DMA address of
218 the memory ANDed with the dma_mask is still equal to the DMA
219 address, then the device can perform DMA to the memory). To
220 ensure that the memory allocated by kmalloc is within the dma_mask,
221 the driver may specify various platform-dependent flags to restrict
222 the DMA address range of the allocation (e.g., on x86, GFP_DMA
223 guarantees to be within the first 16MB of available DMA addresses,
226 Note also that the above constraints on physical contiguity and
227 dma_mask may not apply if the platform has an IOMMU (a device which
232 Warnings: Memory coherency operates at a granularity called the cache
234 correctly, the mapped region must begin exactly on a cache line
236 regions from sharing a single cache line). Since the cache line size
237 may not be known at compile time, the API will not enforce this
239 don't take special care to determine the cache line size at run time
243 DMA_TO_DEVICE synchronisation must be done after the last modification
244 of the memory region by the software and before it is handed off to
245 the driver. Once this primitive is used, memory covered by this
246 primitive should be treated as read-only by the device. If the device
250 DMA_FROM_DEVICE synchronisation must be done before the driver
251 accesses data that may be changed by the device. This memory should
252 be treated as read-only by the driver. If the driver needs to write
255 DMA_BIDIRECTIONAL requires special handling: it means that the driver
256 isn't sure if the memory was modified before being handed off to the
257 device and also isn't sure if the device will also modify it. Thus,
258 you must always sync bidirectional memory twice: once before the
259 memory is handed off to the device (to make sure all memory changes
260 are flushed from the processor) and once before the data may be
261 accessed after being used by the device (to make sure any processor
262 cache lines are updated with data that the device may have changed).
268 Unmaps the region previously mapped. All the parameters passed in
269 must be identical to those passed in (and returned) by the mapping
280 API for mapping and unmapping for pages. All the notes and warnings
281 for the other mapping APIs apply here. Also, although the <offset>
283 recommended that you never use these unless you really know what the
290 a mapping. A driver can check for these errors by testing the returned
291 DMA address with dma_mapping_error(). A non-zero return value means the mapping
292 could not be created and the driver should take appropriate action (e.g.
299 Returns: the number of DMA address segments mapped (this may be shorter
300 than <nents> passed in if some elements of the scatter/gather list are
304 Please note that the sg cannot be mapped again if it has been mapped once.
305 The mapping process is allowed to destroy information in the sg.
307 As with the other mapping interfaces, dma_map_sg() can fail. When it
309 critical that the driver do something, in the case of a block driver
310 aborting the request or even oopsing is better than doing nothing and
311 corrupting the filesystem.
313 With scatterlists, you use the resulting mapping like this:
323 where nents is the number of entries in the sglist.
327 physically contiguous) and returns the actual number of sg entries it
338 Unmap the previously mapped scatter/gather list. All the parameters
339 must be the same as those and passed in to the scatter/gather mapping
342 Note: <nents> must be the number you passed in, *not* the number of
358 Synchronise a single contiguous or scatter/gather mapping for the CPU
359 and device. With the sync_sg API, all the parameters must be the same
360 as those passed into the single mapping API. With the sync_single API,
362 those passed into the single mapping API to do a partial sync.
366 - Before reading values that have been written by DMA from the device
367 (use the DMA_FROM_DEVICE direction)
368 - After writing values that will be written to the device using DMA
369 (use the DMA_TO_DEVICE) direction
370 - before *and* after handing memory to the device if the memory is
395 The four functions above are just like the counterpart functions
396 without the _attrs suffixes, except that they pass an optional
399 struct dma_attrs encapsulates a set of "DMA attributes". For the
405 If struct dma_attrs* is NULL, the semantics of each of these
406 functions is identical to those of the corresponding function
407 without the _attrs suffix. As a result dma_map_single_attrs()
410 As an example of the use of the *_attrs functions, here's how
426 presence in their implementations of the mapping and unmapping
437 /* twizzle the frobnozzle */
444 Warning: These pieces of the DMA API should not be used in the
449 processor and an I/O device, you should not be using this part of the
456 Identical to dma_alloc_coherent() except that the platform will
458 fit. By using this API, you are guaranteeing to the platform that you
459 have all the correct and necessary sync points for this memory in the
462 Note: where the platform can return consistent memory, it will
463 guarantee that the sync points become nops.
467 required to work on one of the rare (usually non-PCI) architectures
474 Free memory allocated by the nonconsistent API. All parameters must
481 Returns the processor cache alignment. This is the absolute minimum
485 Notes: This API may return a number *larger* than the actual cache
487 into the width returned by this call. It will also always be a power
496 continuing on for size. Again, you *must* observe the cache line
507 phys_addr is the CPU physical address to which the memory is currently
508 assigned (this will be ioremapped so the CPU can access the region).
510 device_addr is the DMA address the device needs to be programmed
511 with to actually address this memory (this will be handed out as the
514 size is the size of the area (must be multiples of PAGE_SIZE).
518 DMA_MEMORY_MAP - request that the memory returned from
521 DMA_MEMORY_IO - request that the memory returned from
526 DMA_MEMORY_INCLUDES_CHILDREN - make the declared memory be allocated by
530 DMA_MEMORY_EXCLUSIVE - only allocate memory from the declared regions.
532 it's out of memory in the declared region.
541 must be accessed using the correct bus functions. If your driver
543 DMA_MEMORY_IO in the input flags.
545 As a simplification for the platforms, only *one* such region of
548 For reasons of efficiency, most platforms choose to track the declared
549 region only at the granularity of a page. For smaller allocations,
550 you should use the dma_pool() API.
555 Remove the memory region previously declared from the system. This
557 unconditionally having removed all the required structures. It is the
565 This is used to occupy specific regions of the declared space
566 (dma_alloc_coherent() will hand out the first free region it finds).
568 device_addr is the *device* address of the region requested.
570 size is the size (and should be a page-sized multiple).
572 The return value will be either a pointer to the processor virtual
573 address of the memory, or an error (via PTR_ERR()) if any part of the
576 Part III - Debug drivers use of the DMA-API
580 released with the corresponding function with the same size for example. With
581 the advent of hardware IOMMUs it becomes more and more important that drivers
582 do not violate those constraints. In the worst case such a violation can
585 To debug drivers and find bugs in the usage of the DMA-API checking code can
586 be compiled into the kernel which will tell the developer about those
587 violations. If your architecture supports it you can select the "Enable
591 If you boot the resulting kernel will contain code which does some bookkeeping
627 The driver developer can find the driver and the device including a stacktrace
628 of the DMA-API call which caused this warning.
630 Per default only the first error will result in a warning message. All other
631 errors will only silently counted. This limitation exist to prevent the code
633 be disabled via debugfs. See the debugfs interface documentation below for
636 The debugfs directory for the DMA-API debugging code is called dma-api/. In
637 this directory the following files can currently be found:
640 value is not equal to zero the debugging code
642 into the kernel log. Be careful with this
645 dma-api/disabled This read-only file contains the character 'Y'
646 if the debugging code is disabled. This can
650 dma-api/error_count This file is read-only and shows the total
654 warnings will be printed to the kernel log
660 This read-only file can be read to get the
661 minimum number of free dma_debug_entries the
663 down to zero the code will disable itself
668 in the allocator.
672 to limit the debug output to requests from that
674 that file to disable the filter and see
678 If you want to boot without the bookkeeping anyway you can provide
684 specify the dma_debug_driver=<drivername> parameter. This will enable the
688 When the code disables itself at runtime this is most likely because it ran
691 boot with 'dma_debug_entries=<your_desired_number>' to overwrite the
700 the driver. When driver does unmap, debug_dma_unmap() checks the flag and if
702 leads up to the unmap. This interface can be called from dma_mapping_error()