<!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/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>libbladeRF: Asynchronous data transmission and reception</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { init_search(); });
</script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
extensions: ["tex2jax.js"],
jax: ["input/TeX","output/HTML-CSS"],
});
</script><script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><img alt="Logo" src="logo.png"/></td>
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">libbladeRF
 <span id="projectnumber">1.7.2</span>
</div>
<div id="projectbrief">Nuand bladeRF library</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.11 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="modules.html"><span>API Sections</span></a></li>
<li>
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="summary">
<a href="#define-members">Macros</a> |
<a href="#typedef-members">Typedefs</a> |
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">Asynchronous data transmission and reception</div> </div>
</div><!--header-->
<div class="contents">
<a name="details" id="details"></a><h2 class="groupheader">Description</h2>
<p>This interface gives the API user full control over the stream and buffer management, at the cost of added complexity.</p>
<p>New users are recommended to first evaluate the <a class="el" href="group___f_n___d_a_t_a___s_y_n_c.html">Synchronous data transmission and reception</a> interface, and to only use this interface if the former is found to not yield suitable performance.</p>
<p>These functions are either thread-safe or may be used in a thread-safe manner (per the details noted in the function description). </p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="define-members"></a>
Macros</h2></td></tr>
<tr class="memitem:gaa65843b8e8c9dd17cc3ce851a9c6d70f"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#gaa65843b8e8c9dd17cc3ce851a9c6d70f">BLADERF_STREAM_SHUTDOWN</a>   (NULL)</td></tr>
<tr class="separator:gaa65843b8e8c9dd17cc3ce851a9c6d70f"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga0f252bf68c3253a1997b331f994fa72c"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga0f252bf68c3253a1997b331f994fa72c">BLADERF_STREAM_NO_DATA</a>   ((void*)(-1))</td></tr>
<tr class="separator:ga0f252bf68c3253a1997b331f994fa72c"><td class="memSeparator" colspan="2"> </td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="typedef-members"></a>
Typedefs</h2></td></tr>
<tr class="memitem:ga8a0fcc22ce61e80d20186e5e081a8be7"><td class="memItemLeft" align="right" valign="top">typedef void *(* </td><td class="memItemRight" valign="bottom"><a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga8a0fcc22ce61e80d20186e5e081a8be7">bladerf_stream_cb</a>) (struct bladerf *dev, struct <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga4c5ac0ae2bd3c36b9078f3ce47cb71fd">bladerf_stream</a> *stream, struct <a class="el" href="structbladerf__metadata.html">bladerf_metadata</a> *meta, void *samples, size_t num_samples, void *user_data)</td></tr>
<tr class="separator:ga8a0fcc22ce61e80d20186e5e081a8be7"><td class="memSeparator" colspan="2"> </td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga72752f2a047b95544e7686596a409abd"><td class="memItemLeft" align="right" valign="top"><a class="el" href="libblade_r_f_8h.html#a5e3652cae8b48c1ad174f0b06bbd06d0">API_EXPORT</a> int <a class="el" href="libblade_r_f_8h.html#a66285a1fe575693f5f275b212891222e">CALL_CONV</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga72752f2a047b95544e7686596a409abd">bladerf_init_stream</a> (struct <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga4c5ac0ae2bd3c36b9078f3ce47cb71fd">bladerf_stream</a> **stream, struct bladerf *dev, <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga8a0fcc22ce61e80d20186e5e081a8be7">bladerf_stream_cb</a> callback, void ***buffers, size_t num_buffers, <a class="el" href="group___f_m_t___m_e_t_a.html#ga4c61587834fd4de51a8e2d34e14a73b2">bladerf_format</a> format, size_t samples_per_buffer, size_t num_transfers, void *user_data)</td></tr>
<tr class="separator:ga72752f2a047b95544e7686596a409abd"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga4c5ac0ae2bd3c36b9078f3ce47cb71fd"><td class="memItemLeft" align="right" valign="top"><a class="el" href="libblade_r_f_8h.html#a5e3652cae8b48c1ad174f0b06bbd06d0">API_EXPORT</a> int <a class="el" href="libblade_r_f_8h.html#a66285a1fe575693f5f275b212891222e">CALL_CONV</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga4c5ac0ae2bd3c36b9078f3ce47cb71fd">bladerf_stream</a> (struct bladerf_stream *stream, <a class="el" href="group___f_n___m_o_d_u_l_e.html#gab12571146a3d4c5d79ac497a74b3fb5e">bladerf_module</a> module)</td></tr>
<tr class="separator:ga4c5ac0ae2bd3c36b9078f3ce47cb71fd"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gae0f45c213ace4619f23901b0b7aeeb21"><td class="memItemLeft" align="right" valign="top"><a class="el" href="libblade_r_f_8h.html#a5e3652cae8b48c1ad174f0b06bbd06d0">API_EXPORT</a> int <a class="el" href="libblade_r_f_8h.html#a66285a1fe575693f5f275b212891222e">CALL_CONV</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#gae0f45c213ace4619f23901b0b7aeeb21">bladerf_submit_stream_buffer</a> (struct <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga4c5ac0ae2bd3c36b9078f3ce47cb71fd">bladerf_stream</a> *stream, void *buffer, unsigned int timeout_ms)</td></tr>
<tr class="separator:gae0f45c213ace4619f23901b0b7aeeb21"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga0d41def78ee90074575c8b6cff3a9283"><td class="memItemLeft" align="right" valign="top"><a class="el" href="libblade_r_f_8h.html#a5e3652cae8b48c1ad174f0b06bbd06d0">API_EXPORT</a> int <a class="el" href="libblade_r_f_8h.html#a66285a1fe575693f5f275b212891222e">CALL_CONV</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga0d41def78ee90074575c8b6cff3a9283">bladerf_submit_stream_buffer_nb</a> (struct <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga4c5ac0ae2bd3c36b9078f3ce47cb71fd">bladerf_stream</a> *stream, void *buffer)</td></tr>
<tr class="separator:ga0d41def78ee90074575c8b6cff3a9283"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga43562b4761905b40b0fb42ef0547c019"><td class="memItemLeft" align="right" valign="top"><a class="el" href="libblade_r_f_8h.html#a5e3652cae8b48c1ad174f0b06bbd06d0">API_EXPORT</a> void <a class="el" href="libblade_r_f_8h.html#a66285a1fe575693f5f275b212891222e">CALL_CONV</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga43562b4761905b40b0fb42ef0547c019">bladerf_deinit_stream</a> (struct <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga4c5ac0ae2bd3c36b9078f3ce47cb71fd">bladerf_stream</a> *stream)</td></tr>
<tr class="separator:ga43562b4761905b40b0fb42ef0547c019"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga6c02d821bcdc2b732ef598fe76d98c6b"><td class="memItemLeft" align="right" valign="top"><a class="el" href="libblade_r_f_8h.html#a5e3652cae8b48c1ad174f0b06bbd06d0">API_EXPORT</a> int <a class="el" href="libblade_r_f_8h.html#a66285a1fe575693f5f275b212891222e">CALL_CONV</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga6c02d821bcdc2b732ef598fe76d98c6b">bladerf_set_stream_timeout</a> (struct bladerf *dev, <a class="el" href="group___f_n___m_o_d_u_l_e.html#gab12571146a3d4c5d79ac497a74b3fb5e">bladerf_module</a> module, unsigned int timeout)</td></tr>
<tr class="separator:ga6c02d821bcdc2b732ef598fe76d98c6b"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga232cf6ba9da133507e59a945f0db27dc"><td class="memItemLeft" align="right" valign="top"><a class="el" href="libblade_r_f_8h.html#a5e3652cae8b48c1ad174f0b06bbd06d0">API_EXPORT</a> int <a class="el" href="libblade_r_f_8h.html#a66285a1fe575693f5f275b212891222e">CALL_CONV</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga232cf6ba9da133507e59a945f0db27dc">bladerf_get_stream_timeout</a> (struct bladerf *dev, <a class="el" href="group___f_n___m_o_d_u_l_e.html#gab12571146a3d4c5d79ac497a74b3fb5e">bladerf_module</a> module, unsigned int *timeout)</td></tr>
<tr class="separator:ga232cf6ba9da133507e59a945f0db27dc"><td class="memSeparator" colspan="2"> </td></tr>
</table>
<h2 class="groupheader">Macro Definition Documentation</h2>
<a class="anchor" id="ga0f252bf68c3253a1997b331f994fa72c"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define BLADERF_STREAM_NO_DATA   ((void*)(-1))</td>
</tr>
</table>
</div><div class="memdoc">
<p>Use this value in a stream callback to indicate that no buffer is being provided. In this case, buffers are expected to be provided via <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#gae0f45c213ace4619f23901b0b7aeeb21">bladerf_submit_stream_buffer()</a>. </p>
<p>Definition at line <a class="el" href="libblade_r_f_8h_source.html#l03035">3035</a> of file <a class="el" href="libblade_r_f_8h_source.html">libbladeRF.h</a>.</p>
</div>
</div>
<a class="anchor" id="gaa65843b8e8c9dd17cc3ce851a9c6d70f"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define BLADERF_STREAM_SHUTDOWN   (NULL)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Use this as a return value in callbacks or as the buffer parameter to <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#gae0f45c213ace4619f23901b0b7aeeb21">bladerf_submit_stream_buffer()</a> to shutdown a stream. </p>
<p>Definition at line <a class="el" href="libblade_r_f_8h_source.html#l03028">3028</a> of file <a class="el" href="libblade_r_f_8h_source.html">libbladeRF.h</a>.</p>
</div>
</div>
<h2 class="groupheader">Typedef Documentation</h2>
<a class="anchor" id="ga8a0fcc22ce61e80d20186e5e081a8be7"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef void*(* bladerf_stream_cb) (struct bladerf *dev, struct <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga4c5ac0ae2bd3c36b9078f3ce47cb71fd">bladerf_stream</a> *stream, struct <a class="el" href="structbladerf__metadata.html">bladerf_metadata</a> *meta, void *samples, size_t num_samples, void *user_data)</td>
</tr>
</table>
</div><div class="memdoc">
<p>This typedef represents a callback function that is executed in response to this interface's asynchronous events.</p>
<p>Stream callbacks <b>must not</b> block or perform long-running operations. Otherwise, timeouts may occur. If this cannot be guaranteed, consider returning BLADERF_STREAM_NO_DATA in callbacks and later submit a buffer using <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#gae0f45c213ace4619f23901b0b7aeeb21">bladerf_submit_stream_buffer()</a>. However, callbacks should always take a single approach of returning buffers <b>or</b> returning BLADERF_STREAM_NO_DATA and submitting buffers later – <b>but not both</b>.</p>
<p>When running in a full-duplex mode of operation with simultaneous TX and RX stream threads, be aware that one module's callback may occur in the context of another module's thread. The API user is responsible for ensuring their callbacks are thread safe. For example, when managing access to sample buffers, the caller must ensure that if one thread is processing samples in a buffer, that this buffer is not returned via the callback's return value.</p>
<p>As of libbladeRF v0.15.0, is guaranteed that only one callback from a module will occur at a time. (i.e., a second TX callback will not fire while one is currently being handled.) To achieve this, while a callback is executing, a per-stream lock is held. It is important to consider this when thinking about the order of lock acquisitions both in the callbacks, and the code surrounding <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#gae0f45c213ace4619f23901b0b7aeeb21">bladerf_submit_stream_buffer()</a>.</p>
<p><b>Note:</b>Do not call <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#gae0f45c213ace4619f23901b0b7aeeb21">bladerf_submit_stream_buffer()</a> from a callback.</p>
<p>For both RX and TX, the stream callback receives:</p><ul>
<li>dev: Device structure</li>
<li>stream: The associated stream</li>
<li>metadata: For future support - do not attempt to read/write this in the current library implementation.</li>
<li>user_data: User data provided when initializing stream</li>
</ul>
<p>For TX callbacks:</p><ul>
<li>samples: Pointer to buffer of samples that was sent</li>
<li>num_samples: Number of sent in last transfer and to send in next transfer</li>
<li>Return value: The user specifies the address of the next buffer to send, BLADERF_STREAM_SHUTDOWN, or BLADERF_STREAM_NO_DATA.</li>
</ul>
<p>For RX callbacks:</p><ul>
<li>samples: Buffer filled with received data</li>
<li>num_samples: Number of samples received and size of next buffers</li>
<li>Return value: The user specifies the next buffer to fill with RX data, which should be <code>num_samples</code> in size, BLADERF_STREAM_SHUTDOWN, or BLADERF_STREAM_NO_DATA. </li>
</ul>
<p>Definition at line <a class="el" href="libblade_r_f_8h_source.html#l03088">3088</a> of file <a class="el" href="libblade_r_f_8h_source.html">libbladeRF.h</a>.</p>
</div>
</div>
<h2 class="groupheader">Function Documentation</h2>
<a class="anchor" id="ga43562b4761905b40b0fb42ef0547c019"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="libblade_r_f_8h.html#a5e3652cae8b48c1ad174f0b06bbd06d0">API_EXPORT</a> void <a class="el" href="libblade_r_f_8h.html#a66285a1fe575693f5f275b212891222e">CALL_CONV</a> bladerf_deinit_stream </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga4c5ac0ae2bd3c36b9078f3ce47cb71fd">bladerf_stream</a> * </td>
<td class="paramname"><em>stream</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Deinitialize and deallocate stream resources.</p>
<dl class="section pre"><dt>Precondition</dt><dd>Stream is no longer being used (via <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#gae0f45c213ace4619f23901b0b7aeeb21">bladerf_submit_stream_buffer()</a> or <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga4c5ac0ae2bd3c36b9078f3ce47cb71fd">bladerf_stream()</a> calls.) </dd></dl>
<dl class="section post"><dt>Postcondition</dt><dd>Stream is deallocated and may no longer be used.</dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">stream</td><td>Stream to deinitialize. This function does nothing if stream is NULL. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="ga232cf6ba9da133507e59a945f0db27dc"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="libblade_r_f_8h.html#a5e3652cae8b48c1ad174f0b06bbd06d0">API_EXPORT</a> int <a class="el" href="libblade_r_f_8h.html#a66285a1fe575693f5f275b212891222e">CALL_CONV</a> bladerf_get_stream_timeout </td>
<td>(</td>
<td class="paramtype">struct bladerf * </td>
<td class="paramname"><em>dev</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group___f_n___m_o_d_u_l_e.html#gab12571146a3d4c5d79ac497a74b3fb5e">bladerf_module</a> </td>
<td class="paramname"><em>module</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned int * </td>
<td class="paramname"><em>timeout</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Get transfer timeout in milliseconds</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">dev</td><td>Device handle </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">module</td><td>Module to adjust </td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">timeout</td><td>On success, updated with current transfer timeout value. Undefined on failure.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 on success, value from <a class="el" href="group___r_e_t_c_o_d_e_s.html">Error codes</a> list on failure </dd></dl>
</div>
</div>
<a class="anchor" id="ga72752f2a047b95544e7686596a409abd"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="libblade_r_f_8h.html#a5e3652cae8b48c1ad174f0b06bbd06d0">API_EXPORT</a> int <a class="el" href="libblade_r_f_8h.html#a66285a1fe575693f5f275b212891222e">CALL_CONV</a> bladerf_init_stream </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga4c5ac0ae2bd3c36b9078f3ce47cb71fd">bladerf_stream</a> ** </td>
<td class="paramname"><em>stream</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct bladerf * </td>
<td class="paramname"><em>dev</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga8a0fcc22ce61e80d20186e5e081a8be7">bladerf_stream_cb</a> </td>
<td class="paramname"><em>callback</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void *** </td>
<td class="paramname"><em>buffers</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t </td>
<td class="paramname"><em>num_buffers</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group___f_m_t___m_e_t_a.html#ga4c61587834fd4de51a8e2d34e14a73b2">bladerf_format</a> </td>
<td class="paramname"><em>format</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t </td>
<td class="paramname"><em>samples_per_buffer</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t </td>
<td class="paramname"><em>num_transfers</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"><em>user_data</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Initialize a stream for use with asynchronous routines.</p>
<p>This function will internally allocate data buffers, which will be provided to the API user in callback functions.</p>
<p>The <code>buffers</code> output parameter populates a pointer to the list of allocated buffers. This allows the API user to implement a buffer management scheme to best suit his or her specific use case.</p>
<p>Generally, one will want to set the <code>buffers</code> parameter to a value larger than the <code>num_transfers</code> parameter, and keep track of which buffers are currently "in-flight", versus those available for use.</p>
<p>For example, for a transmit stream, modulated data can be actively written into free buffers while transfers of other buffers are occurring. Once a buffer has been filled with data, it can be marked 'in-flight' and be returned in a successive callback to transmit.</p>
<p>The choice of values for the <code>num_transfers</code> and <code>buffer_size</code> should be made based upon the desired samplerate, and the stream timeout value specified via <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga6c02d821bcdc2b732ef598fe76d98c6b">bladerf_set_stream_timeout()</a>, which defaults to 1 second.</p>
<p>For a given sample rate, the below relationship must be upheld to transmit or receive data without timeouts or dropped data.</p>
<p class="formulaDsp">
\[ Sample\ Rate > \frac{\#\ Transfers}{Timeout} \times Buffer\ Size \]
</p>
<p>...where Sample Rate is in samples per second, and Timeout is in seconds.</p>
<p>To account for general system overhead, it is recommended to multiply the righthand side by 1.1 to 1.25.</p>
<p>While increasing the number of buffers available provides additional elasticity, be aware that it also increases latency.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[out]</td><td class="paramname">stream</td><td>Upon success, this will be updated to contain a stream handle (i.e., address)</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">dev</td><td>Device to associate with the stream</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">callback</td><td>Callback routine to handle asynchronous events</td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">buffers</td><td>This will be updated to point to a dynamically allocated array of buffer pointers.</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">num_buffers</td><td>Number of buffers to allocate and return. This value must >= the <code>num_transfers</code> parameter.</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">format</td><td>Sample data format</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">samples_per_buffer</td><td>Size of allocated buffers, in units of samples Note that the physical size of the buffer is a function of this and the format parameter.</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">num_transfers</td><td>Maximum number of transfers that may be in-flight simultaneously. This must be <= the <code>num_buffers</code> parameter.</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">user_data</td><td>Caller-provided data that will be provided in stream callbacks</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>This call should be later followed by a call to <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga43562b4761905b40b0fb42ef0547c019">bladerf_deinit_stream()</a> to avoid memory leaks.</dd></dl>
<dl class="section return"><dt>Returns</dt><dd>0 on success, value from <a class="el" href="group___r_e_t_c_o_d_e_s.html">Error codes</a> list on failure </dd></dl>
</div>
</div>
<a class="anchor" id="ga6c02d821bcdc2b732ef598fe76d98c6b"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="libblade_r_f_8h.html#a5e3652cae8b48c1ad174f0b06bbd06d0">API_EXPORT</a> int <a class="el" href="libblade_r_f_8h.html#a66285a1fe575693f5f275b212891222e">CALL_CONV</a> bladerf_set_stream_timeout </td>
<td>(</td>
<td class="paramtype">struct bladerf * </td>
<td class="paramname"><em>dev</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group___f_n___m_o_d_u_l_e.html#gab12571146a3d4c5d79ac497a74b3fb5e">bladerf_module</a> </td>
<td class="paramname"><em>module</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned int </td>
<td class="paramname"><em>timeout</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Set stream transfer timeout in milliseconds</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">dev</td><td>Device handle </td></tr>
<tr><td class="paramname">module</td><td>Module to adjust </td></tr>
<tr><td class="paramname">timeout</td><td>Timeout in milliseconds</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 on success, value from <a class="el" href="group___r_e_t_c_o_d_e_s.html">Error codes</a> list on failure </dd></dl>
</div>
</div>
<a class="anchor" id="ga4c5ac0ae2bd3c36b9078f3ce47cb71fd"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="libblade_r_f_8h.html#a5e3652cae8b48c1ad174f0b06bbd06d0">API_EXPORT</a> int <a class="el" href="libblade_r_f_8h.html#a66285a1fe575693f5f275b212891222e">CALL_CONV</a> bladerf_stream </td>
<td>(</td>
<td class="paramtype">struct bladerf_stream * </td>
<td class="paramname"><em>stream</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group___f_n___m_o_d_u_l_e.html#gab12571146a3d4c5d79ac497a74b3fb5e">bladerf_module</a> </td>
<td class="paramname"><em>module</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Begin running a stream. This call will block until the steam completes.</p>
<p>Only 1 RX stream and 1 TX stream may be running at a time. Attempting to call <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga4c5ac0ae2bd3c36b9078f3ce47cb71fd">bladerf_stream()</a> with more than one stream per module will yield unexpected (and most likely undesirable) results. See the <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga8a0fcc22ce61e80d20186e5e081a8be7">bladerf_stream_cb</a> description for additional thread-safety caveats.</p>
<dl class="section pre"><dt>Precondition</dt><dd>This function should be preceded by a call to <a class="el" href="group___f_n___m_o_d_u_l_e.html#gabef14480bd8483eaf937b30a4b5eab88">bladerf_enable_module()</a> to enable the associated RX or TX module before attempting to use it to stream data.</dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">stream</td><td>A stream handle that has been successfully been initialized via <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga72752f2a047b95544e7686596a409abd">bladerf_init_stream()</a></td></tr>
<tr><td class="paramname">module</td><td>Module to perform streaming with</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 on success, value from <a class="el" href="group___r_e_t_c_o_d_e_s.html">Error codes</a> list on failure </dd></dl>
</div>
</div>
<a class="anchor" id="gae0f45c213ace4619f23901b0b7aeeb21"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="libblade_r_f_8h.html#a5e3652cae8b48c1ad174f0b06bbd06d0">API_EXPORT</a> int <a class="el" href="libblade_r_f_8h.html#a66285a1fe575693f5f275b212891222e">CALL_CONV</a> bladerf_submit_stream_buffer </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga4c5ac0ae2bd3c36b9078f3ce47cb71fd">bladerf_stream</a> * </td>
<td class="paramname"><em>stream</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"><em>buffer</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned int </td>
<td class="paramname"><em>timeout_ms</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Submit a buffer to a stream from outside of a stream callback function. Use this only when returning BLADERF_STREAM_NO_DATA from callbacks. <b>Do not</b> use this function if the associated callback functions will be returning buffers for submission.</p>
<p>This call may block if the device is not ready to submit a buffer for transfer. Use the <code>timeout_ms</code> to place an upper limit on the time this function can block.</p>
<p>To safely submit buffers from outside the stream callback flow, this function internally acquires a per-stream lock (the same one that is held during the execution of a stream callback). Therefore, it is important to be aware of locks that may be held while making this call, especially those acquired during execution of the associated stream callback function. (i.e., be wary of the order of lock acquisitions, including the internal per-stream lock.)</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">stream</td><td>Stream to submit buffer to </td></tr>
<tr><td class="paramname">buffer</td><td>Buffer to fill (RX) or containing data (TX). This buffer is assumed to be the size specified in the associated <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga72752f2a047b95544e7686596a409abd">bladerf_init_stream()</a> call. </td></tr>
<tr><td class="paramname">timeout_ms</td><td>Milliseconds to timeout in, if this call blocks. 0 implies an "infinite" wait.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 on success, BLADERF_ERR_TIMEOUT upon a timeout, or a value from <a class="el" href="group___r_e_t_c_o_d_e_s.html">Error codes</a> list on other failures </dd></dl>
</div>
</div>
<a class="anchor" id="ga0d41def78ee90074575c8b6cff3a9283"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="libblade_r_f_8h.html#a5e3652cae8b48c1ad174f0b06bbd06d0">API_EXPORT</a> int <a class="el" href="libblade_r_f_8h.html#a66285a1fe575693f5f275b212891222e">CALL_CONV</a> bladerf_submit_stream_buffer_nb </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga4c5ac0ae2bd3c36b9078f3ce47cb71fd">bladerf_stream</a> * </td>
<td class="paramname"><em>stream</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"><em>buffer</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>This is a non-blocking variant of <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#gae0f45c213ace4619f23901b0b7aeeb21">bladerf_submit_stream_buffer()</a>. All of the caveats and important notes from <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#gae0f45c213ace4619f23901b0b7aeeb21">bladerf_submit_stream_buffer()</a> apply.</p>
<p>In the event that this call would need to block in order to submit a buffer, it returns BLADERF_ERR_WOULD_BLOCK. In this case, the caller could either wait and try again or defer buffer submission to the asynchronous callback.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">stream</td><td>Stream to submit buffer to </td></tr>
<tr><td class="paramname">buffer</td><td>Buffer to fill (RX) or containing data (TX). This buffer is assumed to be the size specified in the associated <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga72752f2a047b95544e7686596a409abd">bladerf_init_stream()</a> call.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 on success, BLADERF_ERR_WOULD_BLOCK if the call would have to block to succeed, or another value from <a class="el" href="group___r_e_t_c_o_d_e_s.html">Error codes</a> upon other failure </dd></dl>
</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Wed Jun 29 2016 16:51:01 for libbladeRF by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.11
</small></address>
</body>
</html>
