![]() |
libbladeRF
1.7.2
Nuand bladeRF library
|
This section defines the available sample formats and metadata flags.
Data Structures | |
struct | bladerf_metadata |
Macros | |
#define | BLADERF_META_STATUS_OVERRUN (1 << 0) |
#define | BLADERF_META_STATUS_UNDERRUN (1 << 1) |
#define | BLADERF_META_FLAG_TX_BURST_START (1 << 0) |
#define | BLADERF_META_FLAG_TX_BURST_END (1 << 1) |
#define | BLADERF_META_FLAG_TX_NOW (1 << 2) |
#define | BLADERF_META_FLAG_TX_UPDATE_TIMESTAMP (1 << 3) |
#define | BLADERF_META_FLAG_RX_NOW (1 << 31) |
Enumerations | |
enum | bladerf_format { BLADERF_FORMAT_SC16_Q11, BLADERF_FORMAT_SC16_Q11_META } |
Functions | |
API_EXPORT int CALL_CONV | bladerf_get_timestamp (struct bladerf *dev, bladerf_module mod, uint64_t *value) |
#define BLADERF_META_FLAG_RX_NOW (1 << 31) |
This flag indicates that calls to bladerf_sync_rx should return any available samples, rather than wait until the timestamp indicated in the bladerf_metadata timestamp field.
Definition at line 2899 of file libbladeRF.h.
#define BLADERF_META_FLAG_TX_BURST_END (1 << 1) |
Mark the associated buffer as the end of a burst transmission. This will flush the remainder of the sync interface's current working buffer and enqueue samples into the hardware's transmit FIFO.
As of libbladeRF v1.3.0, it is no longer necessary for the API user to ensure that the final 3 samples of a burst are 0+0j. libbladeRF now ensures this hardware requirement (driven by the LMS6002D's pre-DAC register stages) is upheld.
Specifying this flag and flushing the sync interface's working buffer implies that the next timestamp that can be transmitted is the current timestamp plus the duration of the burst that this flag is ending and the remaining length of the remaining buffer that is flushed. (The buffer size, in this case, is the buffer_size
value passed to the previous bladerf_sync_config() call.)
Rather than attempting to keep track of the number of samples sent with respect to buffer sizes, it is easiest to always assume 1 buffer's worth of time is required between bursts. In this case "buffer" refers to the buffer_size
parameter provided to bladerf_sync_config().) If this is too much time, consider using the BLADERF_META_FLAG_TX_UPDATE_TIMESTAMP flag.
This is only used for the bladerf_sync_tx() call. It is ignored by the bladerf_sync_rx() call.
Definition at line 2862 of file libbladeRF.h.
#define BLADERF_META_FLAG_TX_BURST_START (1 << 0) |
Mark the associated buffer as the start of a burst transmission. This is only used for the bladerf_sync_tx() call.
When using this flag, the bladerf_metadata::timestamp field should contain the timestamp at which samples should be sent.
Between specifying the BLADERF_META_FLAG_TX_BURST_START and BLADERF_META_FLAG_TX_BURST_END flags, there is no need for the user to the bladerf_metadata::timestamp field because the library will ensure the correct value is used, based upon the timestamp initially provided and the number of samples that have been sent.
Definition at line 2832 of file libbladeRF.h.
#define BLADERF_META_FLAG_TX_NOW (1 << 2) |
Use this flag in conjunction with BLADERF_META_FLAG_TX_BURST_START to indicate that the burst should be transmitted as soon as possible, as opposed to waiting for a specific timestamp.
When this flag is used, there is no need to set the bladerf_metadata::timestamp field.
Definition at line 2872 of file libbladeRF.h.
#define BLADERF_META_FLAG_TX_UPDATE_TIMESTAMP (1 << 3) |
Use this flag within a burst (i.e., between the use of BLADERF_META_FLAG_TX_BURST_START and BLADERF_META_FLAG_TX_BURST_END) to specify that bladerf_sync_tx() should read the bladerf_metadata::timestamp field and zero-pad samples up to the specified timestamp. The provided samples will then be transmitted at that timestamp.
Use this flag when potentially flushing an entire buffer via the BLADERF_META_FLAG_TX_BURST_END would yield an unacceptably large gap in the transmitted samples.
In some applications where a transmitter is constantly transmitting with extremely small gaps (less than a buffer), users may end up using a single BLADERF_META_FLAG_TX_BURST_START, and then numerous calls to bladerf_sync_tx() with the BLADERF_META_FLAG_TX_UPDATE_TIMESTAMP flag set. The BLADERF_META_FLAG_TX_BURST_END would only be used to end the stream when shutting down.
Definition at line 2892 of file libbladeRF.h.
#define BLADERF_META_STATUS_OVERRUN (1 << 0) |
A sample overrun has occurred. This indicates that either the host (more likely) or the FPGA is not keeping up with the incoming samples
Definition at line 2800 of file libbladeRF.h.
#define BLADERF_META_STATUS_UNDERRUN (1 << 1) |
A sample underrun has occurred. This generally only occurrs on the TX module when the FPGA is starved of samples.
Definition at line 2808 of file libbladeRF.h.
enum bladerf_format |
Sample format
Enumerator | |
---|---|
BLADERF_FORMAT_SC16_Q11 |
Signed, Complex 16-bit Q11. This is the native format of the DAC data. Values in the range [-2048, 2048) are used to represent [-1.0, 1.0). Note that the lower bound here is inclusive, and the upper bound is exclusive. Ensure that provided samples stay within [-2048, 2047]. Samples consist of interleaved IQ value pairs, with I being the first value in the pair. Each value in the pair is a right-aligned, little-endian int16_t. The FPGA ensures that these values are sign-extended. When using this format the minimum required buffer size, in bytes, is: buffer_size_min = [ 2 * num_samples * sizeof(int16_t) ] For example, to hold 2048 samples, a buffer must be at least 8192 bytes large. |
BLADERF_FORMAT_SC16_Q11_META |
This format is the same as the BLADERF_FORMAT_SC16_Q11 format, except the first 4 samples in every block* of samples are replaced with metadata organized as follows. All fields are little-endian byte order. .-------------.-----------.----------------------------------. | Byte offset | Type | Description | +-------------+-----------+----------------------------------+ | 0x00 | uint32_t | Reserved | | 0x04 | uint64_t | 64-bit Timestamp | | 0x0c | uint32_t | BLADERF_META_FLAG_* flags | `-------------`-----------`----------------------------------` *The number of samples in a block is dependent upon the USB speed being used:
When using the bladerf_sync_rx() and bladerf_sync_tx() functions, the above details are entirely transparent; the caller need not be concerned with these details. These functions take care of packing/unpacking the metadata into/from the underlying stream and convey this information through the bladerf_metadata structure. However, when using the Asynchronous data transmission and reception interface, the user is responsible for manually packing/unpacking the above metadata into/from their samples. For a more information, see the metadata.h header in the libbladeRF codebase. |
Definition at line 2729 of file libbladeRF.h.
API_EXPORT int CALL_CONV bladerf_get_timestamp | ( | struct bladerf * | dev, |
bladerf_module | mod, | ||
uint64_t * | value | ||
) |
Retrieve the specified module's current timestamp counter value from the FPGA.
This function is only intended to be used to retrieve a coarse estimate of the current timestamp when starting up a stream. It should not be used as a means to accurately retrieve the current timestamp of individual samples within a running stream. The reasons for this are:
When actively receiving a sample stream, instead use the bladerf_metadata::timestamp field (provided when using the BLADERF_FORMAT_SC16_Q11_META format) to retrieve the timestamp value associated with a block of samples. See the RX with metadata page for examples of this.
An example use-case of this function is to schedule an initial TX burst in a set of bursts;
T
, a coarse estimate the TX's current timestamp via this function.F
to occur in the future: F = T + N
. Generally, adding N
in tens to low hundreds of milliseconds is sufficient to account for timestamp retrieval overhead and stream startup.F
.Examples of the above are shown on the TX with metadata page.
[in] | dev | Device handle |
[in] | mod | Module to query |
[out] | value | Coarse timestamp value |