libbladeRF  1.7.2
Nuand bladeRF library
Data Structures | Enumerations | Functions
Triggers and synchronization

Description

Trigger functionality introduced in bladeRF FPGA v0.6.0 allows TX and/or RX samples to be gated via a trigger signal. This allows multiple devices to synchronize their TX/RX operations upon the reception of a trigger event.

The set of functions presented in this section of the API provides control over this triggering functionality. It is intended that these functions be used prior to starting sample streams. Attempting to use these functions while streaming may yield undefined and undesirable behavior. These functions are thread-safe.

For devices running at the same sample rate, the trigger event should achieve synchronization within +/- 1 sample on each device in the chain.

As of FPGA v0.6.0, J71 pin 4 (mini_exp_1) has been allocated as the trigger signal. However, this API section is designed to allow future signals to be added, including users' software and hardware customizations.

Note
Important: Ensure that you disarm triggers before stopping sample streams (i.e., calling bladerf_enable_module() with enable = false). Otherwise, the operation of shutting down streams will block for the entire duration of the stream timeout (or infinitely if the timeouts were set to 0).

The standard usage of these functions is shown below. This example assumes:

int status;
// Allocate and initialize a bladerf_trigger structure for each
// trigger in the system.
struct bladerf_trigger trig_master, trig_slave;
status = bladerf_trigger_init(dev_master, module, signal, &trig_master);
if (status == 0) {
trig_master.role = BLADERF_TRIGGER_ROLE_MASTER;
} else {
goto handle_error;
}
status = bladerf_trigger_init(dev_slave1, module, signal, &trig_slave);
if (status == 0) {
master_rx.role = BLADERF_TRIGGER_ROLE_SLAVE;
} else {
goto handle_error;
}
// Arm the triggering functionality on each device
status = bladerf_trigger_arm(dev_master, &trig_master, true, 0, 0);
if (status != 0) {
goto handle_error;
}
status = bladerf_trigger_arm(dev_slave, &trig_slave, true, 0, 0);
if (status != 0) {
goto handle_error;
}
// Call bladerf_sync_config() and bladerf_sync_rx() on each device.
// Ensure the timeout parameters used are long enough to accommodate
// the expected time until the trigger will be fired.
status = start_rx_streams(dev_master, dev_slave);
if (status != 0) {
goto handle_error;
}
// Fire the trigger signal
status = bladerf_trigger_fire(dev_master, &trig_master);
if (status != 0) {
goto handle_error;
}
// Handle RX signals and then shut down streams.
// Synchronized samples should now be reaching the host following the
// reception of the external trigger signal.
status = handle_rx_operations(dev_master, dev_slave);
if (status != 0) {
goto handle_error;
}
// Disable triggering on all devices to restore normal RX operation
trig_master.role = BLADERF_TRIGGER_ROLE_DISABLED;
status = bladerf_trigger_arm(dev_master, &trig_master, false, 0, 0);
if (status != 0) {
goto handle_error;
}
status = bladerf_trigger_arm(dev_master, &trig_slave, false, 0, 0);
if (status != 0) {
goto handle_error;
}

Data Structures

struct  bladerf_trigger
 

Enumerations

enum  bladerf_trigger_role { BLADERF_TRIGGER_ROLE_INVALID = -1, BLADERF_TRIGGER_ROLE_DISABLED, BLADERF_TRIGGER_ROLE_MASTER, BLADERF_TRIGGER_ROLE_SLAVE }
 
enum  bladerf_trigger_signal {
  BLADERF_TRIGGER_INVALID = -1, BLADERF_TRIGGER_J71_4, BLADERF_TRIGGER_USER_0 = 128, BLADERF_TRIGGER_USER_1,
  BLADERF_TRIGGER_USER_2, BLADERF_TRIGGER_USER_3, BLADERF_TRIGGER_USER_4, BLADERF_TRIGGER_USER_5,
  BLADERF_TRIGGER_USER_6, BLADERF_TRIGGER_USER_7
}
 

Functions

API_EXPORT int CALL_CONV bladerf_trigger_init (struct bladerf *dev, bladerf_module module, bladerf_trigger_signal signal, struct bladerf_trigger *trigger)
 
API_EXPORT int CALL_CONV bladerf_trigger_arm (struct bladerf *dev, const struct bladerf_trigger *trigger, bool arm, uint64_t resv1, uint64_t resv2)
 
API_EXPORT int CALL_CONV bladerf_trigger_fire (struct bladerf *dev, const struct bladerf_trigger *trigger)
 
API_EXPORT int CALL_CONV bladerf_trigger_state (struct bladerf *dev, const struct bladerf_trigger *trigger, bool *is_armed, bool *has_fired, bool *fire_requested, uint64_t *resv1, uint64_t *resv2)
 

Enumeration Type Documentation

This value denotes the role of a device in a trigger chain.

