| libbladeRF 2.6.0-git-fcf94233-dirty Nuand bladeRF library

Loading...
Searching...
No Matches
Topics | Enumerations | Functions
Formats
Streaming

## Description

This section defines the available sample formats and metadata flags.

## Topics
| Metadata structure and flags

## 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

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_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] | 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_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

  format | Format 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] | 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