libbladeRF  2.2.1
Nuand bladeRF library
Modules | Enumerations | Functions
Formats

Description

This section defines the available sample formats and metadata flags.

Modules

 Metadata structure and flags
 

Enumerations

enum  bladerf_format { BLADERF_FORMAT_SC16_Q11, BLADERF_FORMAT_SC16_Q11_META }
 

Functions

API_EXPORT int CALL_CONV bladerf_interleave_stream_buffer (bladerf_channel_layout layout, bladerf_format format, unsigned int buffer_size, void *samples)
 
API_EXPORT int CALL_CONV bladerf_deinterleave_stream_buffer (bladerf_channel_layout layout, bladerf_format format, unsigned int buffer_size, void *samples)
 

Enumeration Type Documentation

◆ 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.

 .--------------.--------------.
 | Bits 31...16 | Bits 15...0  |
 +--------------+--------------+
 |   Q[15..0]   |   I[15..0]   |
 `--------------`--------------`

When using this format the minimum required buffer size, in bytes, is:

\( buffer\_size\_min = (2 \times num\_samples \times num\_channels \times sizeof(int16\_t)) \)

For example, to hold 2048 samples for one channel, a buffer must be at least 8192 bytes large.

When a multi-channel bladerf_channel_layout is selected, samples will be interleaved per channel. For example, with BLADERF_RX_X2 or BLADERF_TX_X2 (x2 MIMO), the buffer is structured like:

 .-------------.--------------.--------------.------------------.
 | Byte offset | Bits 31...16 | Bits 15...0  |    Description   |
 +-------------+--------------+--------------+------------------+
 |    0x00     |     Q0[0]    |     I0[0]    |  Ch 0, sample 0  |
 |    0x04     |     Q1[0]    |     I1[0]    |  Ch 1, sample 0  |
 |    0x08     |     Q0[1]    |     I0[1]    |  Ch 0, sample 1  |
 |    0x0c     |     Q1[1]    |     I1[1]    |  Ch 1, sample 1  |
 |    ...      |      ...     |      ...     |        ...       |
 |    0xxx     |     Q0[n]    |     I0[n]    |  Ch 0, sample n  |
 |    0xxx     |     Q1[n]    |     I1[n]    |  Ch 1, sample n  |
 `-------------`--------------`--------------`------------------`

Per the buffer_size_min formula above, 2048 samples for two channels will generate 4096 total samples, and require at least 16384 bytes.

Implementors may use the interleaved buffers directly, or may use bladerf_deinterleave_stream_buffer() / bladerf_interleave_stream_buffer() if contiguous blocks of samples are desired.

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        |
 |  0x10..end  |            | Payload                          |
 `-------------`------------`----------------------------------`

*The number of samples in a block is dependent upon the USB speed being used:

  • USB 2.0 Hi-Speed: 256 samples
  • USB 3.0 SuperSpeed: 512 samples

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 API interface, the user is responsible for manually packing/unpacking the above metadata into/from their samples.

See also
Metadata structure and flags
The src/streaming/metadata.h header in the libbladeRF codebase.

Definition at line 2040 of file libbladeRF.h.

Function Documentation

◆ bladerf_deinterleave_stream_buffer()

API_EXPORT int CALL_CONV bladerf_deinterleave_stream_buffer ( bladerf_channel_layout  layout,
bladerf_format  format,
unsigned int  buffer_size,
void *  samples 
)

Deinterleaves samples into contiguous blocks after MIMO RX.

This function deinterleaves a multi-channel interleaved buffer, as described by the BLADERF_FORMAT_SC16_Q11 format. The output is in the format described as the input to this function's inverse, bladerf_interleave_stream_buffer().

If the BLADERF_FORMAT_SC16_Q11_META format is specified, the first 16 bytes will skipped.

Parameters
[in]layoutStream direction and layout
[in]formatData format to use
[in]buffer_sizeThe size of the buffer, in samples. Note that this is the entire buffer, not just a single channel.
samplesBuffer to process. The user is responsible for ensuring this buffer contains exactly buffer_size samples.
Returns
0 on success, value from Error codes list on failure

◆ bladerf_interleave_stream_buffer()

API_EXPORT int CALL_CONV bladerf_interleave_stream_buffer ( bladerf_channel_layout  layout,
bladerf_format  format,
unsigned int  buffer_size,
void *  samples 
)

Interleaves contiguous blocks of samples in preparation for MIMO TX.

Given a buffer loaded with data as such:

 .-------------------.--------------.--------------.------------------.
 |    Byte offset    | Bits 31...16 | Bits 15...0  |    Description   |
 +-------------------+--------------+--------------+------------------+
 |  0x00 + 0*chsize  |     Q0[0]    |     I0[0]    |  Ch 0, sample 0  |
 |  0x04 + 0*chsize  |     Q0[1]    |     I0[1]    |  Ch 0, sample 1  |
 |  0x08 + 0*chsize  |     Q0[2]    |     I0[2]    |  Ch 0, sample 2  |
 |  0x0c + 0*chsize  |     Q0[3]    |     I0[3]    |  Ch 0, sample 3  |
 |        ...        |      ...     |      ...     |        ...       |
 |  0x00 + 1*chsize  |     Q1[0]    |     I1[0]    |  Ch 1, sample 0  |
 |  0x04 + 1*chsize  |     Q1[1]    |     I1[1]    |  Ch 1, sample 1  |
 |  0x08 + 1*chsize  |     Q1[2]    |     I1[2]    |  Ch 1, sample 2  |
 |  0x0c + 1*chsize  |     Q1[3]    |     I1[3]    |  Ch 1, sample 3  |
 |        ...        |      ...     |      ...     |        ...       |
 `-------------------`--------------`--------------`------------------`

where \(chsize = \frac{sizeof(buffer)}{num\_channels}\).

This function interleaves the samples in the manner described by the BLADERF_FORMAT_SC16_Q11 format, in place. Each channel must have \(buffer\_size / num\_channels\) samples, and they must be concatenated in order.

If the BLADERF_FORMAT_SC16_Q11_META format is specified, the first 16 bytes will skipped.

This function's inverse is bladerf_deinterleave_stream_buffer().

Parameters
[in]layoutStream direction and layout
[in]formatData format to use
[in]buffer_sizeThe size of the buffer, in samples. Note that this is the entire buffer, not just a single channel.
samplesBuffer to process. The user is responsible for ensuring this buffer contains exactly buffer_size samples.
Returns
0 on success, value from Error codes list on failure