libbladeRF: Formats

| libbladeRF 2.2.0-git 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 }

## 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     | 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 2039 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] | layout | Stream direction and layout
  [in] | format | Data format to use
  [in] | buffer_size | The size of the buffer, in samples. Note that this is the entire buffer, not just a single channel.
  | samples | Buffer 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] | layout | Stream direction and layout
  [in] | format | Data format to use
  [in] | buffer_size | The size of the buffer, in samples. Note that this is the entire buffer, not just a single channel.
  | samples | Buffer 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