libbladeRF  2.4.0-git
Nuand bladeRF library
Modules | Typedefs | Macros | Functions
Streaming

Description

This section defines the streaming APIs.

Modules

 Formats
 This section defines the available sample formats and metadata flags.
 
 Synchronous API
 This group of functions presents synchronous, blocking calls (with optional timeouts) for transmitting and receiving samples.
 
 Asynchronous API
 This interface gives the API user full control over the stream and buffer management, at the cost of added complexity.
 

Typedefs

typedef uint64_t bladerf_timestamp
 

Macros

#define BLADERF_PRIuTS   PRIu64
 
#define BLADERF_PRIxTS   PRIx64
 
#define BLADERF_SCNuTS   SCNu64
 
#define BLADERF_SCNxTS   SCNx64
 

Functions

API_EXPORT int CALL_CONV bladerf_enable_module (struct bladerf *dev, bladerf_channel ch, bool enable)
 
API_EXPORT int CALL_CONV bladerf_get_timestamp (struct bladerf *dev, bladerf_direction dir, bladerf_timestamp *timestamp)
 

Typedef Documentation

◆ bladerf_timestamp

typedef uint64_t bladerf_timestamp

Timestamp, in ticks

A channel's timestamp typically increments at the sample rate.

See also
Format macros for fprintf() and fscanf(): BLADERF_PRIuTS, BLADERF_PRIxTS, BLADERF_SCNuTS, BLADERF_SCNxTS

Definition at line 1817 of file libbladeRF.h.

Macro Definition Documentation

◆ BLADERF_PRIuTS

#define BLADERF_PRIuTS   PRIu64

printf format for timestamps in unsigned decimal

Definition at line 2044 of file libbladeRF.h.

◆ BLADERF_PRIxTS

#define BLADERF_PRIxTS   PRIx64

printf format for timestamps in hexadecimal

Definition at line 2046 of file libbladeRF.h.

◆ BLADERF_SCNuTS

#define BLADERF_SCNuTS   SCNu64

scanf format for timestamps in unsigned decimal

Definition at line 2048 of file libbladeRF.h.

◆ BLADERF_SCNxTS

#define BLADERF_SCNxTS   SCNx64

scanf format for timestamps in hexadecimal

Definition at line 2050 of file libbladeRF.h.

Function Documentation

◆ bladerf_enable_module()

API_EXPORT int CALL_CONV bladerf_enable_module ( struct bladerf *  dev,
bladerf_channel  ch,
bool  enable 
)

Enable or disable the RF front end of the specified direction.

RF front ends must always be enabled prior to streaming samples on the associated interface.

When a synchronous stream is associated with the specified channel, this will shut down the underlying asynchronous stream when enable = false.

When transmitting samples, be sure to provide ample time for TX samples reach the RF front-end before calling this function with enable = false. (This can be achieved easily when using metadata, as shown on this page.)

Parameters
devDevice handle
[in]chChannel
[in]enabletrue to enable, false to disable
Returns
0 on success, value from Error codes list on failure

◆ bladerf_get_timestamp()

API_EXPORT int CALL_CONV bladerf_get_timestamp ( struct bladerf *  dev,
bladerf_direction  dir,
bladerf_timestamp timestamp 
)

Retrieve the specified stream's current timestamp counter value from the FPGA.

This function is only intended to be used to retrieve a coarse estimate of the current timestamp when starting up a stream. It should not be used as a means to accurately retrieve the current timestamp of individual samples within a running stream. The reasons for this are:

  • The timestamp counter will have advanced during the time that the captured value is propagated back from the FPGA to the host
  • The value retrieved in this manner is not tightly-coupled with specific sample positions in the stream.

When actively receiving a sample stream, instead use the bladerf_metadata::timestamp field (provided when using the BLADERF_FORMAT_SC16_Q11_META format) to retrieve the timestamp value associated with a block of samples. See the RX with metadata page for examples of this.

An example use-case of this function is to schedule an initial TX burst in a set of bursts:

  • Configure and start a TX stream using the BLADERF_FORMAT_SC16_Q11_META format.
  • Retrieve timestamp \(T\), a coarse estimate the TX's current timestamp via this function.
  • Schedule the first burst, \(F\) to occur in the future: \(F = T + N\). Generally, adding \(N\) in tens to low hundreds of milliseconds is sufficient to account for timestamp retrieval overhead and stream startup.
  • Schedule additional bursts relative to the first burst \(F\).

Examples of the above are shown on the TX with metadata page.

Parameters
devDevice handle
[in]dirStream direction
[out]timestampCoarse timestamp value
Returns
0 on success, value from Error codes list on failure