Enumerator
BLADERF_TRIGGER_ROLE_INVALID 

Invalid role selection

BLADERF_TRIGGER_ROLE_DISABLED 

Triggering functionality is disabled on this device. Samples are not gated and the trigger signal is an input.

BLADERF_TRIGGER_ROLE_MASTER 

This device is the trigger master. Its trigger signal will be an output and this device will determine when all devices shall trigger.

BLADERF_TRIGGER_ROLE_SLAVE 

This device is the trigger slave. This device's trigger signal will be an input and this devices will wait for the master's trigger signal assertion.

Definition at line 1661 of file libbladeRF.h.

Trigger signal selection

This selects pin or signal used for the trigger.

BLADERF_TRIGGER_J71_4 is the only valid option as of FPGA v0.6.0.

The BLADERF_TRIGGER_USER_* values have been added to allow users to modify both hardware and software implementations to add custom triggers, while maintaining libbladeRF API compatibility. Official bladeRF releases will not utilize these user signal IDs.

Enumerator
BLADERF_TRIGGER_INVALID 

Invalid selection

BLADERF_TRIGGER_J71_4 

J71 pin 4 (mini_exp_1)

BLADERF_TRIGGER_USER_0 

Reserved for user SW/HW customizations

BLADERF_TRIGGER_USER_1 

Reserved for user SW/HW customizations

BLADERF_TRIGGER_USER_2 

Reserved for user SW/HW customizations

BLADERF_TRIGGER_USER_3 

Reserved for user SW/HW customizations

BLADERF_TRIGGER_USER_4 

Reserved for user SW/HW customizations

BLADERF_TRIGGER_USER_5 

Reserved for user SW/HW customizations

BLADERF_TRIGGER_USER_6 

Reserved for user SW/HW customizations

BLADERF_TRIGGER_USER_7 

Reserved for user SW/HW customizations

Definition at line 1697 of file libbladeRF.h.

Function Documentation

API_EXPORT int CALL_CONV bladerf_trigger_arm ( struct bladerf *  dev,
const struct bladerf_trigger trigger,
bool  arm,
uint64_t  resv1,
uint64_t  resv2 
)

Configure and (dis)arm a trigger on the specified device.

Note
If trigger->role is set to BLADERF_TRIGGER_ROLE_DISABLED, this will inherently disarm an armed trigger and clear any fire requests, regardless of the value of arm.
Parameters
[in]devDevice to configure
[in]triggerTrigger configure
[in]arm(Re)Arm trigger if true, disarm if false
[in]resv1Reserved for future use. Set to 0.
[in]resv2Reserved for future use. Set to 0.
Warning
Configuring two devices in the trigger chain (or both RX and TX on a single device) as masters can damage the associated FPGA pins, as this would cause contention over the trigger signal. Ensure only one device in the chain is configured as the master!
Returns
0 on success, value from Error codes list on failure
API_EXPORT int CALL_CONV bladerf_trigger_fire ( struct bladerf *  dev,
const struct bladerf_trigger trigger 
)

Fire a trigger event.

Calling this functiona with a trigger whose role is anything other than BLADERF_TRIGGER_REG_MASTER will yield a BLADERF_ERR_INVAL return value.

Parameters
[in]devDevice handle
[in]triggerTrigger to assert
Returns
0 on success, value from Error codes list on failure
API_EXPORT int CALL_CONV bladerf_trigger_init ( struct bladerf *  dev,
bladerf_module  module,
bladerf_trigger_signal  signal,
struct bladerf_trigger trigger 
)

Initialize a bladerf_trigger structure based upon the current configuration of the specified trigger signal.

While it is possible to simply declare and manually fill in a bladerf_trigger structure, it is recommended to use this function to retrieve the current role and options values.

Parameters
[in]devDevice to query
[in]moduleModule to query
[in]signalTrigger signal to query
[out]triggerUpdated to describe trigger
Returns
0 on success, value from Error codes list on failure
API_EXPORT int CALL_CONV bladerf_trigger_state ( struct bladerf *  dev,
const struct bladerf_trigger trigger,
bool *  is_armed,
bool *  has_fired,
bool *  fire_requested,
uint64_t *  resv1,
uint64_t *  resv2 
)

Query the fire request status of a master trigger

Parameters
[in]devDevice handle
[in]triggerTrigger to query
[out]is_armedSet to true if the trigger is armed, and false otherwise. May be NULL.
[out]has_firedSet to true if the trigger has fired, and false otherwise. May be NULL.
[out]fire_requestedOnly applicable to a trigger master. Set to true if a fire request has been previously submitted. May be NULL.
[out]resv1Reserved for future use. This field is written as 0 if not set to NULL.
[out]resv2Reserved for future use. This field is written as 0 if not set to NULL.
Returns
0 on success, value from Error codes list on failure