linux/Documentation/DMA-attributes.txt
<<
n va6.3/spa 6.3/form 6.3a n va6. href="../linux+v3.8.5/Documenta > /DMA-attributes.txt">n va6.3img src="../.sta c/gfx/right.png" alt=">>">n 3/spa n 3spa class="lxr_search">n va ="+search" method="post" onsubmit="return do_search(this);">n va6.3input typn> hidden" namn> navtarget" ption> ">n va6.3input typn> text" namn> search" id> search">n va6.3butt submit">Searchn va6.Prefs 6.3/a>n 3/spa va6. .3/div va6. .3form ac > ="ajax+*" method="post" onsubmit="return false;">n 3input typn> hidden" namn> ajax_lookup" id> ajax_lookup" ption> ">nva6. .3/form nva6. .3div class="headingbott
search_results" class="search_results" 6 va6. .3/div 3div id> content" 3div id> file_contents"
9d/e0/6879e4727a8b9962cab787aeb29c7ee5d76e_3/0" 
L1" class="line" namn>
L1">. .13/a>                        DMA attributes

L2" class="line" namn>
L2">. .23/a>                        ==============

L3" class="line" namn>
L3">. .33/a>n
L4" class="line" namn>
L4">. .43/a>This document describes the seman  cs of the DMA attributes that aren
L5" class="line" namn>
L5">. .53/a>defined in linux/dma-attrs.h.n
L6" class="line" namn>
L6">. .63/a>n
L7" class="line" namn>
L7">. .73/a>DMA_ATTR_WRITE_BARRIERn
L8" class="line" namn>
L8">. .83/a>----------------------n
L9" class="line" namn>
L9">. .93/a>n
L10" class="line" namn>
L10">. .10"a>DMA_ATTR_WRITE_BARRIER is a (write) barrier attribute for DMA.  DMAn
L11" class="line" namn>
L11">. 113/a>to a memory reg2
L12" class="line" namn>
L12">. 123/a>all pending DMA writes to complete, and thus provides a mechanism to

L13" class="line" namn>
L13">. 133/a>strictly order DMA from a device across all intervening busses and

L14" class="line" namn>
L14">. 143/a>bridges.  This barrier is not specific to a par  cular typn of

L15" class="line" namn>
L15">. 153/a>interconnect, it applies to the system as a whole, and so its

L16" class="line" namn>
L16">. 163/a>implementa  >
 must account for the idiosyncracies of the system all

L17" class="line" namn>
L17">. 173/a>the way from the DMA device to memory.n
L18" class="line" namn>
L18">. 183/a>n
L19" class="line" namn>
L19">. 193/a>As an example of a situa  >
 where DMA_ATTR_WRITE_BARRIER would ben
L20" class="line" namn>
L20">. 210"a>useful, suppose that a device does a DMA write to indicate that data isn
L21" class="line" namn>
L21">. 213/a>ready and available in memory.  The DMA of the "complet >
 indicat >
"n
L22" class="line" namn>
L22">. 223/a>could raceowith data DMA.  Mapping the memory used for complet >
n
L23" class="line" namn>
L23">. 233/a>indicat >
sowith DMA_ATTR_WRITE_BARRIER would prevent the race.n
L24" class="line" namn>
L24">. 243/a>n
L25" class="line" namn>
L25">. 250"a>DMA_ATTR_WEAK_ORDERINGn
L26" class="line" namn>
L26">. 263/a>----------------------n
L27" class="line" namn>
L27">. 273/a>n
L28" class="line" namn>
L28">. 280"a>DMA_ATTR_WEAK_ORDERING specifies that reads and writes to the mappingn
L29" class="line" namn>
L29">. 293/a>may beoweakly ordered, that is that reads and writes may pass each other.n
L30" class="line" namn>
L30">. 303/a>n
L31" class="line" namn>
L31">. 313/a>Sinceoit is 
	  >
al for platforms to implement DMA_ATTR_WEAK_ORDERING,n
L32" class="line" namn>
L32">. 323/a>those that do not will simply ignore the attribute and exhibit defaultn
L33" class="line" namn>
L33">. 333/a>behavior.n
L34" class="line" namn>
L34">. 343/a>n
L35" class="line" namn>
L35">. 350"a>DMA_ATTR_WRITE_COMBINEn
L36" class="line" namn>
L36">. 363/a>----------------------n
L37" class="line" namn>
L37">. 373/a>n
L38" class="line" namn>
L38">. 380"a>DMA_ATTR_WRITE_COMBINE specifies that writes to the mapping may ben
L39" class="line" namn>
L39">. 393/a>buffered to improve performance.n
L40" class="line" namn>
L40">. 403/a>n
L41" class="line" namn>
L41">. 413/a>Sinceoit is 
	  >
al for platforms to implement DMA_ATTR_WRITE_COMBINE,n
L42" class="line" namn>
L42">. 423/a>those that do not will simply ignore the attribute and exhibit defaultn
L43" class="line" namn>
L43">. 433/a>behavior.n
L44" class="line" namn>
L44">. 443/a>n
L45" class="line" namn>
L45">. 450"a>DMA_ATTR_NON_CONSISTENTn
L46" class="line" namn>
L46">. 463/a>-----------------------n
L47" class="line" namn>
L47">. 473/a>n
L48" class="line" namn>
L48">. 480"a>DMA_ATTR_NON_CONSISTENT lets the platform to choose to return eithern
L49" class="line" namn>
L49">. 493/a>consistent or non-consistent memory asoit sees fit.  By using this API,n
L50" class="line" namn>
L50">. 503/a>you are guaranteeing to the platform that you have all the correct and

