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/xA5/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;
if (status == 0) {
} else {
goto handle_error;
}
if (status == 0) {
} else {
goto handle_error;
}
if (status != 0) {
goto handle_error;
}
if (status != 0) {
goto handle_error;
}
status = start_rx_streams(dev_master, dev_slave);
if (status != 0) {
goto handle_error;
}
if (status != 0) {
goto handle_error;
}
status = handle_rx_operations(dev_master, dev_slave);
if (status != 0) {
goto handle_error;
}
if (status != 0) {
goto handle_error;
}
if (status != 0) {
goto handle_error;
}
#define BLADERF_CHANNEL_RX(ch)
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_init(struct bladerf *dev, bladerf_channel ch, bladerf_trigger_signal signal, struct bladerf_trigger *trigger)
API_EXPORT int CALL_CONV bladerf_trigger_fire(struct bladerf *dev, const struct bladerf_trigger *trigger)
@ BLADERF_TRIGGER_ROLE_MASTER
@ BLADERF_TRIGGER_ROLE_DISABLED
@ BLADERF_TRIGGER_ROLE_SLAVE
bladerf_trigger_signal signal
|
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
} |
|
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) |
◆ 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 1567 of file libbladeRF.h.
◆ 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/xA5/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 1606 of file libbladeRF.h.
◆ bladerf_trigger_arm()
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()
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()
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