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 Wraps dma_pool_alloc() and also zeroes the returned memory if the
117 This allocates memory from the pool; the returned memory will meet the
122 address usable by the CPU, and the DMA address usable by the pool's
129 This puts memory back into the pool. The pool is what was passed to
130 dma_pool_alloc(); the CPU (vaddr) and DMA addresses are what
131 were returned when that routine allocated the memory being freed.
136 dma_pool_destroy() frees the resources of the pool. It must be
138 memory back to the pool before you destroy it.
147 Checks to see if the mask is possible and updates the device
155 Checks to see if the mask is possible and updates the device
163 Checks to see if the mask is possible and updates the device
171 This API returns the mask that the platform requires to
172 operate efficiently. Usually this means the returned mask
173 is the minimum required to cover all of memory. Examining the
174 required mask gives drivers with variable descriptor sizes the
177 Requesting the required mask does not alter the current mask. If you
179 call to set the mask to the value returned.
189 Maps a piece of processor virtual memory so it can be accessed by the
190 device and returns the DMA address of the memory.
193 However the dma_ API uses a strongly typed enumerator for its
197 DMA_TO_DEVICE data is going from the memory to the device
198 DMA_FROM_DEVICE data is coming from the device to the memory
204 capability, it will fail if the user tries to map a non-physically
209 Further, the DMA address of the memory must be within the
210 dma_mask of the device (the dma_mask is a bit mask of the
211 addressable region for the device, i.e., if the DMA address of
212 the memory ANDed with the dma_mask is still equal to the DMA
213 address, then the device can perform DMA to the memory). To
214 ensure that the memory allocated by kmalloc is within the dma_mask,
215 the driver may specify various platform-dependent flags to restrict
216 the DMA address range of the allocation (e.g., on x86, GFP_DMA
217 guarantees to be within the first 16MB of available DMA addresses,
220 Note also that the above constraints on physical contiguity and
221 dma_mask may not apply if the platform has an IOMMU (a device which
226 Warnings: Memory coherency operates at a granularity called the cache
228 correctly, the mapped region must begin exactly on a cache line
230 regions from sharing a single cache line). Since the cache line size
231 may not be known at compile time, the API will not enforce this
233 don't take special care to determine the cache line size at run time
237 DMA_TO_DEVICE synchronisation must be done after the last modification
238 of the memory region by the software and before it is handed off to
239 the driver. Once this primitive is used, memory covered by this
240 primitive should be treated as read-only by the device. If the device
244 DMA_FROM_DEVICE synchronisation must be done before the driver
245 accesses data that may be changed by the device. This memory should
246 be treated as read-only by the driver. If the driver needs to write
249 DMA_BIDIRECTIONAL requires special handling: it means that the driver
250 isn't sure if the memory was modified before being handed off to the
251 device and also isn't sure if the device will also modify it. Thus,
252 you must always sync bidirectional memory twice: once before the
253 memory is handed off to the device (to make sure all memory changes
254 are flushed from the processor) and once before the data may be
255 accessed after being used by the device (to make sure any processor
256 cache lines are updated with data that the device may have changed).
262 Unmaps the region previously mapped. All the parameters passed in
263 must be identical to those passed in (and returned) by the mapping
274 API for mapping and unmapping for pages. All the notes and warnings
275 for the other mapping APIs apply here. Also, although the <offset>
277 recommended that you never use these unless you really know what the
284 a mapping. A driver can check for these errors by testing the returned
285 DMA address with dma_mapping_error(). A non-zero return value means the mapping
286 could not be created and the driver should take appropriate action (e.g.
293 Returns: the number of DMA address segments mapped (this may be shorter
294 than <nents> passed in if some elements of the scatter/gather list are
298 Please note that the sg cannot be mapped again if it has been mapped once.
299 The mapping process is allowed to destroy information in the sg.
301 As with the other mapping interfaces, dma_map_sg() can fail. When it
303 critical that the driver do something, in the case of a block driver
304 aborting the request or even oopsing is better than doing nothing and
305 corrupting the filesystem.
307 With scatterlists, you use the resulting mapping like this:
317 where nents is the number of entries in the sglist.
321 physically contiguous) and returns the actual number of sg entries it
332 Unmap the previously mapped scatter/gather list. All the parameters
333 must be the same as those and passed in to the scatter/gather mapping
336 Note: <nents> must be the number you passed in, *not* the number of
352 Synchronise a single contiguous or scatter/gather mapping for the CPU
353 and device. With the sync_sg API, all the parameters must be the same
354 as those passed into the single mapping API. With the sync_single API,
356 those passed into the single mapping API to do a partial sync.
360 - Before reading values that have been written by DMA from the device
361 (use the DMA_FROM_DEVICE direction)
362 - After writing values that will be written to the device using DMA
363 (use the DMA_TO_DEVICE) direction
364 - before *and* after handing memory to the device if the memory is
389 The four functions above are just like the counterpart functions
390 without the _attrs suffixes, except that they pass an optional
393 struct dma_attrs encapsulates a set of "DMA attributes". For the
399 If struct dma_attrs* is NULL, the semantics of each of these
400 functions is identical to those of the corresponding function
401 without the _attrs suffix. As a result dma_map_single_attrs()
404 As an example of the use of the *_attrs functions, here's how
420 presence in their implementations of the mapping and unmapping
431 /* twizzle the frobnozzle */
438 Warning: These pieces of the DMA API should not be used in the
443 processor and an I/O device, you should not be using this part of the
450 Identical to dma_alloc_coherent() except that the platform will
452 fit. By using this API, you are guaranteeing to the platform that you
453 have all the correct and necessary sync points for this memory in the
456 Note: where the platform can return consistent memory, it will
457 guarantee that the sync points become nops.
461 required to work on one of the rare (usually non-PCI) architectures
468 Free memory allocated by the nonconsistent API. All parameters must
475 Returns the processor cache alignment. This is the absolute minimum
479 Notes: This API may return a number *larger* than the actual cache
481 into the width returned by this call. It will also always be a power
490 continuing on for size. Again, you *must* observe the cache line
501 phys_addr is the CPU physical address to which the memory is currently
502 assigned (this will be ioremapped so the CPU can access the region).
504 device_addr is the DMA address the device needs to be programmed
505 with to actually address this memory (this will be handed out as the
508 size is the size of the area (must be multiples of PAGE_SIZE).
512 DMA_MEMORY_MAP - request that the memory returned from
515 DMA_MEMORY_IO - request that the memory returned from
520 DMA_MEMORY_INCLUDES_CHILDREN - make the declared memory be allocated by
524 DMA_MEMORY_EXCLUSIVE - only allocate memory from the declared regions.
526 it's out of memory in the declared region.
535 must be accessed using the correct bus functions. If your driver
537 DMA_MEMORY_IO in the input flags.
539 As a simplification for the platforms, only *one* such region of
542 For reasons of efficiency, most platforms choose to track the declared
543 region only at the granularity of a page. For smaller allocations,
544 you should use the dma_pool() API.
549 Remove the memory region previously declared from the system. This
551 unconditionally having removed all the required structures. It is the
559 This is used to occupy specific regions of the declared space
560 (dma_alloc_coherent() will hand out the first free region it finds).
562 device_addr is the *device* address of the region requested.
564 size is the size (and should be a page-sized multiple).
566 The return value will be either a pointer to the processor virtual
567 address of the memory, or an error (via PTR_ERR()) if any part of the
570 Part III - Debug drivers use of the DMA-API
574 released with the corresponding function with the same size for example. With
575 the advent of hardware IOMMUs it becomes more and more important that drivers
576 do not violate those constraints. In the worst case such a violation can
579 To debug drivers and find bugs in the usage of the DMA-API checking code can
580 be compiled into the kernel which will tell the developer about those
581 violations. If your architecture supports it you can select the "Enable
585 If you boot the resulting kernel will contain code which does some bookkeeping
621 The driver developer can find the driver and the device including a stacktrace
622 of the DMA-API call which caused this warning.
624 Per default only the first error will result in a warning message. All other
625 errors will only silently counted. This limitation exist to prevent the code
627 be disabled via debugfs. See the debugfs interface documentation below for
630 The debugfs directory for the DMA-API debugging code is called dma-api/. In
631 this directory the following files can currently be found:
634 value is not equal to zero the debugging code
636 into the kernel log. Be careful with this
639 dma-api/disabled This read-only file contains the character 'Y'
640 if the debugging code is disabled. This can
644 dma-api/error_count This file is read-only and shows the total
648 warnings will be printed to the kernel log
654 This read-only file can be read to get the
655 minimum number of free dma_debug_entries the
657 down to zero the code will disable itself
662 in the allocator.
666 to limit the debug output to requests from that
668 that file to disable the filter and see
672 If you want to boot without the bookkeeping anyway you can provide
678 specify the dma_debug_driver=<drivername> parameter. This will enable the
682 When the code disables itself at runtime this is most likely because it ran
685 boot with 'dma_debug_entries=<your_desired_number>' to overwrite the
694 the driver. When driver does unmap, debug_dma_unmap() checks the flag and if
696 leads up to the unmap. This interface can be called from dma_mapping_error()