Documentation/core-api/dma-api.rst

8 of the API (and actual examples), see Documentation/core-api/dma-api-howto.rst.
11 Part II describes extensions for supporting non-coherent memory
13 non-coherent 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 ------------------------------------------
36 Coherent memory is memory for which a write by either the device or
42 This routine allocates a region of <size> bytes of coherent memory.
51 Note: coherent memory can be expensive on some platforms, and the
53 consolidate your requests for coherent memory as much as possible.
66 Free a previously allocated region of coherent memory.  dev, size and dma_handle
74 Part Ib - Using small DMA-coherent buffers
75 ------------------------------------------
79 Many drivers need lots of small DMA-coherent memory regions for DMA
82 much like a struct kmem_cache, except that they use the DMA-coherent allocator,
84 for alignment, like queue heads needing to be aligned on N-byte boundaries.
86 .. kernel-doc:: mm/dmapool.c
89 .. kernel-doc:: include/linux/dmapool.h
92 Part Ic - DMA addressing limitations
93 ------------------------------------
108 Updates both streaming and coherent DMA masks.
126 Updates only the coherent DMA mask.
162 addition, for high-rate short-lived streaming mappings, the upfront time
184 Part Id - Streaming DMA mappings
185 --------------------------------
229 	capability, it will fail if the user tries to map a non-physically
250 	primitive should be treated as read-only by the device.  If the device
256 	be treated as read-only by the driver.  If the driver needs to write
315 the returned DMA address with dma_mapping_error(). A non-zero return value
357 accessed sg->address and sg->length as shown above.
405    - Before reading values that have been written by DMA from the device
407    - After writing values that will be written to the device using DMA
409    - before *and* after handing memory to the device if the memory is
440 The interpretation of DMA attributes is architecture-specific, and
442 Documentation/core-api/dma-attributes.rst.
453 	#include <linux/dma-mapping.h>
454 	/* DMA_ATTR_FOO should be defined in linux/dma-mapping.h and
455 	* documented in Documentation/core-api/dma-attributes.rst */
478 Part Ie - IOVA-based DMA mappings
479 ---------------------------------
500 Can be used by the driver to check if the IOVA-based API is used after a
520 Must be called to sync the IOMMU page tables for IOVA-range mapped by one or
523 For drivers that use a one-shot mapping, all ranges can be unmapped and the
550 Part II - Non-coherent DMA allocations
551 --------------------------------------
566 This routine allocates a region of <size> bytes of non-coherent memory.  It
635 This routine allocates  <size> bytes of non-coherent and possibly non-contiguous
641 indicated by sgt->nents, but it might have multiple CPU side segments as
642 indicated by sgt->orig_nents.
680 Once a non-contiguous allocation is mapped using this function, the
723 Part III - Debug drivers use of the DMA API
724 -------------------------------------------
743 	WARNING: at /data2/repos/linux-2.6-iommu/lib/dma-debug.c:448
746 	forcedeth 0000:00:08.0: DMA-API: device driver frees DMA memory with wrong
750 	Pid: 0, comm: swapper Tainted: G        W  2.6.28-dmatest-09289-g8bb99c0 #1
771 	<EOI> <4>---[ end trace f6435a98e2a38c0e ]---
782 The debugfs directory for the DMA API debugging code is called dma-api/. In
786 dma-api/all_errors		This file contains a numeric value. If this
792 dma-api/disabled		This read-only file contains the character 'Y'
797 dma-api/dump			This read-only file contains current DMA
800 dma-api/error_count		This file is read-only and shows the total
803 dma-api/num_errors		The number in this file shows how many
809 dma-api/min_free_entries	This read-only file can be read to get the
815 dma-api/num_free_entries	The current number of free dma_debug_entries
818 dma-api/nr_total_entries	The total number of dma_debug_entries in the
821 dma-api/driver_filter		You can write a name of a driver into this file
840 out of dma_debug_entries and was unable to allocate more on-demand. 65536
841 entries are preallocated at boot - if this is too low for you boot with
855 dma-debug interface debug_dma_mapping_error() to debug drivers that fail
867 .. kernel-doc:: include/linux/scatterlist.h
868 .. kernel-doc:: lib/scatterlist.c