<?xml version="1.0" encoding="ANSI_X3.4-1968" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968" /><title>usb_buffer_alloc</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" href="index.html" title="The Linux-USB Host Side API" /><link rel="up" href="ch05.html" title="Chapter 5. USB Core APIs" /><link rel="prev" href="re96.html" title="usb_get_current_frame_number" /><link rel="next" href="re98.html" title="usb_buffer_free" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center"><span>usb_buffer_alloc</span></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="re96.html">Prev</a> </td><th width="60%" align="center">Chapter 5. USB Core APIs</th><td width="20%" align="right"> <a accesskey="n" href="re98.html">Next</a></td></tr></table><hr /></div><div class="refentry" title="usb_buffer_alloc"><a id="API-usb-buffer-alloc"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>usb_buffer_alloc —
allocate dma-consistent buffer for URB_NO_xxx_DMA_MAP
</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void * <b class="fsfunc">usb_buffer_alloc </b>(</code></td><td>struct usb_device * <var class="pdparam">dev</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td> </td><td>gfp_t <var class="pdparam">mem_flags</var>, </td></tr><tr><td> </td><td>dma_addr_t * <var class="pdparam">dma</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Arguments"><a id="id2752539"></a><h2>Arguments</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>dev</code></em></span></dt><dd><p>
device the buffer will be used with
</p></dd><dt><span class="term"><em class="parameter"><code>size</code></em></span></dt><dd><p>
requested buffer size
</p></dd><dt><span class="term"><em class="parameter"><code>mem_flags</code></em></span></dt><dd><p>
affect whether allocation may block
</p></dd><dt><span class="term"><em class="parameter"><code>dma</code></em></span></dt><dd><p>
used to return DMA address of buffer
</p></dd></dl></div></div><div class="refsect1" title="Description"><a id="id2752615"></a><h2>Description</h2><p>
Return value is either null (indicating no buffer could be allocated), or
the cpu-space pointer to a buffer that may be used to perform DMA to the
specified device. Such cpu-space buffers are returned along with the DMA
address (through the pointer provided).
</p><p>
These buffers are used with URB_NO_xxx_DMA_MAP set in urb->transfer_flags
to avoid behaviors like using <span class="quote">“<span class="quote">DMA bounce buffers</span>”</span>, or thrashing IOMMU
hardware during URB completion/resubmit. The implementation varies between
platforms, depending on details of how DMA will work to this device.
Using these buffers also eliminates cacheline sharing problems on
architectures where CPU caches are not DMA-coherent. On systems without
bus-snooping caches, these buffers are uncached.
</p><p>
When the buffer is no longer used, free it with <code class="function">usb_buffer_free</code>.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="re96.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch05.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="re98.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span>usb_get_current_frame_number</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> <span>usb_buffer_free</span></td></tr></table></div></body></html>
