<!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 Interface: RX with Metadata</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><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>
<!-- 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><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Synchronous Interface: RX with Metadata </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This page describes how to use the bladeRF <a href="group___f_n___d_a_t_a___s_y_n_c.html" class="el">Synchronous Interface</a> to receive samples with their associated timestamp, and scheduling reception at a specific timestamp.</p>
<p>The timestamp value is associated with free-running counter in the FPGA, incrementing at the sample rate specified by <a class="el" href="group___f_n___s_a_m_p_l_i_n_g.html#ga248121816cd4621abf833df906ca0761">bladerf_set_sample_rate()</a>, with each incoming sample.</p>
<p><br />
</p><h2>Configuring the Synchronous Interface</h2>
<p>When timestamps are desired, one must enable metadata support. This is done through the <code>format</code> parameter of the <a class="el" href="group___f_n___d_a_t_a___s_y_n_c.html#gacde68e74a8f7d27100b071634b2e65c5">bladerf_sync_config()</a> function:</p>
<div class="fragment"><div class="line"></div><div class="line"> <span class="comment">/* Configure the device's RX module for use with the sync interface.</span></div><div class="line"><span class="comment"> * SC16 Q11 samples *with* metadata are used. */</span></div><div class="line"> status = <a class="code" href="group___f_n___d_a_t_a___s_y_n_c.html#gacde68e74a8f7d27100b071634b2e65c5">bladerf_sync_config</a>(dev,</div><div class="line"> <a class="code" href="group___f_n___m_o_d_u_l_e.html#ggab12571146a3d4c5d79ac497a74b3fb5ea8df9d0339c79bf7221af3a3897360c6f">BLADERF_MODULE_RX</a>,</div><div class="line"> <a class="code" href="group___f_m_t___m_e_t_a.html#gga4c61587834fd4de51a8e2d34e14a73b2a4af3974535ba338bbcecaa8d7500de03">BLADERF_FORMAT_SC16_Q11_META</a>,</div><div class="line"> num_buffers,</div><div class="line"> buffer_size,</div><div class="line"> num_transfers,</div><div class="line"> timeout_ms);</div><div class="line"></div><div class="line"> <span class="keywordflow">if</span> (status != 0) {</div><div class="line"> fprintf(stderr, <span class="stringliteral">"Failed to configure RX sync interface: %s\n"</span>,</div><div class="line"> <a class="code" href="group___r_e_t_c_o_d_e_s.html#ga689e0c91e6abb8b5575a929453e4dbcc">bladerf_strerror</a>(status));</div><div class="line"></div><div class="line"> <span class="keywordflow">goto</span> error;</div><div class="line"> }</div><div class="line"></div></div><!-- fragment --><p> Descriptions of the other parameters may be found in the <a href="sync_no_meta.html" class="el">Synchronous Interface: Basic usage without metadata</a> page.</p>
<p>Remember to enable the module via <a class="el" href="group___f_n___m_o_d_u_l_e.html#gabef14480bd8483eaf937b30a4b5eab88">bladerf_enable_module()</a> <em>after</em> calling <a class="el" href="group___f_n___d_a_t_a___s_y_n_c.html#gacde68e74a8f7d27100b071634b2e65c5">bladerf_sync_config()</a>, and <em>before</em> attempting to call <a class="el" href="group___f_n___d_a_t_a___s_y_n_c.html#gacbe845827dd4ad717f3cbc812e66b204">bladerf_sync_rx()</a>.</p>
<p>Also ensure that <a class="el" href="group___f_n___d_a_t_a___s_y_n_c.html#gacde68e74a8f7d27100b071634b2e65c5">bladerf_sync_config()</a> has been called before attempting to read timestamps via <a class="el" href="group___f_m_t___m_e_t_a.html#ga9b03a1b2254eab471f789627c3bde408">bladerf_get_timestamp()</a>.</p>
<p>When using the <a class="el" href="group___f_m_t___m_e_t_a.html#gga4c61587834fd4de51a8e2d34e14a73b2a4af3974535ba338bbcecaa8d7500de03">BLADERF_FORMAT_SC16_Q11_META</a> format, a <a class="el" href="structbladerf__metadata.html">bladerf_metadata</a> structure must be passed to <a class="el" href="group___f_n___d_a_t_a___s_y_n_c.html#gacbe845827dd4ad717f3cbc812e66b204">bladerf_sync_rx()</a>. One should zeroize the contents of this structure prior to using it.</p>
<p><br />
</p><h2>Receiving Samples Immediately with Timestamps</h2>
<p>As shown in the following snippet, the <a class="el" href="structbladerf__metadata.html">bladerf_metadata</a> structure (<code>meta</code>) is first zeroed out, and then the metadata flags (<code>meta.flags</code>) are set to <a class="el" href="group___f_m_t___m_e_t_a.html#ga63edd4df536045366c24df13d2c49899">BLADERF_META_FLAG_RX_NOW</a>. This flag denotes that RX samples should returned immediately, rather than scheduled for a specific RX timestamp.</p>
<p>Once <a class="el" href="group___f_n___d_a_t_a___s_y_n_c.html#gacbe845827dd4ad717f3cbc812e66b204">bladerf_sync_rx()</a> returns, the <a class="el" href="structbladerf__metadata.html#a465bef81f6478756e5443025b1f2ddfa">bladerf_metadata.timestamp</a> field may be read (<code>meta.timestamp</code>). Under normal conditions, this timestamp is associated with the first sample in the provided buffer, with the remaining samples in the buffer being contiguous (i.e., there is no timestamp gap between them). The <a class="el" href="structbladerf__metadata.html#a0a144ddaed8845788d38379d7b469960">bladerf_metadata.actual_count</a> field should indicate that the requested number of samples have been read into the supplied buffer.</p>
<p>However, if an RX overrun has occurred, as indicated by the <a class="el" href="group___f_m_t___m_e_t_a.html#ga5c2c095d1681ffe8928d84c8b4cca714">BLADERF_META_STATUS_OVERRUN</a> bit being set in the <a class="el" href="structbladerf__metadata.html#ade20423e91627f07e610924cb0081623">bladerf_metadata.status</a> field (<code>meta.status</code>), a sample discontinuity will have occurred. Generally, this overrun condition may occur if the time between calls to <a class="el" href="group___f_n___d_a_t_a___s_y_n_c.html#gacbe845827dd4ad717f3cbc812e66b204">bladerf_sync_rx()</a> is too long, or too few/small buffers were provided to <a class="el" href="group___f_n___d_a_t_a___s_y_n_c.html#gacde68e74a8f7d27100b071634b2e65c5">bladerf_sync_config()</a>.</p>
<p>In the case of an overrun, the <a class="el" href="structbladerf__metadata.html">bladerf_metadata</a>'s <code>actual_count</code> value is set to the number of contiguous samples read into the supplied buffer. This value will be less than the requested number of samples, so be sure not to read past this number of samples.</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> sync_rx_meta_now_example(<span class="keyword">struct</span> bladerf *dev,</div><div class="line"> int16_t *samples, <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> samples_len,</div><div class="line"> <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> rx_count, <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> timeout_ms)</div><div class="line">{</div><div class="line"> <span class="keywordtype">int</span> status = 0;</div><div class="line"> <span class="keyword">struct </span><a class="code" href="structbladerf__metadata.html">bladerf_metadata</a> meta;</div><div class="line"> <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> i;</div><div class="line"></div><div class="line"></div><div class="line"> <span class="comment">/* Perform a read immediately, and have the bladerf_sync_rx function</span></div><div class="line"><span class="comment"> * provide the timestamp of the read samples */</span></div><div class="line"> memset(&meta, 0, <span class="keyword">sizeof</span>(meta));</div><div class="line"> meta.flags = <a class="code" href="group___f_m_t___m_e_t_a.html#ga63edd4df536045366c24df13d2c49899">BLADERF_META_FLAG_RX_NOW</a>;</div><div class="line"></div><div class="line"> <span class="comment">/* Receive samples and do work on them */</span></div><div class="line"> <span class="keywordflow">for</span> (i = 0; i < rx_count && status == 0; i++) {</div><div class="line"></div><div class="line"> status = <a class="code" href="group___f_n___d_a_t_a___s_y_n_c.html#gacbe845827dd4ad717f3cbc812e66b204">bladerf_sync_rx</a>(dev, samples, samples_len, &meta, timeout_ms);</div><div class="line"> <span class="keywordflow">if</span> (status != 0) {</div><div class="line"> fprintf(stderr, <span class="stringliteral">"RX \"now\" failed: %s\n\n"</span>,</div><div class="line"> <a class="code" href="group___r_e_t_c_o_d_e_s.html#ga689e0c91e6abb8b5575a929453e4dbcc">bladerf_strerror</a>(status));</div><div class="line"> } <span class="keywordflow">else</span> <span class="keywordflow">if</span> (meta.status & <a class="code" href="group___f_m_t___m_e_t_a.html#ga5c2c095d1681ffe8928d84c8b4cca714">BLADERF_META_STATUS_OVERRUN</a>) {</div><div class="line"> fprintf(stderr, <span class="stringliteral">"Overrun detected. %u valid samples were read.\n"</span>,</div><div class="line"> meta.actual_count);</div><div class="line"> } <span class="keywordflow">else</span> {</div><div class="line"> printf(<span class="stringliteral">"RX'd %u samples at t=0x%016"</span>PRIx64<span class="stringliteral">"\n"</span>,</div><div class="line"> meta.actual_count, meta.timestamp);</div><div class="line"></div><div class="line"> fflush(stdout);</div><div class="line"></div><div class="line"> <span class="comment">/* ... Do work on samples here...</span></div><div class="line"><span class="comment"> *</span></div><div class="line"><span class="comment"> * status = process_samples(samples, samples_len);</span></div><div class="line"><span class="comment"> */</span></div><div class="line"> }</div><div class="line"> }</div><div class="line"></div><div class="line"> <span class="keywordflow">return</span> <a class="code" href="structbladerf__metadata.html#ade20423e91627f07e610924cb0081623">status</a>;</div><div class="line">}</div></div><!-- fragment --><p> <br />
</p><h2>Receiving Samples at a Specified Timestamps</h2>
<p>To schedule reception at a specific timestamp, set the <a class="el" href="structbladerf__metadata.html#a773b39d480759f67926cb18ae2219281">bladerf_metadata.flags</a> field to 0, and write the desired timestamp to the <a class="el" href="structbladerf__metadata.html#a465bef81f6478756e5443025b1f2ddfa">bladerf_metadata.timestamp</a> field.</p>
<p>A call to <a class="el" href="group___f_n___d_a_t_a___s_y_n_c.html#gacbe845827dd4ad717f3cbc812e66b204">bladerf_sync_rx()</a> may then be used to read the specified number of samples at the timestamp indicated in metadata structure. Ensure that the timeout provided to <a class="el" href="group___f_n___d_a_t_a___s_y_n_c.html#gacbe845827dd4ad717f3cbc812e66b204">bladerf_sync_rx()</a> is sufficiently large, such that the function call does not time out before the desired timestamp occurs.</p>
<p>When scheduling the first RX, it is generally helpful to first read the module's timestamp counter and advance it by a known duration. This is shown in the below example code.</p>
<p>Note that the caller is responsible for advancing the timestamp field each time <a class="el" href="group___f_n___d_a_t_a___s_y_n_c.html#gacbe845827dd4ad717f3cbc812e66b204">bladerf_sync_rx()</a> is called.</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> sync_rx_meta_sched_example(<span class="keyword">struct</span> bladerf *dev,</div><div class="line"> int16_t *samples, <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> samples_len,</div><div class="line"> <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> rx_count, <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> samplerate,</div><div class="line"> <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> timeout_ms)</div><div class="line">{</div><div class="line"> <span class="keywordtype">int</span> <a class="code" href="structbladerf__metadata.html#ade20423e91627f07e610924cb0081623">status</a>;</div><div class="line"> <span class="keyword">struct </span><a class="code" href="structbladerf__metadata.html">bladerf_metadata</a> meta;</div><div class="line"> <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> i;</div><div class="line"></div><div class="line"> <span class="comment">/* 150 ms timestamp increment */</span></div><div class="line"> <span class="keyword">const</span> uint64_t ts_inc_150ms = ((uint64_t) samplerate) * 150 / 1000;</div><div class="line"></div><div class="line"> <span class="comment">/* 1 ms timestamp increment */</span></div><div class="line"> <span class="keyword">const</span> uint64_t ts_inc_1ms = samplerate / 1000;</div><div class="line"></div><div class="line"> memset(&meta, 0, <span class="keyword">sizeof</span>(meta));</div><div class="line"></div><div class="line"> <span class="comment">/* Perform scheduled RXs by having meta.timestamp set appropriately</span></div><div class="line"><span class="comment"> * and ensuring the BLADERF_META_FLAG_RX_NOW flag is cleared. */</span></div><div class="line"> meta.flags = 0;</div><div class="line"></div><div class="line"> <span class="comment">/* Retrieve the current timestamp */</span></div><div class="line"> status = <a class="code" href="group___f_m_t___m_e_t_a.html#ga9b03a1b2254eab471f789627c3bde408">bladerf_get_timestamp</a>(dev, <a class="code" href="group___f_n___m_o_d_u_l_e.html#ggab12571146a3d4c5d79ac497a74b3fb5ea8df9d0339c79bf7221af3a3897360c6f">BLADERF_MODULE_RX</a>, &meta.timestamp);</div><div class="line"> <span class="keywordflow">if</span> (status != 0) {</div><div class="line"> fprintf(stderr, <span class="stringliteral">"Failed to get current RX timestamp: %s\n"</span>,</div><div class="line"> <a class="code" href="group___r_e_t_c_o_d_e_s.html#ga689e0c91e6abb8b5575a929453e4dbcc">bladerf_strerror</a>(status));</div><div class="line"> } <span class="keywordflow">else</span> {</div><div class="line"> printf(<span class="stringliteral">"Current RX timestamp: 0x%016"</span>PRIx64<span class="stringliteral">"\n"</span>, meta.timestamp);</div><div class="line"> }</div><div class="line"></div><div class="line"> <span class="comment">/* Schedule first RX to be 150 ms in the future */</span></div><div class="line"> meta.timestamp += ts_inc_150ms;</div><div class="line"></div><div class="line"> <span class="comment">/* Receive samples and do work on them */</span></div><div class="line"> <span class="keywordflow">for</span> (i = 0; i < rx_count && status == 0; i++) {</div><div class="line"></div><div class="line"> status = <a class="code" href="group___f_n___d_a_t_a___s_y_n_c.html#gacbe845827dd4ad717f3cbc812e66b204">bladerf_sync_rx</a>(dev, samples, samples_len,</div><div class="line"> &meta, 2 * timeout_ms);</div><div class="line"></div><div class="line"></div><div class="line"> <span class="keywordflow">if</span> (status != 0) {</div><div class="line"> fprintf(stderr, <span class="stringliteral">"Scheduled RX failed: %s\n\n"</span>,</div><div class="line"> <a class="code" href="group___r_e_t_c_o_d_e_s.html#ga689e0c91e6abb8b5575a929453e4dbcc">bladerf_strerror</a>(status));</div><div class="line"> } <span class="keywordflow">else</span> <span class="keywordflow">if</span> (meta.status & <a class="code" href="group___f_m_t___m_e_t_a.html#ga5c2c095d1681ffe8928d84c8b4cca714">BLADERF_META_STATUS_OVERRUN</a>) {</div><div class="line"> fprintf(stderr, <span class="stringliteral">"Overrun detected in scheduled RX. "</span></div><div class="line"> <span class="stringliteral">"%u valid samples were read.\n\n"</span>, meta.actual_count);</div><div class="line"> } <span class="keywordflow">else</span> {</div><div class="line"> printf(<span class="stringliteral">"RX'd %u samples at t=0x%016"</span>PRIx64<span class="stringliteral">"\n"</span>,</div><div class="line"> meta.actual_count, meta.timestamp);</div><div class="line"></div><div class="line"> fflush(stdout);</div><div class="line"></div><div class="line"> <span class="comment">/* ... Process samples here ... */</span></div><div class="line"></div><div class="line"> <span class="comment">/* Schedule the next RX to be 1 ms after the end of the samples we</span></div><div class="line"><span class="comment"> * just processed */</span></div><div class="line"> meta.timestamp += samples_len + ts_inc_1ms;</div><div class="line"> }</div><div class="line"> }</div><div class="line"></div><div class="line"> <span class="keywordflow">return</span> <a class="code" href="structbladerf__metadata.html#ade20423e91627f07e610924cb0081623">status</a>;</div><div class="line">}</div><div class="line"></div></div><!-- fragment --><p> The description of the <a class="el" href="group___f_m_t___m_e_t_a.html#ga5c2c095d1681ffe8928d84c8b4cca714">BLADERF_META_STATUS_OVERRUN</a> flag and the the <a class="el" href="structbladerf__metadata.html#a0a144ddaed8845788d38379d7b469960">bladerf_metadata.actual_count</a> field from the previous section applies here as well. </p>
</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>