L51" class="line" namn>
L51">. 513/a>necessary sync points for this memory in the driver.n
L52" class="line" namn>
L52">. 523/a>n
L53" class="line" namn>
L53">. 530"a>DMA_ATTR_NO_KERNEL_MAPPINGn
L54" class="line" namn>
L54">. 543/a>--------------------------n
L55" class="line" namn>
L55">. 553/a>n
L56" class="line" namn>
L56">. 560"a>DMA_ATTR_NO_KERNEL_MAPPING lets the platform to avoid creating a kernel

L57" class="line" namn>
L57">. 573/a>virtual mapping for the allocated buffer. On some architectures creating

L58" class="line" namn>
L58">. 580"a>such mapping is non-trivial task and consumes very limited resources

L59" class="line" namn>
L59">. 593/a>(like kernel virtual address spaceoor dma consistent address space).n
L60" class="line" namn>
L60">. 603/a>Buffers allocated with this attribute can beoonly passed to user spacen
L61" class="line" namn>
L61">. 613/a>by calling dma_mmap_attrs(). By using this API, you are guaranteeingn
L62" class="line" namn>
L62">. 623/a>that you won't dereferenceothe pointer returned by dma_alloc_attr(). Youn
L63" class="line" namn>
L63">. 630"a>can threat it as a cookie that must beopassed to dma_mmap_attrs() and

L64" class="line" namn>
L64">. 643/a>dma_free_attrs(). Make sure that both of these also get this attribute

L65" class="line" namn>
L65">. 653/a>set on each call.n
L66" class="line" namn>
L66">. 663/a>n
L67" class="line" namn>
L67">. 673/a>Sinceoit is 
	  >
al for platforms to implementn
L68" class="line" namn>
L68">. 680"a>DMA_ATTR_NO_KERNEL_MAPPING, those that do not will simply ignore then
L69" class="line" namn>
L69">. 693/a>attribute and exhibit default behavior.n
L70" class="line" namn>
L70">. 703/a>n
L71" class="line" namn>
L71">. 710"a>DMA_ATTR_SKIP_CPU_SYNCn
L72" class="line" namn>
L72">. 723/a>----------------------n
L73" class="line" namn>
L73">. 733/a>n
L74" class="line" namn>
L74">. 743/a>By default dma_map_{single,page,sg} funct >
sofamily transfer a give
n
L75" class="line" namn>
L75">. 753/a>buffer from CPU domain to device domain. Some advanced use cases mightn
L76" class="line" namn>
L76">. 763/a>require sharing a buffer between more than one device. This requires

L77" class="line" namn>
L77">. 773/a>having a mapping created separately for each device and is usually

L78" class="line" namn>
L78">. 780"a>performed by calling dma_map_{single,page,sg} funct >
 more than oncen
L79" class="line" namn>
L79">. 793/a>for the give
 buffer with device pointer to each device taking par  inn
L80" class="line" namn>
L80">. 803/a>the buffer sharing. The first call transfers a buffer from 'CPU' domainn
L81" class="line" namn>
L81">. 813/a>to 'device' domain, what synchronizes CPU caches for the give
 reg2
L82" class="line" namn>
L82">. 823/a>(usuallyoit means that the cache has been flushed or invalidatedn
L83" class="line" namn>
L83">. 833/a>depending on the dma direct >
). However, next calls to

L84" class="line" namn>
L84">. 843/a>dma_map_{single,page,sg}() for other devices will perform exactly then
L85" class="line" namn>
L85">. 853/a>samn sychroniza  >
 opera  >
 on the CPU cache. CPU cache sychroniza  >
n
L86" class="line" namn>
L86">. 863/a>might beoa time consuming opera  >
, especiallyoif the buffers aren
L87" class="line" namn>
L87">. 873/a>large, so it is highly recommended to avoid it if possible.n
L88" class="line" namn>
L88">. 880"a>DMA_ATTR_SKIP_CPU_SYNC allows platform code to skip synchroniza  >
 of

L89" class="line" namn>
L89">. 893/a>the CPU cache for the give
 buffer assuming that it has been alreadyn
L90" class="line" namn>
L90">. 903/a>transferred to 'device' domain. This attribute can beoalso used forn
L91" class="line" namn>
L91">. 913/a>dma_unmap_{single,page,sg} funct >
sofamily to force buffer to stay inn
L92" class="line" namn>
L92">. 923/a>device domain after releasing a mapping for it. Use this attribute withn
L93" class="line" namn>
L93">. 930"a>care!n
L94" class="line" namn>
L94">. 943/a>n
L95" class="line" namn>
L95">. 950"a>DMA_ATTR_FORCE_CONTIGUOUSn
L96" class="line" namn>
L96">. 963/a>-------------------------n
L97" class="line" namn>
L97">. 973/a>n
L98" class="line" namn>
L98">. 983/a>By default DMA-mapping subsystem is allowed to assemble the buffern
L99" class="line" namn>
L99">. 993/a>allocated by dma_alloc_attrs() funct >
 from individual pages if it cann
L100" class="line" namn>
L100">.1003/a>be mapped as contiguous chunk into device dma address space. Byn
L101" class="line" namn>
L101">.1013/a>specifing this attribute the allocated buffer is forced to be contiguousn
L102" class="line" namn>
L102">.1023/a>also in physical memory.n
L103" class="line" namn>
L103">.1030"a>
The origi al LXR software by the.3a href="http://sourceforge.net/projects/lxr">LXR community0"a>, this experimental vers > by 3a href="mailto:lxr@linux.no">lxr@linux.no0"a>. 3/div 3div class="subfooter"> lxr.linux.no kindly hosted by 3a href="http://www.redpill-linpro.no">Redpill Linpro AS0"a>, provider of Linux consulting and opera > s services sinceo1995. 3/div 3/body 3/html