![]() |
libbladeRF
1.1.0
Nuand bladeRF library
|
Functions | |
API_EXPORT int CALL_CONV | bladerf_sync_config (struct bladerf *dev, bladerf_module module, bladerf_format format, unsigned int num_buffers, unsigned int buffer_size, unsigned int num_transfers, unsigned int stream_timeout) |
API_EXPORT int CALL_CONV | bladerf_sync_tx (struct bladerf *dev, void *samples, unsigned int num_samples, struct bladerf_metadata *metadata, unsigned int timeout_ms) |
API_EXPORT int CALL_CONV | bladerf_sync_rx (struct bladerf *dev, void *samples, unsigned int num_samples, struct bladerf_metadata *metadata, unsigned int timeout_ms) |
This group of functions presents synchronous, blocking calls (with optional timeouts) for transmitting and receiving samples.
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.
Under the hood, this interface spawns worker threads to handle an asynchronous stream and perform thread-safe buffer management.
These functions are thread-safe.
Below is the general process for using this interface to transmit and receive SC16 Q11 samples, without metadata.
To run in a half-duplex mode of operation, simply remove the RX or TX specific portions from the above example.
By using the BLADERF_FORMAT_SC16_Q11_META format with the synchronous interface, one can read the timestamp associated with a received buffer of data, or schedule to read a specific number of samples at a desired timestamp. Additionally, the metadata indicates if an overrun was detected, and the number of samples actually copied into the buffer before the discontinuity caused by the overrun.
Using the synchronous interface with the BLADERF_FORMAT_SC16_Q11_META format allows for bursts of samples to be scheduled for transmissions. Between these bursts, the device transmits I=0, Q=0.
To begin a burst, call bladerf_sync_tx() with the metadata's BLADERF_META_FLAG_TX_BURST_START flag set, the desired timestamp set in the bladerf_metadata structure, and any number of samples.
You may then continue calling bladerf_sync_tx(), without needing to update the timestamp field in the bladerf_metadata structure. For these calls, no flags should be set.
On the final bladerf_sync_tx() call for the burst, set the BLADERF_META_FLAG_TX_BURST_END flag, and ensure the final two samples provided to this function are 0.
It is valid to send the entire burst with a single function call, with both flags set.
API_EXPORT int CALL_CONV bladerf_sync_config | ( | struct bladerf * | dev, |
bladerf_module | module, | ||
bladerf_format | format, | ||
unsigned int | num_buffers, | ||
unsigned int | buffer_size, | ||
unsigned int | num_transfers, | ||
unsigned int | stream_timeout | ||
) |
(Re)Configure a device for synchronous transmission or reception
This function sets up the device for the specified format and initializes the underlying asynchronous stream parameters
This function does not call bladerf_enable_module(). The API user is responsible for enabling/disable modules when desired.
Note that (re)configuring BLADERF_MODULE_TX does not affect the BLADERF_MODULE_RX modules, and vice versa. This call configures each module independently.
Memory allocated by this function will be deallocated when bladerf_close() is called.
See the bladerf_init_stream() documentation for information on determining appropriate values for buffers_size
, num_transfers
, and stream_timeout
. The num_buffers
parameter should generally be increased as the amount of work done between bladerf_sync_rx() or bladerf_sync_tx() calls increases.
dev | Device to configure |
module | Module to use with synchronous interface |
format | Format to use in synchronous data transfers |
num_buffers | The number of buffers to use in the underlying data stream. This must be greater than the num_xfers parameter. |
buffer_size | 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. |
num_transfers | 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. |
stream_timeout | Timeout (milliseconds) for transfers in the underlying data stream. |
API_EXPORT int CALL_CONV bladerf_sync_rx | ( | struct bladerf * | dev, |
void * | samples, | ||
unsigned int | num_samples, | ||
struct bladerf_metadata * | metadata, | ||
unsigned int | timeout_ms | ||
) |
Receive IQ samples.
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.)
[in] | dev | Device handle |
[out] | samples | 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. |
[in] | num_samples | Number of samples to read |
[out] | metadata | Sample metadata. This must be provided when using the BLADERF_FORMAT_SC16_Q11_META format, but may be NULL when the interface is configured for the BLADERF_FORMAT_SC16_Q11 format. |
[in] | timeout_ms | Timeout (milliseconds) for this call to complete. Zero implies "infinite." |
API_EXPORT int CALL_CONV bladerf_sync_tx | ( | struct bladerf * | dev, |
void * | samples, | ||
unsigned int | num_samples, | ||
struct bladerf_metadata * | metadata, | ||
unsigned int | timeout_ms | ||
) |
Transmit IQ samples.
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.)
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 buffer_size
parameter passed to bladerf_sync_config().
[in] | dev | Device handle |
[in] | samples | Array of samples |
[in] | num_samples | Number of samples to write |
[in] | metadata | Sample metadata. This must be provided when using the BLADERF_FORMAT_SC16_Q11_META format, but may be NULL when the interface is configured for the BLADERF_FORMAT_SC16_Q11 format. |
[in] | timeout_ms | Timeout (milliseconds) for this call to complete. Zero implies "infinite." |