libbladeRF: Triggers

| libbladeRF 2.2.1-git Nuand bladeRF library

Data Structures | Enumerations | Functions
Triggers
Channel control

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

Note
  As of FPGA v0.6.0, `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.
  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).

These functions are thread-safe.

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

- The two devices are connected such they share a common ground and their `mini_exp[1]` pins are connected. `mini_exp[1]` is J71-4 on bladeRF x40/x115, and J51-1 on bladeRF xA4/xA9.
- Both devices are already configured to utilize a common clock signal via the external SMB connection. Generally, this will consist of one device to outputting its reference clock via the SMB clock port, and configuring the other device(s) to use the SMB clock port as a reference clock input. This may be achieved using the bladerf_set_smb_mode() function, found in the SMB clock port control section.

int status;
bladerf_channel channel = BLADERF_CHANNEL_RX(0);
bladerf_trigger_signal signal = BLADERF_TRIGGER_J71_4;
// 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, channel, signal, &trig_master);
if (status == 0) {
trig_master.role = BLADERF_TRIGGER_ROLE_MASTER;
} else {
goto handle_error;
}
status = bladerf_trigger_init(dev_slave1, channel, 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;
}
trig_slave.role = BLADERF_TRIGGER_ROLE_DISABLED;
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_J51_1, BLADERF_TRIGGER_MINI_EXP_1, 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_channel ch, 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

## ◆ bladerf_trigger_role

enum bladerf_trigger_role

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 1542 of file libbladeRF.h.

## ◆ bladerf_trigger_signal

enum bladerf_trigger_signal

Trigger signal selection

This selects pin or signal used for the trigger.

Note
  BLADERF_TRIGGER_J71_4, BLADERF_TRIGGER_J51_1, and BLADERF_TRIGGER_MINI_EXP_1 are the only valid options as of FPGA v0.6.0. All three values have the same behavior and may be used interchangably.

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] on x40/x115
BLADERF_TRIGGER_J51_1 | J51 pin 1, mini_exp[1] on xA4/xA9
BLADERF_TRIGGER_MINI_EXP_1 | mini_exp[1], hardware-independent
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 1581 of file libbladeRF.h.

## Function Documentation

## ◆ bladerf_trigger_arm()

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

  | dev | Device to configure
  [in] | trigger | Trigger configure
  [in] | arm | (Re)Arm trigger if true, disarm if false
  [in] | resv1 | Reserved for future use. Set to 0.
  [in] | resv2 | Reserved 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

## ◆ bladerf_trigger_fire()

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

  | dev | Device handle
  [in] | trigger | Trigger to assert

Returns
  0 on success, value from Error codes list on failure

## ◆ bladerf_trigger_init()

API_EXPORT int CALL_CONV bladerf_trigger_init | ( | struct bladerf * | dev,
|  | bladerf_channel | ch,
|  | 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

  | dev | Device to query
  [in] | ch | Channel
  [in] | signal | Trigger signal to query
  [out] | trigger | Updated to describe trigger

Returns
  0 on success, value from Error codes list on failure

## ◆ bladerf_trigger_state()

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

  | dev | Device handle
  [in] | trigger | Trigger to query
  [out] | is_armed | Set to true if the trigger is armed, and false otherwise. May be NULL.
  [out] | has_fired | Set to true if the trigger has fired, and false otherwise. May be NULL.
  [out] | fire_requested | Only applicable to a trigger master. Set to true if a fire request has been previously submitted. May be NULL.
  [out] | resv1 | Reserved for future use. This field is written as 0 if not set to NULL.
  [out] | resv2 | Reserved 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

BLADERF_TRIGGER_ROLE_DISABLED
@ BLADERF_TRIGGER_ROLE_DISABLED
Definition: libbladeRF.h:1550
bladerf_trigger_signal
bladerf_trigger_signal
Definition: libbladeRF.h:1581
BLADERF_TRIGGER_ROLE_MASTER
@ BLADERF_TRIGGER_ROLE_MASTER
Definition: libbladeRF.h:1556
bladerf_channel
int bladerf_channel
Definition: libbladeRF.h:624
bladerf_trigger::signal
bladerf_trigger_signal signal
Definition: libbladeRF.h:1607
bladerf_trigger::channel
bladerf_channel channel
Definition: libbladeRF.h:1605
BLADERF_TRIGGER_J71_4
@ BLADERF_TRIGGER_J71_4
Definition: libbladeRF.h:1583
BLADERF_TRIGGER_ROLE_SLAVE
@ BLADERF_TRIGGER_ROLE_SLAVE
Definition: libbladeRF.h:1563
bladerf_trigger_init
API_EXPORT int CALL_CONV bladerf_trigger_init(struct bladerf *dev, bladerf_channel ch, bladerf_trigger_signal signal, struct bladerf_trigger *trigger)
bladerf_trigger_fire
API_EXPORT int CALL_CONV bladerf_trigger_fire(struct bladerf *dev, const struct bladerf_trigger *trigger)
bladerf_trigger
Definition: libbladeRF.h:1604
bladerf_trigger_arm
API_EXPORT int CALL_CONV bladerf_trigger_arm(struct bladerf *dev, const struct bladerf_trigger *trigger, bool arm, uint64_t resv1, uint64_t resv2)
BLADERF_CHANNEL_RX
#define BLADERF_CHANNEL_RX(ch)
Definition: libbladeRF.h:639