<!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: Synchronous 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="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">Synchronous data transmission and reception</div> </div>
</div><!--header-->
<div class="contents">
<a name="details" id="details"></a><h2 class="groupheader">Description</h2>
<p>This group of functions presents synchronous, blocking calls (with optional timeouts) for transmitting and receiving samples.</p>
<p>The synchronous interface is built atop the asynchronous interface, and is generally less complex and easier to work with. It alleviates the need to explicitly spawn threads (it is done under the hood) and manually manage sample buffers.</p>
<p>Under the hood, this interface spawns worker threads to handle an asynchronous stream and perform thread-safe buffer management.</p>
<p>These functions are thread-safe.</p>
<p>The following pages provide additional information and example usage: </p><ul>
<li>
<a href="sync_no_meta.html" class="el">Synchronous Interface: Basic usage without metadata </a> </li>
<li>
<a href="sync_rx_meta.html" class="el">Synchronous Interface: RX with metadata </a> </li>
<li>
<a href="sync_tx_meta_bursts.html" class="el">Synchronous Interface: TX with metadata </a> </li>
</ul>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:gacde68e74a8f7d27100b071634b2e65c5"><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___s_y_n_c.html#gacde68e74a8f7d27100b071634b2e65c5">bladerf_sync_config</a> (struct bladerf *dev, <a class="el" href="group___f_n___m_o_d_u_l_e.html#gab12571146a3d4c5d79ac497a74b3fb5e">bladerf_module</a> module, <a class="el" href="group___f_m_t___m_e_t_a.html#ga4c61587834fd4de51a8e2d34e14a73b2">bladerf_format</a> format, unsigned int num_buffers, unsigned int buffer_size, unsigned int num_transfers, unsigned int stream_timeout)</td></tr>
<tr class="separator:gacde68e74a8f7d27100b071634b2e65c5"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gac4a13bf1cb10d9a3e547b8c654268c35"><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___s_y_n_c.html#gac4a13bf1cb10d9a3e547b8c654268c35">bladerf_sync_tx</a> (struct bladerf *dev, void *samples, unsigned int num_samples, struct <a class="el" href="structbladerf__metadata.html">bladerf_metadata</a> *metadata, unsigned int timeout_ms)</td></tr>
<tr class="separator:gac4a13bf1cb10d9a3e547b8c654268c35"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gacbe845827dd4ad717f3cbc812e66b204"><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___s_y_n_c.html#gacbe845827dd4ad717f3cbc812e66b204">bladerf_sync_rx</a> (struct bladerf *dev, void *samples, unsigned int num_samples, struct <a class="el" href="structbladerf__metadata.html">bladerf_metadata</a> *metadata, unsigned int timeout_ms)</td></tr>
<tr class="separator:gacbe845827dd4ad717f3cbc812e66b204"><td class="memSeparator" colspan="2"> </td></tr>
</table>
<h2 class="groupheader">Function Documentation</h2>
<a class="anchor" id="gacde68e74a8f7d27100b071634b2e65c5"></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_sync_config </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"><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">unsigned int </td>
<td class="paramname"><em>num_buffers</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned int </td>
<td class="paramname"><em>buffer_size</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned int </td>
<td class="paramname"><em>num_transfers</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned int </td>
<td class="paramname"><em>stream_timeout</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>(Re)Configure a device for synchronous transmission or reception</p>
<p>This function sets up the device for the specified format and initializes the underlying asynchronous stream parameters</p>
<p>This function does not call <a class="el" href="group___f_n___m_o_d_u_l_e.html#gabef14480bd8483eaf937b30a4b5eab88">bladerf_enable_module()</a>. The API user is responsible for enabling/disable modules when desired.</p>
<p>Note that (re)configuring <a class="el" href="group___f_n___m_o_d_u_l_e.html#ggab12571146a3d4c5d79ac497a74b3fb5ea2b59868119a050b6f0e24631ffbb16e3">BLADERF_MODULE_TX</a> does not affect the <a class="el" href="group___f_n___m_o_d_u_l_e.html#ggab12571146a3d4c5d79ac497a74b3fb5ea8df9d0339c79bf7221af3a3897360c6f">BLADERF_MODULE_RX</a> modules, and vice versa. This call configures each module independently.</p>
<p>Memory allocated by this function will be deallocated when <a class="el" href="group___f_n___i_n_i_t.html#ga78676b94de9a8aae49d72a9ef2f0e4d9">bladerf_close()</a> is called.</p>
<p>See the <a class="el" href="group___f_n___d_a_t_a___a_s_y_n_c.html#ga72752f2a047b95544e7686596a409abd">bladerf_init_stream()</a> documentation for information on determining appropriate values for <code>buffers_size</code>, <code>num_transfers</code>, and <code>stream_timeout</code>. The <code>num_buffers</code> parameter should generally be increased as the amount of work done between <a class="el" href="group___f_n___d_a_t_a___s_y_n_c.html#gacbe845827dd4ad717f3cbc812e66b204">bladerf_sync_rx()</a> or <a class="el" href="group___f_n___d_a_t_a___s_y_n_c.html#gac4a13bf1cb10d9a3e547b8c654268c35">bladerf_sync_tx()</a> calls increases.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">dev</td><td>Device to configure</td></tr>
<tr><td class="paramname">module</td><td>Module to use with synchronous interface</td></tr>
<tr><td class="paramname">format</td><td>Format to use in synchronous data transfers</td></tr>
<tr><td class="paramname">num_buffers</td><td>The number of buffers to use in the underlying data stream. This must be greater than the <code>num_xfers</code> parameter.</td></tr>
<tr><td class="paramname">buffer_size</td><td>The size of the underlying stream buffers, in samples. This value must be a multiple of 1024. Note that samples are only transferred when a buffer of this size is filled.</td></tr>
<tr><td class="paramname">num_transfers</td><td>The number of active USB transfers that may be in-flight at any given time. If unsure of what to use here, try values of 4, 8, or 16.</td></tr>
<tr><td class="paramname">stream_timeout</td><td>Timeout (milliseconds) for transfers in the underlying data stream.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 on success, BLADERF_ERR_UNSUPPORTED if libbladeRF is not built with support for this functionality, or a value from <a class="el" href="group___r_e_t_c_o_d_e_s.html">Error codes</a> list on failures. </dd></dl>
</div>
</div>
<a class="anchor" id="gacbe845827dd4ad717f3cbc812e66b204"></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_sync_rx </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">void * </td>
<td class="paramname"><em>samples</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned int </td>
<td class="paramname"><em>num_samples</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct <a class="el" href="structbladerf__metadata.html">bladerf_metadata</a> * </td>
<td class="paramname"><em>metadata</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>Receive IQ samples.</p>
<p>Under the hood, this call starts up an underlying asynchronous stream as needed. This stream can be stopped by disabling the RX module. (See bladerf_enable_module for more details.)</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">[out]</td><td class="paramname">samples</td><td>Buffer to store samples in. The caller is responsible for ensuring this buffer is sufficiently large for the number of samples requested, considering the size of the sample format being used.</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">num_samples</td><td>Number of samples to read</td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">metadata</td><td>Sample metadata. This must be provided when using the <a class="el" href="group___f_m_t___m_e_t_a.html#gga4c61587834fd4de51a8e2d34e14a73b2a4af3974535ba338bbcecaa8d7500de03">BLADERF_FORMAT_SC16_Q11_META</a> format, but may be NULL when the interface is configured for the <a class="el" href="group___f_m_t___m_e_t_a.html#gga4c61587834fd4de51a8e2d34e14a73b2a92cfbda7a5577c809e2ff6123f8f30b6">BLADERF_FORMAT_SC16_Q11</a> format.</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">timeout_ms</td><td>Timeout (milliseconds) for this call to complete. Zero implies "infinite."</td></tr>
</table>
</dd>
</dl>
<dl class="section pre"><dt>Precondition</dt><dd>A <a class="el" href="group___f_n___d_a_t_a___s_y_n_c.html#gacde68e74a8f7d27100b071634b2e65c5">bladerf_sync_config()</a> call has been to configure the device for synchronous data transfer.</dd>
<dd>
A call to <a class="el" href="group___f_n___m_o_d_u_l_e.html#gabef14480bd8483eaf937b30a4b5eab88">bladerf_enable_module()</a> should be made before attempting to receive samples. Failing to do this may result in timeouts and other errors.</dd></dl>
<dl class="section return"><dt>Returns</dt><dd>0 on success, BLADERF_ERR_UNSUPPORTED if libbladeRF is not built with support for this functionality, or a value from <a class="el" href="group___r_e_t_c_o_d_e_s.html">Error codes</a> list on failures. </dd></dl>
</div>
</div>
<a class="anchor" id="gac4a13bf1cb10d9a3e547b8c654268c35"></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_sync_tx </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">void * </td>
<td class="paramname"><em>samples</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned int </td>
<td class="paramname"><em>num_samples</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct <a class="el" href="structbladerf__metadata.html">bladerf_metadata</a> * </td>
<td class="paramname"><em>metadata</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>Transmit IQ samples.</p>
<p>Under the hood, this call starts up an underlying asynchronous stream as needed. This stream can be stopped by disabling the TX module. (See bladerf_enable_module for more details.)</p>
<p>Samples will only be sent to the FPGA when a buffer have been filled. The number of samples required to fill a buffer corresponds to the <code>buffer_size</code> parameter passed to <a class="el" href="group___f_n___d_a_t_a___s_y_n_c.html#gacde68e74a8f7d27100b071634b2e65c5">bladerf_sync_config()</a>.</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">samples</td><td>Array of samples</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">num_samples</td><td>Number of samples to write</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">metadata</td><td>Sample metadata. This must be provided when using the <a class="el" href="group___f_m_t___m_e_t_a.html#gga4c61587834fd4de51a8e2d34e14a73b2a4af3974535ba338bbcecaa8d7500de03">BLADERF_FORMAT_SC16_Q11_META</a> format, but may be NULL when the interface is configured for the <a class="el" href="group___f_m_t___m_e_t_a.html#gga4c61587834fd4de51a8e2d34e14a73b2a92cfbda7a5577c809e2ff6123f8f30b6">BLADERF_FORMAT_SC16_Q11</a> format.</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">timeout_ms</td><td>Timeout (milliseconds) for this call to complete. Zero implies "infinite."</td></tr>
</table>
</dd>
</dl>
<dl class="section pre"><dt>Precondition</dt><dd>A <a class="el" href="group___f_n___d_a_t_a___s_y_n_c.html#gacde68e74a8f7d27100b071634b2e65c5">bladerf_sync_config()</a> call has been to configure the device for synchronous data transfer.</dd>
<dd>
A call to <a class="el" href="group___f_n___m_o_d_u_l_e.html#gabef14480bd8483eaf937b30a4b5eab88">bladerf_enable_module()</a> should be made before attempting to transmit samples. Failing to do this may result in timeouts and other errors.</dd></dl>
<dl class="section return"><dt>Returns</dt><dd>0 on success, BLADERF_ERR_UNSUPPORTED if libbladeRF is not built with support for this functionality, or a value from <a class="el" href="group___r_e_t_c_o_d_e_s.html">Error codes</a> list on failures. </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>
