libbladeRF  2.5.0
Nuand bladeRF library
Modules | Enumerations | Functions
Formats
Streaming

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 , BLADERF_FORMAT_PACKET_META , BLADERF_FORMAT_SC8_Q7 ,
  BLADERF_FORMAT_SC8_Q7_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

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.

 .--------------.--------------.
 | 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     | uint16_t   | Reserved                         |
 |    0x02     |  uint8_t   | Stream flags                     |
 |    0x03     |  uint8_t   | Meta version ID                  |
 |    0x04     | uint64_t   | 64-bit Timestamp                 |
 |    0x0c     | uint32_t   | BLADERF_META_FLAG_* flags        |
 |  0x10..end  |            | Payload                          |
 `-------------`------------`----------------------------------`

For IQ sample meta mode, the Meta version ID and Stream flags should currently be set to values 0x00 and 0x00, respectively.

*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.
BLADERF_FORMAT_PACKET_META 

This format is for exchanging packets containing digital payloads with the FPGA. A packet is generall a digital payload, that the FPGA then processes to either modulate, demodulate, filter, etc.

All fields are little-endian byte order.

 .-------------.------------.----------------------------------.
 | Byte offset |   Type     | Description                      |
 +-------------+------------+----------------------------------+
 |    0x00     | uint16_t   | Packet length (in 32bit DWORDs)  |
 |    0x02     |  uint8_t   | Packet flags                     |
 |    0x03     |  uint8_t   | Packet core ID                   |
 |    0x04     | uint64_t   | 64-bit Timestamp                 |
 |    0x0c     | uint32_t   | BLADERF_META_FLAG_* flags        |
 |  0x10..end  |            | Payload                          |
 `-------------`------------`----------------------------------`

A target core (for example a modem) must be specified when calling the bladerf_sync_rx() and bladerf_sync_tx() functions.

When in packet mode, lengths for all functions and data formats are expressed in number of 32-bit DWORDs. As an example, a 12 byte packet is considered to be 3 32-bit DWORDs long.

This packet format does not send or receive raw IQ samples. The digital payloads contain configurations, and digital payloads that are specific to the digital core to which they are addressed. It is the FPGA core that should generate, interpret, and process the digital payloads.

With the exception of packet lenghts, no difference should exist between USB 2.0 Hi-Speed or USB 3.0 SuperSpeed for packets for this streaming format.

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

Signed, Complex 8-bit Q8. This is the native format of the DAC data.

Values in the range [-256, 256) 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 [-256, 255].

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 15...8  | Bits  7...0  |
 +--------------+--------------+
 |    Q[7..0]   |    I[7..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(int8\_t)) \)

For example, to hold 2048 samples for one channel, a buffer must be at least 4096 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 15...8  | Bits  7...0  |    Description   |
 +-------------+--------------+--------------+------------------+
 |    0x00     |     Q0[0]    |     I0[0]    |  Ch 0, sample 0  |
 |    0x02     |     Q1[0]    |     I1[0]    |  Ch 1, sample 0  |
 |    0x04     |     Q0[1]    |     I0[1]    |  Ch 0, sample 1  |
 |    0x06     |     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 8192 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_SC8_Q7_META 

This format is the same as the BLADERF_FORMAT_SC8_Q7 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     | uint16_t   | Reserved                         |
 |    0x02     |  uint8_t   | Stream flags                     |
 |    0x03     |  uint8_t   | Meta version ID                  |
 |    0x04     | uint64_t   | 64-bit Timestamp                 |
 |    0x0c     | uint32_t   | BLADERF_META_FLAG_* flags        |
 |  0x10..end  |            | Payload                          |
 `-------------`------------`----------------------------------`

For IQ sample meta mode, the Meta version ID and Stream flags should currently be set to values 0x00 and 0x00, respectively.

*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 2064 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
Generated on Wed Feb 15 2023 02:09:26 for libbladeRF by doxygen 1.9.1