bladeRF/host/libraries/libbladeRF/doc/doxygen/sync_tx_meta.dox
2017-12-21 12:55:04 -05:00

153 lines
6 KiB
Text

/**
\page sync_tx_meta_bursts Synchronous Interface: Scheduled TX bursts
This page describes how to use the bladeRF <a class="el"
href="group___f_n___d_a_t_a___s_y_n_c.html">Synchronous Interface</a> to
transmit bursts of samples at a specified timestamp. The timestamp is a
free-running counter in the FPGA, incrementing at the sample rate specified by
bladerf_set_sample_rate(), with each outgoing sample.
<h2>Configuring the Synchronous Interface</h2>
When timestamps are desired, one must enable metadata support. This is done
through the `format` parameter of the bladerf_sync_config() function:
\snippet sync_tx_meta.c sync_config
Descriptions of the other parameters may be found in the
<a class="el" href="sync_no_meta.html">Synchronous Interface: Basic usage without metadata</a>
page.
Remember to enable the front end via bladerf_enable_module() <i>after</i>
calling bladerf_sync_config(), and <i>before</i> attempting to call
bladerf_sync_tx().
Also ensure that bladerf_sync_config() has been called before attempting to read
timestamps via bladerf_get_timestamp().
<h2>Burst Transmissions</h2>
The synchronous interface allows a burst of samples to be transmitted at
a specified timestamp value. The hardware will output zeros after the burst.
The general procedure for transmitting a burst is as follows
<ul>
<li>Call bladerf_sync_tx() with ::bladerf_metadata.flags set to
::BLADERF_META_FLAG_TX_BURST_START and ::bladerf_metadata.timestamp
set to the timestamp at which samples should be transmitted.
<li>Make successive bladerf_sync_tx() calls with ::bladerf_metadata.flags
set to 0. These samples will be contiguously appended to the
previous samples. The ::bladerf_metadata.timestamp field is not used
at this point; the caller does not need to worry about advancing it.
<li>Call bladerf_sync_tx() with the final samples in the burst and the
::bladerf_metadata.flags set to ::BLADERF_META_FLAG_TX_BURST_END.
This will complete the burst, flush any remaining samples in the
synchronous interface's current internal buffer, and write the
buffer to the device. Similar to the previous step, any samples
provided at this points will be contiguously appended to prior
samples, and the ::bladerf_metadata.timestamp field will not be used.
</ul>
The above procedure is useful when the samples for the burst are actively
being produced.
If all the samples for the burst are available ahead of time, all of the above
steps can be performed with a single function call, with:
<ul>
<li>::bladerf_metadata.flags set to:
<code>(BLADERF_META_FLAG_TX_BURST_START | BLADERF_META_FLAG_TX_BURST_END)</code>
</li>
<li>
::bladerf_metadata.timestamp set to the timestamp at which the samples
should be transmitted.
</li>
</ul>
Note that when completing a burst with ::BLADERF_META_FLAG_TX_BURST_END, up
to one of the synchronous interface's buffers may be flushed. This is important
to consider, since this defines the minimum value of the next timestamp
can be provided.
If small bursts need to be scheduled back to back, consider either manually
zero-padding between them, or using the ::BLADERF_META_FLAG_TX_UPDATE_TIMESTAMP
flag, as described in one of the following sections.
<br>
<h2>Waiting for TX to complete</h2>
When scheduling transmissions, one must ensure the samples have reached the
RF front end before shutting the stream down and disabling TX.
This can be achieved by polling the TX timestamp and waiting for it to exceed
the value of the last sample. Generally, one should wait some additional time
to account for some group delay in the signal path.
Below is an example `wait_for_timestamp()` function that provides this
functionality, with a simple timeout:
\snippet sync_tx_meta.c wait_for_timestamp
<br>
<h2>Scheduled Burst Example</h2>
This example illustrates transmitting scheduled bursts, via a single function
call.
\snippet sync_tx_meta.c tx_meta_sched
<br>
<h2>Using the TX_NOW flag</h2>
In some cases, one may wish to transmit a burst immediately while using the
::BLADERF_FORMAT_SC16_Q11_META format. As shown in the below example, this
is possible by setting the ::BLADERF_META_FLAG_TX_NOW flag. When using this
flag the ::bladerf_metadata.timestamp field is not used.
\snippet sync_tx_meta.c tx_meta_now
<br>
<h2>Using the UPDATE_TIMESTAMP flag</h2>
In some applications, flushing an entire buffer ::BLADERF_META_FLAG_TX_BURST_END
may result in too long of a delay between bursts. As suggested earlier in this
page, a user may instead manually zero pad their samples to achieve short
discontinuities, or have libbladeRF do this for them using the
::BLADERF_META_FLAG_TX_UPDATE_TIMESTAMP flag.
The general usage of this is:
<ul>
<li>
Set ::bladerf_metadata.timestamp to the desired start of transmission, and
::bladerf_metadata.flags to ::BLADERF_META_FLAG_TX_BURST_START. Call
bladerf_sync_tx() with the initial samples in
the burst.
</li>
<li>
<i>Optional:</i> Call bladerf_sync_tx() with ::bladerf_metadata.flags as
needed to transmit samples that are contiguous with the previous samples.
::bladerf_metadata.timestamp is not used in this state.
</li>
<li>
Call bladerf_sync_tx() with ::bladerf_metadata.flags set to ::BLADERF_META_FLAG_TX_UPDATE_TIMESTAMP and ::bladerf_metadata.timestamp set to the desired timestamp. libbladeRF will schedule
the provided samples for the specified timestamp, manually zero-padding a buffer if needed.
</li>
<li>
<i>Optional:</i> Call bladerf_sync_tx() with ::bladerf_metadata.flags as
needed to transmit samples that are contiguous with the newly scheduled samples.
::bladerf_metadata.timestamp is not used in this state.
</li>
<li>
When done transmitting, call bladerf_sync_tx() with
::bladerf_metadata.flags set to ::BLADERF_META_FLAG_TX_BURST_END and two or
more zero samples. This will ensure the analog front end DACs are held at a
zero value.
</li>
</ul>
The above procedure is shown in the below example:
\snippet sync_tx_meta.c tx_meta_update
*/