Documentation/core-api/dma-api.rst

8 of the API (and actual examples), see :doc:`/core-api/dma-api-howto`.
11 Part II describes extensions for supporting non-consistent memory
13 non-consistent platforms (this is usually only legacy platforms) you
16 Part I - dma_API
17 ----------------
19 To get the dma_API, you must #include <linux/dma-mapping.h>.  This
27 Part Ia - Using large DMA-coherent buffers
28 ------------------------------------------
76 Part Ib - Using small DMA-coherent buffers
77 ------------------------------------------
81 Many drivers need lots of small DMA-coherent memory regions for DMA
84 much like a struct kmem_cache, except that they use the DMA-coherent allocator,
86 for alignment, like queue heads needing to be aligned on N-byte boundaries.
95 dma_pool_create() initializes a pool of DMA-coherent buffers
150 Part Ic - DMA addressing limitations
151 ------------------------------------
221 segments, the function returns 0.
223 Part Id - Streaming DMA mappings
224 --------------------------------
236 However the dma_API uses a strongly typed enumerator for its
251 	capability, it will fail if the user tries to map a non-physically
262 	the driver may specify various platform-dependent flags to restrict
289 	primitive should be treated as read-only by the device.  If the device
295 	be treated as read-only by the driver.  If the driver needs to write
355 the returned DMA address with dma_mapping_error(). A non-zero return value
398 accessed sg->address and sg->length as shown above.
446    - Before reading values that have been written by DMA from the device
448    - After writing values that will be written to the device using DMA
450    - before *and* after handing memory to the device if the memory is
481 The interpretation of DMA attributes is architecture-specific, and
482 each attribute should be documented in :doc:`/core-api/dma-attributes`.
485 is identical to those of the corresponding function
493 	#include <linux/dma-mapping.h>
494 	/* DMA_ATTR_FOO should be defined in linux/dma-mapping.h and
495 	* documented in Documentation/core-api/dma-attributes.rst */
519 Part II - Non-coherent DMA allocations
520 --------------------------------------
575 This routine allocates a region of <size> bytes of non-coherent memory.  It
624 Part III - Debug drivers use of the DMA-API
625 -------------------------------------------
627 The DMA-API as described above has some constraints. DMA addresses must be
628 released with the corresponding function with the same size for example. With
633 To debug drivers and find bugs in the usage of the DMA-API checking code can
636 debugging of DMA-API usage" option in your kernel configuration. Enabling this
644 	WARNING: at /data2/repos/linux-2.6-iommu/lib/dma-debug.c:448
647 	forcedeth 0000:00:08.0: DMA-API: device driver frees DMA memory with wrong
648 		function [device address=0x00000000640444be] [size=66 bytes] [mapped as
651 	Pid: 0, comm: swapper Tainted: G        W  2.6.28-dmatest-09289-g8bb99c0 #1
672 	<EOI> <4>---[ end trace f6435a98e2a38c0e ]---
675 of the DMA-API call which caused this warning.
683 The debugfs directory for the DMA-API debugging code is called dma-api/. In
687 dma-api/all_errors		This file contains a numeric value. If this
693 dma-api/disabled		This read-only file contains the character 'Y'
698 dma-api/dump			This read-only file contains current DMA
701 dma-api/error_count		This file is read-only and shows the total
704 dma-api/num_errors		The number in this file shows how many
710 dma-api/min_free_entries	This read-only file can be read to get the
716 dma-api/num_free_entries	The current number of free dma_debug_entries
719 dma-api/nr_total_entries	The total number of dma_debug_entries in the
722 dma-api/driver_filter		You can write a name of a driver into this file
731 'dma_debug=off' as a boot parameter. This will disable DMA-API debugging.
741 out of dma_debug_entries and was unable to allocate more on-demand. 65536
742 entries are preallocated at boot - if this is too low for you boot with
756 dma-debug interface debug_dma_mapping_error() to debug drivers that fail