About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / DMA-API.txt




Custom Search

Based on kernel version 2.6.33. Page generated on 2010-02-24 15:35 EST.

1	               Dynamic DMA mapping using the generic device
2	               ============================================
3	
4	        James E.J. Bottomley <James.Bottomley[AT]HansenPartnership[DOT]com>
5	
6	This document describes the DMA API.  For a more gentle introduction
7	phrased in terms of the pci_ equivalents (and actual examples) see
8	Documentation/PCI/PCI-DMA-mapping.txt.
9	
10	This API is split into two pieces.  Part I describes the API and the
11	corresponding pci_ API.  Part II describes the extensions to the API
12	for supporting non-consistent memory machines.  Unless you know that
13	your driver absolutely has to support non-consistent platforms (this
14	is usually only legacy platforms) you should only use the API
15	described in part I.
16	
17	Part I - pci_ and dma_ Equivalent API 
18	-------------------------------------
19	
20	To get the pci_ API, you must #include <linux/pci.h>
21	To get the dma_ API, you must #include <linux/dma-mapping.h>
22	
23	
24	Part Ia - Using large dma-coherent buffers
25	------------------------------------------
26	
27	void *
28	dma_alloc_coherent(struct device *dev, size_t size,
29				     dma_addr_t *dma_handle, gfp_t flag)
30	void *
31	pci_alloc_consistent(struct pci_dev *dev, size_t size,
32				     dma_addr_t *dma_handle)
33	
34	Consistent memory is memory for which a write by either the device or
35	the processor can immediately be read by the processor or device
36	without having to worry about caching effects.  (You may however need
37	to make sure to flush the processor's write buffers before telling
38	devices to read that memory.)
39	
40	This routine allocates a region of <size> bytes of consistent memory.
41	It also returns a <dma_handle> which may be cast to an unsigned
42	integer the same width as the bus and used as the physical address
43	base of the region.
44	
45	Returns: a pointer to the allocated region (in the processor's virtual
46	address space) or NULL if the allocation failed.
47	
48	Note: consistent memory can be expensive on some platforms, and the
49	minimum allocation length may be as big as a page, so you should
50	consolidate your requests for consistent memory as much as possible.
51	The simplest way to do that is to use the dma_pool calls (see below).
52	
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).  For pci_alloc_consistent, you
57	must assume GFP_ATOMIC behaviour.
58	
59	void
60	dma_free_coherent(struct device *dev, size_t size, void *cpu_addr,
61				   dma_addr_t dma_handle)
62	void
63	pci_free_consistent(struct pci_dev *dev, size_t size, void *cpu_addr,
64				   dma_addr_t dma_handle)
65	
66	Free the region of consistent memory you previously allocated.  dev,
67	size and dma_handle must all be the same as those passed into the
68	consistent allocate.  cpu_addr must be the virtual address returned by
69	the consistent allocate.
70	
71	Note that unlike their sibling allocation calls, these routines
72	may only be called with IRQs enabled.
73	
74	
75	Part Ib - Using small dma-coherent buffers
76	------------------------------------------
77	
78	To get this part of the dma_ API, you must #include <linux/dmapool.h>
79	
80	Many drivers need lots of small dma-coherent memory regions for DMA
81	descriptors or I/O buffers.  Rather than allocating in units of a page
82	or more using dma_alloc_coherent(), you can use DMA pools.  These work
83	much like a struct kmem_cache, except that they use the dma-coherent allocator,
84	not __get_free_pages().  Also, they understand common hardware constraints
85	for alignment, like queue heads needing to be aligned on N-byte boundaries.
86	
87	
88		struct dma_pool *
89		dma_pool_create(const char *name, struct device *dev,
90				size_t size, size_t align, size_t alloc);
91	
92		struct pci_pool *
93		pci_pool_create(const char *name, struct pci_device *dev,
94				size_t size, size_t align, size_t alloc);
95	
96	The pool create() routines initialize a pool of dma-coherent buffers
97	for use with a given device.  It must be called in a context which
98	can sleep.
99	
100	The "name" is for diagnostics (like a struct kmem_cache name); dev and size
101	are like what you'd pass to dma_alloc_coherent().  The device's hardware
102	alignment requirement for this type of data is "align" (which is expressed
103	in bytes, and must be a power of two).  If your device has no boundary
104	crossing restrictions, pass 0 for alloc; passing 4096 says memory allocated
105	from this pool must not cross 4KByte boundaries.
106	
107	
108		void *dma_pool_alloc(struct dma_pool *pool, gfp_t gfp_flags,
109				dma_addr_t *dma_handle);
110	
111		void *pci_pool_alloc(struct pci_pool *pool, gfp_t gfp_flags,
112				dma_addr_t *dma_handle);
113	
114	This allocates memory from the pool; the returned memory will meet the size
115	and alignment requirements specified at creation time.  Pass GFP_ATOMIC to
116	prevent blocking, or if it's permitted (not in_interrupt, not holding SMP locks),
117	pass GFP_KERNEL to allow blocking.  Like dma_alloc_coherent(), this returns
118	two values:  an address usable by the cpu, and the dma address usable by the
119	pool's device.
120	
121	
122		void dma_pool_free(struct dma_pool *pool, void *vaddr,
123				dma_addr_t addr);
124	
125		void pci_pool_free(struct pci_pool *pool, void *vaddr,
126				dma_addr_t addr);
127	
128	This puts memory back into the pool.  The pool is what was passed to
129	the pool allocation routine; the cpu (vaddr) and dma addresses are what
130	were returned when that routine allocated the memory being freed.
131	
132	
133		void dma_pool_destroy(struct dma_pool *pool);
134	
135		void pci_pool_destroy(struct pci_pool *pool);
136	
137	The pool destroy() routines free the resources of the pool.  They must be
138	called in a context which can sleep.  Make sure you've freed all allocated
139	memory back to the pool before you destroy it.
140	
141	
142	Part Ic - DMA addressing limitations
143	------------------------------------
144	
145	int
146	dma_supported(struct device *dev, u64 mask)
147	int
148	pci_dma_supported(struct pci_dev *hwdev, u64 mask)
149	
150	Checks to see if the device can support DMA to the memory described by
151	mask.
152	
153	Returns: 1 if it can and 0 if it can't.
154	
155	Notes: This routine merely tests to see if the mask is possible.  It
156	won't change the current mask settings.  It is more intended as an
157	internal API for use by the platform than an external API for use by
158	driver writers.
159	
160	int
161	dma_set_mask(struct device *dev, u64 mask)
162	int
163	pci_set_dma_mask(struct pci_device *dev, u64 mask)
164	
165	Checks to see if the mask is possible and updates the device
166	parameters if it is.
167	
168	Returns: 0 if successful and a negative error if not.
169	
170	u64
171	dma_get_required_mask(struct device *dev)
172	
173	This API returns the mask that the platform requires to
174	operate efficiently.  Usually this means the returned mask
175	is the minimum required to cover all of memory.  Examining the
176	required mask gives drivers with variable descriptor sizes the
177	opportunity to use smaller descriptors as necessary.
178	
179	Requesting the required mask does not alter the current mask.  If you
180	wish to take advantage of it, you should issue a dma_set_mask()
181	call to set the mask to the value returned.
182	
183	
184	Part Id - Streaming DMA mappings
185	--------------------------------
186	
187	dma_addr_t
188	dma_map_single(struct device *dev, void *cpu_addr, size_t size,
189			      enum dma_data_direction direction)
190	dma_addr_t
191	pci_map_single(struct pci_dev *hwdev, void *cpu_addr, size_t size,
192			      int direction)
193	
194	Maps a piece of processor virtual memory so it can be accessed by the
195	device and returns the physical handle of the memory.
196	
197	The direction for both api's may be converted freely by casting.
198	However the dma_ API uses a strongly typed enumerator for its
199	direction:
200	
201	DMA_NONE		= PCI_DMA_NONE		no direction (used for
202							debugging)
203	DMA_TO_DEVICE		= PCI_DMA_TODEVICE	data is going from the
204							memory to the device
205	DMA_FROM_DEVICE		= PCI_DMA_FROMDEVICE	data is coming from
206							the device to the
207							memory
208	DMA_BIDIRECTIONAL	= PCI_DMA_BIDIRECTIONAL	direction isn't known
209	
210	Notes:  Not all memory regions in a machine can be mapped by this
211	API.  Further, regions that appear to be physically contiguous in
212	kernel virtual space may not be contiguous as physical memory.  Since
213	this API does not provide any scatter/gather capability, it will fail
214	if the user tries to map a non-physically contiguous piece of memory.
215	For this reason, it is recommended that memory mapped by this API be
216	obtained only from sources which guarantee it to be physically contiguous
217	(like kmalloc).
218	
219	Further, the physical address of the memory must be within the
220	dma_mask of the device (the dma_mask represents a bit mask of the
221	addressable region for the device.  I.e., if the physical address of
222	the memory anded with the dma_mask is still equal to the physical
223	address, then the device can perform DMA to the memory).  In order to
224	ensure that the memory allocated by kmalloc is within the dma_mask,
225	the driver may specify various platform-dependent flags to restrict
226	the physical memory range of the allocation (e.g. on x86, GFP_DMA
227	guarantees to be within the first 16Mb of available physical memory,
228	as required by ISA devices).
229	
230	Note also that the above constraints on physical contiguity and
231	dma_mask may not apply if the platform has an IOMMU (a device which
232	supplies a physical to virtual mapping between the I/O memory bus and
233	the device).  However, to be portable, device driver writers may *not*
234	assume that such an IOMMU exists.
235	
236	Warnings:  Memory coherency operates at a granularity called the cache
237	line width.  In order for memory mapped by this API to operate
238	correctly, the mapped region must begin exactly on a cache line
239	boundary and end exactly on one (to prevent two separately mapped
240	regions from sharing a single cache line).  Since the cache line size
241	may not be known at compile time, the API will not enforce this
242	requirement.  Therefore, it is recommended that driver writers who
243	don't take special care to determine the cache line size at run time
244	only map virtual regions that begin and end on page boundaries (which
245	are guaranteed also to be cache line boundaries).
246	
247	DMA_TO_DEVICE synchronisation must be done after the last modification
248	of the memory region by the software and before it is handed off to
249	the driver.  Once this primitive is used, memory covered by this
250	primitive should be treated as read-only by the device.  If the device
251	may write to it at any point, it should be DMA_BIDIRECTIONAL (see
252	below).
253	
254	DMA_FROM_DEVICE synchronisation must be done before the driver
255	accesses data that may be changed by the device.  This memory should
256	be treated as read-only by the driver.  If the driver needs to write
257	to it at any point, it should be DMA_BIDIRECTIONAL (see below).
258	
259	DMA_BIDIRECTIONAL requires special handling: it means that the driver
260	isn't sure if the memory was modified before being handed off to the
261	device and also isn't sure if the device will also modify it.  Thus,
262	you must always sync bidirectional memory twice: once before the
263	memory is handed off to the device (to make sure all memory changes
264	are flushed from the processor) and once before the data may be
265	accessed after being used by the device (to make sure any processor
266	cache lines are updated with data that the device may have changed).
267	
268	void
269	dma_unmap_single(struct device *dev, dma_addr_t dma_addr, size_t size,
270			 enum dma_data_direction direction)
271	void
272	pci_unmap_single(struct pci_dev *hwdev, dma_addr_t dma_addr,
273			 size_t size, int direction)
274	
275	Unmaps the region previously mapped.  All the parameters passed in
276	must be identical to those passed in (and returned) by the mapping
277	API.
278	
279	dma_addr_t
280	dma_map_page(struct device *dev, struct page *page,
281			    unsigned long offset, size_t size,
282			    enum dma_data_direction direction)
283	dma_addr_t
284	pci_map_page(struct pci_dev *hwdev, struct page *page,
285			    unsigned long offset, size_t size, int direction)
286	void
287	dma_unmap_page(struct device *dev, dma_addr_t dma_address, size_t size,
288		       enum dma_data_direction direction)
289	void
290	pci_unmap_page(struct pci_dev *hwdev, dma_addr_t dma_address,
291		       size_t size, int direction)
292	
293	API for mapping and unmapping for pages.  All the notes and warnings
294	for the other mapping APIs apply here.  Also, although the <offset>
295	and <size> parameters are provided to do partial page mapping, it is
296	recommended that you never use these unless you really know what the
297	cache width is.
298	
299	int
300	dma_mapping_error(struct device *dev, dma_addr_t dma_addr)
301	
302	int
303	pci_dma_mapping_error(struct pci_dev *hwdev, dma_addr_t dma_addr)
304	
305	In some circumstances dma_map_single and dma_map_page will fail to create
306	a mapping. A driver can check for these errors by testing the returned
307	dma address with dma_mapping_error(). A non-zero return value means the mapping
308	could not be created and the driver should take appropriate action (e.g.
309	reduce current DMA mapping usage or delay and try again later).
310	
311		int
312		dma_map_sg(struct device *dev, struct scatterlist *sg,
313			int nents, enum dma_data_direction direction)
314		int
315		pci_map_sg(struct pci_dev *hwdev, struct scatterlist *sg,
316			int nents, int direction)
317	
318	Returns: the number of physical segments mapped (this may be shorter
319	than <nents> passed in if some elements of the scatter/gather list are
320	physically or virtually adjacent and an IOMMU maps them with a single
321	entry).
322	
323	Please note that the sg cannot be mapped again if it has been mapped once.
324	The mapping process is allowed to destroy information in the sg.
325	
326	As with the other mapping interfaces, dma_map_sg can fail. When it
327	does, 0 is returned and a driver must take appropriate action. It is
328	critical that the driver do something, in the case of a block driver
329	aborting the request or even oopsing is better than doing nothing and
330	corrupting the filesystem.
331	
332	With scatterlists, you use the resulting mapping like this:
333	
334		int i, count = dma_map_sg(dev, sglist, nents, direction);
335		struct scatterlist *sg;
336	
337		for_each_sg(sglist, sg, count, i) {
338			hw_address[i] = sg_dma_address(sg);
339			hw_len[i] = sg_dma_len(sg);
340		}
341	
342	where nents is the number of entries in the sglist.
343	
344	The implementation is free to merge several consecutive sglist entries
345	into one (e.g. with an IOMMU, or if several pages just happen to be
346	physically contiguous) and returns the actual number of sg entries it
347	mapped them to. On failure 0, is returned.
348	
349	Then you should loop count times (note: this can be less than nents times)
350	and use sg_dma_address() and sg_dma_len() macros where you previously
351	accessed sg->address and sg->length as shown above.
352	
353		void
354		dma_unmap_sg(struct device *dev, struct scatterlist *sg,
355			int nhwentries, enum dma_data_direction direction)
356		void
357		pci_unmap_sg(struct pci_dev *hwdev, struct scatterlist *sg,
358			int nents, int direction)
359	
360	Unmap the previously mapped scatter/gather list.  All the parameters
361	must be the same as those and passed in to the scatter/gather mapping
362	API.
363	
364	Note: <nents> must be the number you passed in, *not* the number of
365	physical entries returned.
366	
367	void
368	dma_sync_single(struct device *dev, dma_addr_t dma_handle, size_t size,
369			enum dma_data_direction direction)
370	void
371	pci_dma_sync_single(struct pci_dev *hwdev, dma_addr_t dma_handle,
372				   size_t size, int direction)
373	void
374	dma_sync_sg(struct device *dev, struct scatterlist *sg, int nelems,
375				  enum dma_data_direction direction)
376	void
377	pci_dma_sync_sg(struct pci_dev *hwdev, struct scatterlist *sg,
378			       int nelems, int direction)
379	
380	Synchronise a single contiguous or scatter/gather mapping.  All the
381	parameters must be the same as those passed into the single mapping
382	API.
383	
384	Notes:  You must do this:
385	
386	- Before reading values that have been written by DMA from the device
387	  (use the DMA_FROM_DEVICE direction)
388	- After writing values that will be written to the device using DMA
389	  (use the DMA_TO_DEVICE) direction
390	- before *and* after handing memory to the device if the memory is
391	  DMA_BIDIRECTIONAL
392	
393	See also dma_map_single().
394	
395	dma_addr_t
396	dma_map_single_attrs(struct device *dev, void *cpu_addr, size_t size,
397			     enum dma_data_direction dir,
398			     struct dma_attrs *attrs)
399	
400	void
401	dma_unmap_single_attrs(struct device *dev, dma_addr_t dma_addr,
402			       size_t size, enum dma_data_direction dir,
403			       struct dma_attrs *attrs)
404	
405	int
406	dma_map_sg_attrs(struct device *dev, struct scatterlist *sgl,
407			 int nents, enum dma_data_direction dir,
408			 struct dma_attrs *attrs)
409	
410	void
411	dma_unmap_sg_attrs(struct device *dev, struct scatterlist *sgl,
412			   int nents, enum dma_data_direction dir,
413			   struct dma_attrs *attrs)
414	
415	The four functions above are just like the counterpart functions
416	without the _attrs suffixes, except that they pass an optional
417	struct dma_attrs*.
418	
419	struct dma_attrs encapsulates a set of "dma attributes". For the
420	definition of struct dma_attrs see linux/dma-attrs.h.
421	
422	The interpretation of dma attributes is architecture-specific, and
423	each attribute should be documented in Documentation/DMA-attributes.txt.
424	
425	If struct dma_attrs* is NULL, the semantics of each of these
426	functions is identical to those of the corresponding function
427	without the _attrs suffix. As a result dma_map_single_attrs()
428	can generally replace dma_map_single(), etc.
429	
430	As an example of the use of the *_attrs functions, here's how
431	you could pass an attribute DMA_ATTR_FOO when mapping memory
432	for DMA:
433	
434	#include <linux/dma-attrs.h>
435	/* DMA_ATTR_FOO should be defined in linux/dma-attrs.h and
436	 * documented in Documentation/DMA-attributes.txt */
437	...
438	
439		DEFINE_DMA_ATTRS(attrs);
440		dma_set_attr(DMA_ATTR_FOO, &attrs);
441		....
442		n = dma_map_sg_attrs(dev, sg, nents, DMA_TO_DEVICE, &attr);
443		....
444	
445	Architectures that care about DMA_ATTR_FOO would check for its
446	presence in their implementations of the mapping and unmapping
447	routines, e.g.:
448	
449	void whizco_dma_map_sg_attrs(struct device *dev, dma_addr_t dma_addr,
450				     size_t size, enum dma_data_direction dir,
451				     struct dma_attrs *attrs)
452	{
453		....
454		int foo =  dma_get_attr(DMA_ATTR_FOO, attrs);
455		....
456		if (foo)
457			/* twizzle the frobnozzle */
458		....
459	
460	
461	Part II - Advanced dma_ usage
462	-----------------------------
463	
464	Warning: These pieces of the DMA API have no PCI equivalent.  They
465	should also not be used in the majority of cases, since they cater for
466	unlikely corner cases that don't belong in usual drivers.
467	
468	If you don't understand how cache line coherency works between a
469	processor and an I/O device, you should not be using this part of the
470	API at all.
471	
472	void *
473	dma_alloc_noncoherent(struct device *dev, size_t size,
474				       dma_addr_t *dma_handle, gfp_t flag)
475	
476	Identical to dma_alloc_coherent() except that the platform will
477	choose to return either consistent or non-consistent memory as it sees
478	fit.  By using this API, you are guaranteeing to the platform that you
479	have all the correct and necessary sync points for this memory in the
480	driver should it choose to return non-consistent memory.
481	
482	Note: where the platform can return consistent memory, it will
483	guarantee that the sync points become nops.
484	
485	Warning:  Handling non-consistent memory is a real pain.  You should
486	only ever use this API if you positively know your driver will be
487	required to work on one of the rare (usually non-PCI) architectures
488	that simply cannot make consistent memory.
489	
490	void
491	dma_free_noncoherent(struct device *dev, size_t size, void *cpu_addr,
492				      dma_addr_t dma_handle)
493	
494	Free memory allocated by the nonconsistent API.  All parameters must
495	be identical to those passed in (and returned by
496	dma_alloc_noncoherent()).
497	
498	int
499	dma_is_consistent(struct device *dev, dma_addr_t dma_handle)
500	
501	Returns true if the device dev is performing consistent DMA on the memory
502	area pointed to by the dma_handle.
503	
504	int
505	dma_get_cache_alignment(void)
506	
507	Returns the processor cache alignment.  This is the absolute minimum
508	alignment *and* width that you must observe when either mapping
509	memory or doing partial flushes.
510	
511	Notes: This API may return a number *larger* than the actual cache
512	line, but it will guarantee that one or more cache lines fit exactly
513	into the width returned by this call.  It will also always be a power
514	of two for easy alignment.
515	
516	void
517	dma_sync_single_range(struct device *dev, dma_addr_t dma_handle,
518			      unsigned long offset, size_t size,
519			      enum dma_data_direction direction)
520	
521	Does a partial sync, starting at offset and continuing for size.  You
522	must be careful to observe the cache alignment and width when doing
523	anything like this.  You must also be extra careful about accessing
524	memory you intend to sync partially.
525	
526	void
527	dma_cache_sync(struct device *dev, void *vaddr, size_t size,
528		       enum dma_data_direction direction)
529	
530	Do a partial sync of memory that was allocated by
531	dma_alloc_noncoherent(), starting at virtual address vaddr and
532	continuing on for size.  Again, you *must* observe the cache line
533	boundaries when doing this.
534	
535	int
536	dma_declare_coherent_memory(struct device *dev, dma_addr_t bus_addr,
537				    dma_addr_t device_addr, size_t size, int
538				    flags)
539	
540	Declare region of memory to be handed out by dma_alloc_coherent when
541	it's asked for coherent memory for this device.
542	
543	bus_addr is the physical address to which the memory is currently
544	assigned in the bus responding region (this will be used by the
545	platform to perform the mapping).
546	
547	device_addr is the physical address the device needs to be programmed
548	with actually to address this memory (this will be handed out as the
549	dma_addr_t in dma_alloc_coherent()).
550	
551	size is the size of the area (must be multiples of PAGE_SIZE).
552	
553	flags can be or'd together and are:
554	
555	DMA_MEMORY_MAP - request that the memory returned from
556	dma_alloc_coherent() be directly writable.
557	
558	DMA_MEMORY_IO - request that the memory returned from
559	dma_alloc_coherent() be addressable using read/write/memcpy_toio etc.
560	
561	One or both of these flags must be present.
562	
563	DMA_MEMORY_INCLUDES_CHILDREN - make the declared memory be allocated by
564	dma_alloc_coherent of any child devices of this one (for memory residing
565	on a bridge).
566	
567	DMA_MEMORY_EXCLUSIVE - only allocate memory from the declared regions. 
568	Do not allow dma_alloc_coherent() to fall back to system memory when
569	it's out of memory in the declared region.
570	
571	The return value will be either DMA_MEMORY_MAP or DMA_MEMORY_IO and
572	must correspond to a passed in flag (i.e. no returning DMA_MEMORY_IO
573	if only DMA_MEMORY_MAP were passed in) for success or zero for
574	failure.
575	
576	Note, for DMA_MEMORY_IO returns, all subsequent memory returned by
577	dma_alloc_coherent() may no longer be accessed directly, but instead
578	must be accessed using the correct bus functions.  If your driver
579	isn't prepared to handle this contingency, it should not specify
580	DMA_MEMORY_IO in the input flags.
581	
582	As a simplification for the platforms, only *one* such region of
583	memory may be declared per device.
584	
585	For reasons of efficiency, most platforms choose to track the declared
586	region only at the granularity of a page.  For smaller allocations,
587	you should use the dma_pool() API.
588	
589	void
590	dma_release_declared_memory(struct device *dev)
591	
592	Remove the memory region previously declared from the system.  This
593	API performs *no* in-use checking for this region and will return
594	unconditionally having removed all the required structures.  It is the
595	driver's job to ensure that no parts of this memory region are
596	currently in use.
597	
598	void *
599	dma_mark_declared_memory_occupied(struct device *dev,
600					  dma_addr_t device_addr, size_t size)
601	
602	This is used to occupy specific regions of the declared space
603	(dma_alloc_coherent() will hand out the first free region it finds).
604	
605	device_addr is the *device* address of the region requested.
606	
607	size is the size (and should be a page-sized multiple).
608	
609	The return value will be either a pointer to the processor virtual
610	address of the memory, or an error (via PTR_ERR()) if any part of the
611	region is occupied.
612	
613	Part III - Debug drivers use of the DMA-API
614	-------------------------------------------
615	
616	The DMA-API as described above as some constraints. DMA addresses must be
617	released with the corresponding function with the same size for example. With
618	the advent of hardware IOMMUs it becomes more and more important that drivers
619	do not violate those constraints. In the worst case such a violation can
620	result in data corruption up to destroyed filesystems.
621	
622	To debug drivers and find bugs in the usage of the DMA-API checking code can
623	be compiled into the kernel which will tell the developer about those
624	violations. If your architecture supports it you can select the "Enable
625	debugging of DMA-API usage" option in your kernel configuration. Enabling this
626	option has a performance impact. Do not enable it in production kernels.
627	
628	If you boot the resulting kernel will contain code which does some bookkeeping
629	about what DMA memory was allocated for which device. If this code detects an
630	error it prints a warning message with some details into your kernel log. An
631	example warning message may look like this:
632	
633	------------[ cut here ]------------
634	WARNING: at /data2/repos/linux-2.6-iommu/lib/dma-debug.c:448
635		check_unmap+0x203/0x490()
636	Hardware name:
637	forcedeth 0000:00:08.0: DMA-API: device driver frees DMA memory with wrong
638		function [device address=0x00000000640444be] [size=66 bytes] [mapped as
639	single] [unmapped as page]
640	Modules linked in: nfsd exportfs bridge stp llc r8169
641	Pid: 0, comm: swapper Tainted: G        W  2.6.28-dmatest-09289-g8bb99c0 #1
642	Call Trace:
643	 <IRQ>  [<ffffffff80240b22>] warn_slowpath+0xf2/0x130
644	 [<ffffffff80647b70>] _spin_unlock+0x10/0x30
645	 [<ffffffff80537e75>] usb_hcd_link_urb_to_ep+0x75/0xc0
646	 [<ffffffff80647c22>] _spin_unlock_irqrestore+0x12/0x40
647	 [<ffffffff8055347f>] ohci_urb_enqueue+0x19f/0x7c0
648	 [<ffffffff80252f96>] queue_work+0x56/0x60
649	 [<ffffffff80237e10>] enqueue_task_fair+0x20/0x50
650	 [<ffffffff80539279>] usb_hcd_submit_urb+0x379/0xbc0
651	 [<ffffffff803b78c3>] cpumask_next_and+0x23/0x40
652	 [<ffffffff80235177>] find_busiest_group+0x207/0x8a0
653	 [<ffffffff8064784f>] _spin_lock_irqsave+0x1f/0x50
654	 [<ffffffff803c7ea3>] check_unmap+0x203/0x490
655	 [<ffffffff803c8259>] debug_dma_unmap_page+0x49/0x50
656	 [<ffffffff80485f26>] nv_tx_done_optimized+0xc6/0x2c0
657	 [<ffffffff80486c13>] nv_nic_irq_optimized+0x73/0x2b0
658	 [<ffffffff8026df84>] handle_IRQ_event+0x34/0x70
659	 [<ffffffff8026ffe9>] handle_edge_irq+0xc9/0x150
660	 [<ffffffff8020e3ab>] do_IRQ+0xcb/0x1c0
661	 [<ffffffff8020c093>] ret_from_intr+0x0/0xa
662	 <EOI> <4>---[ end trace f6435a98e2a38c0e ]---
663	
664	The driver developer can find the driver and the device including a stacktrace
665	of the DMA-API call which caused this warning.
666	
667	Per default only the first error will result in a warning message. All other
668	errors will only silently counted. This limitation exist to prevent the code
669	from flooding your kernel log. To support debugging a device driver this can
670	be disabled via debugfs. See the debugfs interface documentation below for
671	details.
672	
673	The debugfs directory for the DMA-API debugging code is called dma-api/. In
674	this directory the following files can currently be found:
675	
676		dma-api/all_errors	This file contains a numeric value. If this
677					value is not equal to zero the debugging code
678					will print a warning for every error it finds
679					into the kernel log. Be careful with this
680					option, as it can easily flood your logs.
681	
682		dma-api/disabled	This read-only file contains the character 'Y'
683					if the debugging code is disabled. This can
684					happen when it runs out of memory or if it was
685					disabled at boot time
686	
687		dma-api/error_count	This file is read-only and shows the total
688					numbers of errors found.
689	
690		dma-api/num_errors	The number in this file shows how many
691					warnings will be printed to the kernel log
692					before it stops. This number is initialized to
693					one at system boot and be set by writing into
694					this file
695	
696		dma-api/min_free_entries
697					This read-only file can be read to get the
698					minimum number of free dma_debug_entries the
699					allocator has ever seen. If this value goes
700					down to zero the code will disable itself
701					because it is not longer reliable.
702	
703		dma-api/num_free_entries
704					The current number of free dma_debug_entries
705					in the allocator.
706	
707		dma-api/driver-filter
708					You can write a name of a driver into this file
709					to limit the debug output to requests from that
710					particular driver. Write an empty string to
711					that file to disable the filter and see
712					all errors again.
713	
714	If you have this code compiled into your kernel it will be enabled by default.
715	If you want to boot without the bookkeeping anyway you can provide
716	'dma_debug=off' as a boot parameter. This will disable DMA-API debugging.
717	Notice that you can not enable it again at runtime. You have to reboot to do
718	so.
719	
720	If you want to see debug messages only for a special device driver you can
721	specify the dma_debug_driver=<drivername> parameter. This will enable the
722	driver filter at boot time. The debug code will only print errors for that
723	driver afterwards. This filter can be disabled or changed later using debugfs.
724	
725	When the code disables itself at runtime this is most likely because it ran
726	out of dma_debug_entries. These entries are preallocated at boot. The number
727	of preallocated entries is defined per architecture. If it is too low for you
728	boot with 'dma_debug_entries=<your_desired_number>' to overwrite the
729	architectural default.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog
Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.