Back to home page

LXR

 
 

    


0001                Dynamic DMA mapping using the generic device
0002                ============================================
0003 
0004         James E.J. Bottomley <James.Bottomley@HansenPartnership.com>
0005 
0006 This document describes the DMA API.  For a more gentle introduction
0007 of the API (and actual examples), see Documentation/DMA-API-HOWTO.txt.
0008 
0009 This API is split into two pieces.  Part I describes the basic API.
0010 Part II describes extensions for supporting non-consistent memory
0011 machines.  Unless you know that your driver absolutely has to support
0012 non-consistent platforms (this is usually only legacy platforms) you
0013 should only use the API described in part I.
0014 
0015 Part I - dma_ API
0016 -------------------------------------
0017 
0018 To get the dma_ API, you must #include <linux/dma-mapping.h>.  This
0019 provides dma_addr_t and the interfaces described below.
0020 
0021 A dma_addr_t can hold any valid DMA address for the platform.  It can be
0022 given to a device to use as a DMA source or target.  A CPU cannot reference
0023 a dma_addr_t directly because there may be translation between its physical
0024 address space and the DMA address space.
0025 
0026 Part Ia - Using large DMA-coherent buffers
0027 ------------------------------------------
0028 
0029 void *
0030 dma_alloc_coherent(struct device *dev, size_t size,
0031                              dma_addr_t *dma_handle, gfp_t flag)
0032 
0033 Consistent memory is memory for which a write by either the device or
0034 the processor can immediately be read by the processor or device
0035 without having to worry about caching effects.  (You may however need
0036 to make sure to flush the processor's write buffers before telling
0037 devices to read that memory.)
0038 
0039 This routine allocates a region of <size> bytes of consistent memory.
0040 
0041 It returns a pointer to the allocated region (in the processor's virtual
0042 address space) or NULL if the allocation failed.
0043 
0044 It also returns a <dma_handle> which may be cast to an unsigned integer the
0045 same width as the bus and given to the device as the DMA address base of
0046 the region.
0047 
0048 Note: consistent memory can be expensive on some platforms, and the
0049 minimum allocation length may be as big as a page, so you should
0050 consolidate your requests for consistent memory as much as possible.
0051 The simplest way to do that is to use the dma_pool calls (see below).
0052 
0053 The flag parameter (dma_alloc_coherent() only) allows the caller to
0054 specify the GFP_ flags (see kmalloc()) for the allocation (the
0055 implementation may choose to ignore flags that affect the location of
0056 the returned memory, like GFP_DMA).
0057 
0058 void *
0059 dma_zalloc_coherent(struct device *dev, size_t size,
0060                              dma_addr_t *dma_handle, gfp_t flag)
0061 
0062 Wraps dma_alloc_coherent() and also zeroes the returned memory if the
0063 allocation attempt succeeded.
0064 
0065 void
0066 dma_free_coherent(struct device *dev, size_t size, void *cpu_addr,
0067                            dma_addr_t dma_handle)
0068 
0069 Free a region of consistent memory you previously allocated.  dev,
0070 size and dma_handle must all be the same as those passed into
0071 dma_alloc_coherent().  cpu_addr must be the virtual address returned by
0072 the dma_alloc_coherent().
0073 
0074 Note that unlike their sibling allocation calls, these routines
0075 may only be called with IRQs enabled.
0076 
0077 
0078 Part Ib - Using small DMA-coherent buffers
0079 ------------------------------------------
0080 
0081 To get this part of the dma_ API, you must #include <linux/dmapool.h>
0082 
0083 Many drivers need lots of small DMA-coherent memory regions for DMA
0084 descriptors or I/O buffers.  Rather than allocating in units of a page
0085 or more using dma_alloc_coherent(), you can use DMA pools.  These work
0086 much like a struct kmem_cache, except that they use the DMA-coherent allocator,
0087 not __get_free_pages().  Also, they understand common hardware constraints
0088 for alignment, like queue heads needing to be aligned on N-byte boundaries.
0089 
0090 
0091         struct dma_pool *
0092         dma_pool_create(const char *name, struct device *dev,
0093                         size_t size, size_t align, size_t alloc);
0094 
0095 dma_pool_create() initializes a pool of DMA-coherent buffers
0096 for use with a given device.  It must be called in a context which
0097 can sleep.
0098 
0099 The "name" is for diagnostics (like a struct kmem_cache name); dev and size
0100 are like what you'd pass to dma_alloc_coherent().  The device's hardware
0101 alignment requirement for this type of data is "align" (which is expressed
0102 in bytes, and must be a power of two).  If your device has no boundary
0103 crossing restrictions, pass 0 for alloc; passing 4096 says memory allocated
0104 from this pool must not cross 4KByte boundaries.
0105 
0106 
0107         void *dma_pool_zalloc(struct dma_pool *pool, gfp_t mem_flags,
0108                               dma_addr_t *handle)
0109 
0110 Wraps dma_pool_alloc() and also zeroes the returned memory if the
0111 allocation attempt succeeded.
0112 
0113 
0114         void *dma_pool_alloc(struct dma_pool *pool, gfp_t gfp_flags,
0115                         dma_addr_t *dma_handle);
0116 
0117 This allocates memory from the pool; the returned memory will meet the
0118 size and alignment requirements specified at creation time.  Pass
0119 GFP_ATOMIC to prevent blocking, or if it's permitted (not
0120 in_interrupt, not holding SMP locks), pass GFP_KERNEL to allow
0121 blocking.  Like dma_alloc_coherent(), this returns two values:  an
0122 address usable by the CPU, and the DMA address usable by the pool's
0123 device.
0124 
0125 
0126         void dma_pool_free(struct dma_pool *pool, void *vaddr,
0127                         dma_addr_t addr);
0128 
0129 This puts memory back into the pool.  The pool is what was passed to
0130 dma_pool_alloc(); the CPU (vaddr) and DMA addresses are what
0131 were returned when that routine allocated the memory being freed.
0132 
0133 
0134         void dma_pool_destroy(struct dma_pool *pool);
0135 
0136 dma_pool_destroy() frees the resources of the pool.  It must be
0137 called in a context which can sleep.  Make sure you've freed all allocated
0138 memory back to the pool before you destroy it.
0139 
0140 
0141 Part Ic - DMA addressing limitations
0142 ------------------------------------
0143 
0144 int
0145 dma_set_mask_and_coherent(struct device *dev, u64 mask)
0146 
0147 Checks to see if the mask is possible and updates the device
0148 streaming and coherent DMA mask parameters if it is.
0149 
0150 Returns: 0 if successful and a negative error if not.
0151 
0152 int
0153 dma_set_mask(struct device *dev, u64 mask)
0154 
0155 Checks to see if the mask is possible and updates the device
0156 parameters if it is.
0157 
0158 Returns: 0 if successful and a negative error if not.
0159 
0160 int
0161 dma_set_coherent_mask(struct device *dev, u64 mask)
0162 
0163 Checks to see if the mask is possible and updates the device
0164 parameters if it is.
0165 
0166 Returns: 0 if successful and a negative error if not.
0167 
0168 u64
0169 dma_get_required_mask(struct device *dev)
0170 
0171 This API returns the mask that the platform requires to
0172 operate efficiently.  Usually this means the returned mask
0173 is the minimum required to cover all of memory.  Examining the
0174 required mask gives drivers with variable descriptor sizes the
0175 opportunity to use smaller descriptors as necessary.
0176 
0177 Requesting the required mask does not alter the current mask.  If you
0178 wish to take advantage of it, you should issue a dma_set_mask()
0179 call to set the mask to the value returned.
0180 
0181 
0182 Part Id - Streaming DMA mappings
0183 --------------------------------
0184 
0185 dma_addr_t
0186 dma_map_single(struct device *dev, void *cpu_addr, size_t size,
0187                       enum dma_data_direction direction)
0188 
0189 Maps a piece of processor virtual memory so it can be accessed by the
0190 device and returns the DMA address of the memory.
0191 
0192 The direction for both APIs may be converted freely by casting.
0193 However the dma_ API uses a strongly typed enumerator for its
0194 direction:
0195 
0196 DMA_NONE                no direction (used for debugging)
0197 DMA_TO_DEVICE           data is going from the memory to the device
0198 DMA_FROM_DEVICE         data is coming from the device to the memory
0199 DMA_BIDIRECTIONAL       direction isn't known
0200 
0201 Notes:  Not all memory regions in a machine can be mapped by this API.
0202 Further, contiguous kernel virtual space may not be contiguous as
0203 physical memory.  Since this API does not provide any scatter/gather
0204 capability, it will fail if the user tries to map a non-physically
0205 contiguous piece of memory.  For this reason, memory to be mapped by
0206 this API should be obtained from sources which guarantee it to be
0207 physically contiguous (like kmalloc).
0208 
0209 Further, the DMA address of the memory must be within the
0210 dma_mask of the device (the dma_mask is a bit mask of the
0211 addressable region for the device, i.e., if the DMA address of
0212 the memory ANDed with the dma_mask is still equal to the DMA
0213 address, then the device can perform DMA to the memory).  To
0214 ensure that the memory allocated by kmalloc is within the dma_mask,
0215 the driver may specify various platform-dependent flags to restrict
0216 the DMA address range of the allocation (e.g., on x86, GFP_DMA
0217 guarantees to be within the first 16MB of available DMA addresses,
0218 as required by ISA devices).
0219 
0220 Note also that the above constraints on physical contiguity and
0221 dma_mask may not apply if the platform has an IOMMU (a device which
0222 maps an I/O DMA address to a physical memory address).  However, to be
0223 portable, device driver writers may *not* assume that such an IOMMU
0224 exists.
0225 
0226 Warnings:  Memory coherency operates at a granularity called the cache
0227 line width.  In order for memory mapped by this API to operate
0228 correctly, the mapped region must begin exactly on a cache line
0229 boundary and end exactly on one (to prevent two separately mapped
0230 regions from sharing a single cache line).  Since the cache line size
0231 may not be known at compile time, the API will not enforce this
0232 requirement.  Therefore, it is recommended that driver writers who
0233 don't take special care to determine the cache line size at run time
0234 only map virtual regions that begin and end on page boundaries (which
0235 are guaranteed also to be cache line boundaries).
0236 
0237 DMA_TO_DEVICE synchronisation must be done after the last modification
0238 of the memory region by the software and before it is handed off to
0239 the device.  Once this primitive is used, memory covered by this
0240 primitive should be treated as read-only by the device.  If the device
0241 may write to it at any point, it should be DMA_BIDIRECTIONAL (see
0242 below).
0243 
0244 DMA_FROM_DEVICE synchronisation must be done before the driver
0245 accesses data that may be changed by the device.  This memory should
0246 be treated as read-only by the driver.  If the driver needs to write
0247 to it at any point, it should be DMA_BIDIRECTIONAL (see below).
0248 
0249 DMA_BIDIRECTIONAL requires special handling: it means that the driver
0250 isn't sure if the memory was modified before being handed off to the
0251 device and also isn't sure if the device will also modify it.  Thus,
0252 you must always sync bidirectional memory twice: once before the
0253 memory is handed off to the device (to make sure all memory changes
0254 are flushed from the processor) and once before the data may be
0255 accessed after being used by the device (to make sure any processor
0256 cache lines are updated with data that the device may have changed).
0257 
0258 void
0259 dma_unmap_single(struct device *dev, dma_addr_t dma_addr, size_t size,
0260                  enum dma_data_direction direction)
0261 
0262 Unmaps the region previously mapped.  All the parameters passed in
0263 must be identical to those passed in (and returned) by the mapping
0264 API.
0265 
0266 dma_addr_t
0267 dma_map_page(struct device *dev, struct page *page,
0268                     unsigned long offset, size_t size,
0269                     enum dma_data_direction direction)
0270 void
0271 dma_unmap_page(struct device *dev, dma_addr_t dma_address, size_t size,
0272                enum dma_data_direction direction)
0273 
0274 API for mapping and unmapping for pages.  All the notes and warnings
0275 for the other mapping APIs apply here.  Also, although the <offset>
0276 and <size> parameters are provided to do partial page mapping, it is
0277 recommended that you never use these unless you really know what the
0278 cache width is.
0279 
0280 dma_addr_t
0281 dma_map_resource(struct device *dev, phys_addr_t phys_addr, size_t size,
0282                  enum dma_data_direction dir, unsigned long attrs)
0283 
0284 void
0285 dma_unmap_resource(struct device *dev, dma_addr_t addr, size_t size,
0286                    enum dma_data_direction dir, unsigned long attrs)
0287 
0288 API for mapping and unmapping for MMIO resources. All the notes and
0289 warnings for the other mapping APIs apply here. The API should only be
0290 used to map device MMIO resources, mapping of RAM is not permitted.
0291 
0292 int
0293 dma_mapping_error(struct device *dev, dma_addr_t dma_addr)
0294 
0295 In some circumstances dma_map_single(), dma_map_page() and dma_map_resource()
0296 will fail to create a mapping. A driver can check for these errors by testing
0297 the returned DMA address with dma_mapping_error(). A non-zero return value
0298 means the mapping could not be created and the driver should take appropriate
0299 action (e.g. reduce current DMA mapping usage or delay and try again later).
0300 
0301         int
0302         dma_map_sg(struct device *dev, struct scatterlist *sg,
0303                 int nents, enum dma_data_direction direction)
0304 
0305 Returns: the number of DMA address segments mapped (this may be shorter
0306 than <nents> passed in if some elements of the scatter/gather list are
0307 physically or virtually adjacent and an IOMMU maps them with a single
0308 entry).
0309 
0310 Please note that the sg cannot be mapped again if it has been mapped once.
0311 The mapping process is allowed to destroy information in the sg.
0312 
0313 As with the other mapping interfaces, dma_map_sg() can fail. When it
0314 does, 0 is returned and a driver must take appropriate action. It is
0315 critical that the driver do something, in the case of a block driver
0316 aborting the request or even oopsing is better than doing nothing and
0317 corrupting the filesystem.
0318 
0319 With scatterlists, you use the resulting mapping like this:
0320 
0321         int i, count = dma_map_sg(dev, sglist, nents, direction);
0322         struct scatterlist *sg;
0323 
0324         for_each_sg(sglist, sg, count, i) {
0325                 hw_address[i] = sg_dma_address(sg);
0326                 hw_len[i] = sg_dma_len(sg);
0327         }
0328 
0329 where nents is the number of entries in the sglist.
0330 
0331 The implementation is free to merge several consecutive sglist entries
0332 into one (e.g. with an IOMMU, or if several pages just happen to be
0333 physically contiguous) and returns the actual number of sg entries it
0334 mapped them to. On failure 0, is returned.
0335 
0336 Then you should loop count times (note: this can be less than nents times)
0337 and use sg_dma_address() and sg_dma_len() macros where you previously
0338 accessed sg->address and sg->length as shown above.
0339 
0340         void
0341         dma_unmap_sg(struct device *dev, struct scatterlist *sg,
0342                 int nents, enum dma_data_direction direction)
0343 
0344 Unmap the previously mapped scatter/gather list.  All the parameters
0345 must be the same as those and passed in to the scatter/gather mapping
0346 API.
0347 
0348 Note: <nents> must be the number you passed in, *not* the number of
0349 DMA address entries returned.
0350 
0351 void
0352 dma_sync_single_for_cpu(struct device *dev, dma_addr_t dma_handle, size_t size,
0353                         enum dma_data_direction direction)
0354 void
0355 dma_sync_single_for_device(struct device *dev, dma_addr_t dma_handle, size_t size,
0356                            enum dma_data_direction direction)
0357 void
0358 dma_sync_sg_for_cpu(struct device *dev, struct scatterlist *sg, int nents,
0359                     enum dma_data_direction direction)
0360 void
0361 dma_sync_sg_for_device(struct device *dev, struct scatterlist *sg, int nents,
0362                        enum dma_data_direction direction)
0363 
0364 Synchronise a single contiguous or scatter/gather mapping for the CPU
0365 and device. With the sync_sg API, all the parameters must be the same
0366 as those passed into the single mapping API. With the sync_single API,
0367 you can use dma_handle and size parameters that aren't identical to
0368 those passed into the single mapping API to do a partial sync.
0369 
0370 Notes:  You must do this:
0371 
0372 - Before reading values that have been written by DMA from the device
0373   (use the DMA_FROM_DEVICE direction)
0374 - After writing values that will be written to the device using DMA
0375   (use the DMA_TO_DEVICE) direction
0376 - before *and* after handing memory to the device if the memory is
0377   DMA_BIDIRECTIONAL
0378 
0379 See also dma_map_single().
0380 
0381 dma_addr_t
0382 dma_map_single_attrs(struct device *dev, void *cpu_addr, size_t size,
0383                      enum dma_data_direction dir,
0384                      unsigned long attrs)
0385 
0386 void
0387 dma_unmap_single_attrs(struct device *dev, dma_addr_t dma_addr,
0388                        size_t size, enum dma_data_direction dir,
0389                        unsigned long attrs)
0390 
0391 int
0392 dma_map_sg_attrs(struct device *dev, struct scatterlist *sgl,
0393                  int nents, enum dma_data_direction dir,
0394                  unsigned long attrs)
0395 
0396 void
0397 dma_unmap_sg_attrs(struct device *dev, struct scatterlist *sgl,
0398                    int nents, enum dma_data_direction dir,
0399                    unsigned long attrs)
0400 
0401 The four functions above are just like the counterpart functions
0402 without the _attrs suffixes, except that they pass an optional
0403 dma_attrs.
0404 
0405 The interpretation of DMA attributes is architecture-specific, and
0406 each attribute should be documented in Documentation/DMA-attributes.txt.
0407 
0408 If dma_attrs are 0, the semantics of each of these functions
0409 is identical to those of the corresponding function
0410 without the _attrs suffix. As a result dma_map_single_attrs()
0411 can generally replace dma_map_single(), etc.
0412 
0413 As an example of the use of the *_attrs functions, here's how
0414 you could pass an attribute DMA_ATTR_FOO when mapping memory
0415 for DMA:
0416 
0417 #include <linux/dma-mapping.h>
0418 /* DMA_ATTR_FOO should be defined in linux/dma-mapping.h and
0419  * documented in Documentation/DMA-attributes.txt */
0420 ...
0421 
0422         unsigned long attr;
0423         attr |= DMA_ATTR_FOO;
0424         ....
0425         n = dma_map_sg_attrs(dev, sg, nents, DMA_TO_DEVICE, attr);
0426         ....
0427 
0428 Architectures that care about DMA_ATTR_FOO would check for its
0429 presence in their implementations of the mapping and unmapping
0430 routines, e.g.:
0431 
0432 void whizco_dma_map_sg_attrs(struct device *dev, dma_addr_t dma_addr,
0433                              size_t size, enum dma_data_direction dir,
0434                              unsigned long attrs)
0435 {
0436         ....
0437         if (attrs & DMA_ATTR_FOO)
0438                 /* twizzle the frobnozzle */
0439         ....
0440 
0441 
0442 Part II - Advanced dma_ usage
0443 -----------------------------
0444 
0445 Warning: These pieces of the DMA API should not be used in the
0446 majority of cases, since they cater for unlikely corner cases that
0447 don't belong in usual drivers.
0448 
0449 If you don't understand how cache line coherency works between a
0450 processor and an I/O device, you should not be using this part of the
0451 API at all.
0452 
0453 void *
0454 dma_alloc_noncoherent(struct device *dev, size_t size,
0455                                dma_addr_t *dma_handle, gfp_t flag)
0456 
0457 Identical to dma_alloc_coherent() except that the platform will
0458 choose to return either consistent or non-consistent memory as it sees
0459 fit.  By using this API, you are guaranteeing to the platform that you
0460 have all the correct and necessary sync points for this memory in the
0461 driver should it choose to return non-consistent memory.
0462 
0463 Note: where the platform can return consistent memory, it will
0464 guarantee that the sync points become nops.
0465 
0466 Warning:  Handling non-consistent memory is a real pain.  You should
0467 only use this API if you positively know your driver will be
0468 required to work on one of the rare (usually non-PCI) architectures
0469 that simply cannot make consistent memory.
0470 
0471 void
0472 dma_free_noncoherent(struct device *dev, size_t size, void *cpu_addr,
0473                               dma_addr_t dma_handle)
0474 
0475 Free memory allocated by the nonconsistent API.  All parameters must
0476 be identical to those passed in (and returned by
0477 dma_alloc_noncoherent()).
0478 
0479 int
0480 dma_get_cache_alignment(void)
0481 
0482 Returns the processor cache alignment.  This is the absolute minimum
0483 alignment *and* width that you must observe when either mapping
0484 memory or doing partial flushes.
0485 
0486 Notes: This API may return a number *larger* than the actual cache
0487 line, but it will guarantee that one or more cache lines fit exactly
0488 into the width returned by this call.  It will also always be a power
0489 of two for easy alignment.
0490 
0491 void
0492 dma_cache_sync(struct device *dev, void *vaddr, size_t size,
0493                enum dma_data_direction direction)
0494 
0495 Do a partial sync of memory that was allocated by
0496 dma_alloc_noncoherent(), starting at virtual address vaddr and
0497 continuing on for size.  Again, you *must* observe the cache line
0498 boundaries when doing this.
0499 
0500 int
0501 dma_declare_coherent_memory(struct device *dev, phys_addr_t phys_addr,
0502                             dma_addr_t device_addr, size_t size, int
0503                             flags)
0504 
0505 Declare region of memory to be handed out by dma_alloc_coherent() when
0506 it's asked for coherent memory for this device.
0507 
0508 phys_addr is the CPU physical address to which the memory is currently
0509 assigned (this will be ioremapped so the CPU can access the region).
0510 
0511 device_addr is the DMA address the device needs to be programmed
0512 with to actually address this memory (this will be handed out as the
0513 dma_addr_t in dma_alloc_coherent()).
0514 
0515 size is the size of the area (must be multiples of PAGE_SIZE).
0516 
0517 flags can be ORed together and are:
0518 
0519 DMA_MEMORY_MAP - request that the memory returned from
0520 dma_alloc_coherent() be directly writable.
0521 
0522 DMA_MEMORY_IO - request that the memory returned from
0523 dma_alloc_coherent() be addressable using read()/write()/memcpy_toio() etc.
0524 
0525 One or both of these flags must be present.
0526 
0527 DMA_MEMORY_INCLUDES_CHILDREN - make the declared memory be allocated by
0528 dma_alloc_coherent of any child devices of this one (for memory residing
0529 on a bridge).
0530 
0531 DMA_MEMORY_EXCLUSIVE - only allocate memory from the declared regions. 
0532 Do not allow dma_alloc_coherent() to fall back to system memory when
0533 it's out of memory in the declared region.
0534 
0535 The return value will be either DMA_MEMORY_MAP or DMA_MEMORY_IO and
0536 must correspond to a passed in flag (i.e. no returning DMA_MEMORY_IO
0537 if only DMA_MEMORY_MAP were passed in) for success or zero for
0538 failure.
0539 
0540 Note, for DMA_MEMORY_IO returns, all subsequent memory returned by
0541 dma_alloc_coherent() may no longer be accessed directly, but instead
0542 must be accessed using the correct bus functions.  If your driver
0543 isn't prepared to handle this contingency, it should not specify
0544 DMA_MEMORY_IO in the input flags.
0545 
0546 As a simplification for the platforms, only *one* such region of
0547 memory may be declared per device.
0548 
0549 For reasons of efficiency, most platforms choose to track the declared
0550 region only at the granularity of a page.  For smaller allocations,
0551 you should use the dma_pool() API.
0552 
0553 void
0554 dma_release_declared_memory(struct device *dev)
0555 
0556 Remove the memory region previously declared from the system.  This
0557 API performs *no* in-use checking for this region and will return
0558 unconditionally having removed all the required structures.  It is the
0559 driver's job to ensure that no parts of this memory region are
0560 currently in use.
0561 
0562 void *
0563 dma_mark_declared_memory_occupied(struct device *dev,
0564                                   dma_addr_t device_addr, size_t size)
0565 
0566 This is used to occupy specific regions of the declared space
0567 (dma_alloc_coherent() will hand out the first free region it finds).
0568 
0569 device_addr is the *device* address of the region requested.
0570 
0571 size is the size (and should be a page-sized multiple).
0572 
0573 The return value will be either a pointer to the processor virtual
0574 address of the memory, or an error (via PTR_ERR()) if any part of the
0575 region is occupied.
0576 
0577 Part III - Debug drivers use of the DMA-API
0578 -------------------------------------------
0579 
0580 The DMA-API as described above has some constraints. DMA addresses must be
0581 released with the corresponding function with the same size for example. With
0582 the advent of hardware IOMMUs it becomes more and more important that drivers
0583 do not violate those constraints. In the worst case such a violation can
0584 result in data corruption up to destroyed filesystems.
0585 
0586 To debug drivers and find bugs in the usage of the DMA-API checking code can
0587 be compiled into the kernel which will tell the developer about those
0588 violations. If your architecture supports it you can select the "Enable
0589 debugging of DMA-API usage" option in your kernel configuration. Enabling this
0590 option has a performance impact. Do not enable it in production kernels.
0591 
0592 If you boot the resulting kernel will contain code which does some bookkeeping
0593 about what DMA memory was allocated for which device. If this code detects an
0594 error it prints a warning message with some details into your kernel log. An
0595 example warning message may look like this:
0596 
0597 ------------[ cut here ]------------
0598 WARNING: at /data2/repos/linux-2.6-iommu/lib/dma-debug.c:448
0599         check_unmap+0x203/0x490()
0600 Hardware name:
0601 forcedeth 0000:00:08.0: DMA-API: device driver frees DMA memory with wrong
0602         function [device address=0x00000000640444be] [size=66 bytes] [mapped as
0603 single] [unmapped as page]
0604 Modules linked in: nfsd exportfs bridge stp llc r8169
0605 Pid: 0, comm: swapper Tainted: G        W  2.6.28-dmatest-09289-g8bb99c0 #1
0606 Call Trace:
0607  <IRQ>  [<ffffffff80240b22>] warn_slowpath+0xf2/0x130
0608  [<ffffffff80647b70>] _spin_unlock+0x10/0x30
0609  [<ffffffff80537e75>] usb_hcd_link_urb_to_ep+0x75/0xc0
0610  [<ffffffff80647c22>] _spin_unlock_irqrestore+0x12/0x40
0611  [<ffffffff8055347f>] ohci_urb_enqueue+0x19f/0x7c0
0612  [<ffffffff80252f96>] queue_work+0x56/0x60
0613  [<ffffffff80237e10>] enqueue_task_fair+0x20/0x50
0614  [<ffffffff80539279>] usb_hcd_submit_urb+0x379/0xbc0
0615  [<ffffffff803b78c3>] cpumask_next_and+0x23/0x40
0616  [<ffffffff80235177>] find_busiest_group+0x207/0x8a0
0617  [<ffffffff8064784f>] _spin_lock_irqsave+0x1f/0x50
0618  [<ffffffff803c7ea3>] check_unmap+0x203/0x490
0619  [<ffffffff803c8259>] debug_dma_unmap_page+0x49/0x50
0620  [<ffffffff80485f26>] nv_tx_done_optimized+0xc6/0x2c0
0621  [<ffffffff80486c13>] nv_nic_irq_optimized+0x73/0x2b0
0622  [<ffffffff8026df84>] handle_IRQ_event+0x34/0x70
0623  [<ffffffff8026ffe9>] handle_edge_irq+0xc9/0x150
0624  [<ffffffff8020e3ab>] do_IRQ+0xcb/0x1c0
0625  [<ffffffff8020c093>] ret_from_intr+0x0/0xa
0626  <EOI> <4>---[ end trace f6435a98e2a38c0e ]---
0627 
0628 The driver developer can find the driver and the device including a stacktrace
0629 of the DMA-API call which caused this warning.
0630 
0631 Per default only the first error will result in a warning message. All other
0632 errors will only silently counted. This limitation exist to prevent the code
0633 from flooding your kernel log. To support debugging a device driver this can
0634 be disabled via debugfs. See the debugfs interface documentation below for
0635 details.
0636 
0637 The debugfs directory for the DMA-API debugging code is called dma-api/. In
0638 this directory the following files can currently be found:
0639 
0640         dma-api/all_errors      This file contains a numeric value. If this
0641                                 value is not equal to zero the debugging code
0642                                 will print a warning for every error it finds
0643                                 into the kernel log. Be careful with this
0644                                 option, as it can easily flood your logs.
0645 
0646         dma-api/disabled        This read-only file contains the character 'Y'
0647                                 if the debugging code is disabled. This can
0648                                 happen when it runs out of memory or if it was
0649                                 disabled at boot time
0650 
0651         dma-api/error_count     This file is read-only and shows the total
0652                                 numbers of errors found.
0653 
0654         dma-api/num_errors      The number in this file shows how many
0655                                 warnings will be printed to the kernel log
0656                                 before it stops. This number is initialized to
0657                                 one at system boot and be set by writing into
0658                                 this file
0659 
0660         dma-api/min_free_entries
0661                                 This read-only file can be read to get the
0662                                 minimum number of free dma_debug_entries the
0663                                 allocator has ever seen. If this value goes
0664                                 down to zero the code will disable itself
0665                                 because it is not longer reliable.
0666 
0667         dma-api/num_free_entries
0668                                 The current number of free dma_debug_entries
0669                                 in the allocator.
0670 
0671         dma-api/driver-filter
0672                                 You can write a name of a driver into this file
0673                                 to limit the debug output to requests from that
0674                                 particular driver. Write an empty string to
0675                                 that file to disable the filter and see
0676                                 all errors again.
0677 
0678 If you have this code compiled into your kernel it will be enabled by default.
0679 If you want to boot without the bookkeeping anyway you can provide
0680 'dma_debug=off' as a boot parameter. This will disable DMA-API debugging.
0681 Notice that you can not enable it again at runtime. You have to reboot to do
0682 so.
0683 
0684 If you want to see debug messages only for a special device driver you can
0685 specify the dma_debug_driver=<drivername> parameter. This will enable the
0686 driver filter at boot time. The debug code will only print errors for that
0687 driver afterwards. This filter can be disabled or changed later using debugfs.
0688 
0689 When the code disables itself at runtime this is most likely because it ran
0690 out of dma_debug_entries. These entries are preallocated at boot. The number
0691 of preallocated entries is defined per architecture. If it is too low for you
0692 boot with 'dma_debug_entries=<your_desired_number>' to overwrite the
0693 architectural default.
0694 
0695 void debug_dmap_mapping_error(struct device *dev, dma_addr_t dma_addr);
0696 
0697 dma-debug interface debug_dma_mapping_error() to debug drivers that fail
0698 to check DMA mapping errors on addresses returned by dma_map_single() and
0699 dma_map_page() interfaces. This interface clears a flag set by
0700 debug_dma_map_page() to indicate that dma_mapping_error() has been called by
0701 the driver. When driver does unmap, debug_dma_unmap() checks the flag and if
0702 this flag is still set, prints warning message that includes call trace that
0703 leads up to the unmap. This interface can be called from dma_mapping_error()
0704 routines to enable DMA mapping error check debugging.
0705