libbladeRF 2.6.0-git
Nuand bladeRF library
Loading...
Searching...
No Matches
Formats

Description

This section defines the available sample formats and metadata flags.

Topics

Enumerations

enum  bladerf_format {
  BLADERF_FORMAT_SC16_Q11 , BLADERF_FORMAT_SC16_Q11_PACKED , BLADERF_FORMAT_SC16_Q11_META , BLADERF_FORMAT_PACKET_META ,
  BLADERF_FORMAT_SC8_Q7 , BLADERF_FORMAT_SC8_Q7_META
}

Functions

API_EXPORT const char *CALL_CONV bladerf_format_to_string (bladerf_format format)
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_PACKED 

Signed, Complex 16-bit Q11 using a 12-bit Q11 intermediate format.

This format is a BLADERF_FORMAT_SC16_Q11 equivalent to the end user. The difference lies in the intermediate SC12 Q11 packing format used by the FPGA and libbladeRF. This intermediate format allows for a 33.3% higher sample rate when bandwidth limited by the host interface. Synchronous buffer length must be a multiple of 4096 samples.

Note
While this format allows for higher sample rates over bandwidth-limited interfaces, it requires additional CPU processing for packing/unpacking. Users should benchmark to determine if the increased sample rate outweighs the added processing overhead for their specific use case.
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: 1024 samples
  • USB 3.0 SuperSpeed: 2048 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.

Warning
A packet length of (n*256-4) DWORDs will cause the synchronous buffer it's filled into to indefinitely persist. For instance, if a packet containing 252 DWORDs is filled into buffer N, buffer N will always return that first 252 dword packet. It is recommended to avoid these specific packet lengths (252, 508, 764, 1020, etc. DWORDs) until this limitation is resolved.
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 [-128, 128) 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 [-128, 127].

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 int8_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: 1024 samples
  • USB 3.0 SuperSpeed: 2048 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 2085 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_format_to_string()

API_EXPORT const char *CALL_CONV bladerf_format_to_string ( bladerf_format format)

Convert a sample format to a string suitable for printing

Parameters
formatFormat to convert to string
Returns
The string representation of the format

◆ 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