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-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 ------------------------------------
215 addition, for high-rate short-lived streaming mappings, the upfront time
237 Part Id - Streaming DMA mappings
238 --------------------------------
263 	Further, contiguous kernel virtual space may not be contiguous as
265 	capability, it will fail if the user tries to map a non-physically
266 	contiguous piece of memory.  For this reason, memory to be mapped by
268 	physically contiguous (like kmalloc).
276 	the driver may specify various platform-dependent flags to restrict
303 	primitive should be treated as read-only by the device.  If the device
309 	be treated as read-only by the driver.  If the driver needs to write
369 the returned DMA address with dma_mapping_error(). A non-zero return value
407 physically contiguous) and returns the actual number of sg entries it
412 accessed sg->address and sg->length as shown above.
449 Synchronise a single contiguous or scatter/gather mapping for the CPU
460    - Before reading values that have been written by DMA from the device
462    - After writing values that will be written to the device using DMA
464    - before *and* after handing memory to the device if the memory is
495 The interpretation of DMA attributes is architecture-specific, and
497 Documentation/core-api/dma-attributes.rst.
508 	#include <linux/dma-mapping.h>
509 	/* DMA_ATTR_FOO should be defined in linux/dma-mapping.h and
510 	* documented in Documentation/core-api/dma-attributes.rst */
534 Part II - Non-coherent DMA allocations
535 --------------------------------------
550 This routine allocates a region of <size> bytes of non-coherent memory.  It
619 This routine allocates  <size> bytes of non-coherent and possibly non-contiguous
625 indicated by sgt->nents, but it might have multiple CPU side segments as
626 indicated by sgt->orig_nents.
659 Return a contiguous kernel mapping for an allocation returned from
664 Once a non-contiguous allocation is mapped using this function, the
707 Part III - Debug drivers use of the DMA-API
708 -------------------------------------------
710 The DMA-API as described above has some constraints. DMA addresses must be
716 To debug drivers and find bugs in the usage of the DMA-API checking code can
719 debugging of DMA-API usage" option in your kernel configuration. Enabling this
727 	WARNING: at /data2/repos/linux-2.6-iommu/lib/dma-debug.c:448
730 	forcedeth 0000:00:08.0: DMA-API: device driver frees DMA memory with wrong
734 	Pid: 0, comm: swapper Tainted: G        W  2.6.28-dmatest-09289-g8bb99c0 #1
755 	<EOI> <4>---[ end trace f6435a98e2a38c0e ]---
758 of the DMA-API call which caused this warning.
766 The debugfs directory for the DMA-API debugging code is called dma-api/. In
770 dma-api/all_errors		This file contains a numeric value. If this
776 dma-api/disabled		This read-only file contains the character 'Y'
781 dma-api/dump			This read-only file contains current DMA
784 dma-api/error_count		This file is read-only and shows the total
787 dma-api/num_errors		The number in this file shows how many
793 dma-api/min_free_entries	This read-only file can be read to get the
799 dma-api/num_free_entries	The current number of free dma_debug_entries
802 dma-api/nr_total_entries	The total number of dma_debug_entries in the
805 dma-api/driver_filter		You can write a name of a driver into this file
814 'dma_debug=off' as a boot parameter. This will disable DMA-API debugging.
824 out of dma_debug_entries and was unable to allocate more on-demand. 65536
825 entries are preallocated at boot - if this is too low for you boot with
839 dma-debug interface debug_dma_mapping_error() to debug drivers that fail