Processor Trigger Manager Module

The WARPLab Reference Design implements a Trigger Manager module that handles various types of triggers that can be used to synchronize actions among multiple nodes.

Related Components:

• MATLAB:
  • wl_trigger_manager_proc​ class
  • wl_trigger_eth_udp_broadcast​ class
• WARP Hardware:
  • warplab_trigger_proc peripheral
  • wl_trigger_manager.c​ C software
  • wl_trigger_manager.h​ C header file

User Guide

System Requirements

• Review the WARPLab 7 System Requirements

Overview

The Trigger Manager was designed to allow flexible coordination and communication between nodes. Each trigger is assigned an ID and then all configuration of the trigger manager is based on these IDs. By default, WARPLab has the following triggers:

• Input Triggers
  • External Pins (For example: EXT_IN_P0 - EXT_IN_P3, pins 12 - 15 on the debug header in the WARPLab reference design)
  • Ethernet Packets
  • Register writes (used for WARP v2 compatibility)
  • Input Energy
  • Automatic Gain Control (AGC) Done

NOTE: Each input has configuration options that can be found in the Trigger Manager Command Reference.

• Output Triggers
  • External Pins (For example: EXT_OUT_P0 - EXT_OUT_P3, pins 8 - 11 on the debug header in the WARPLab reference design)
  • Baseband
  • Automatic Gain Control (AGC) Start

NOTE: Each output can be based on a configurable set of inputs as well as a logical combination of inputs. The above diagram is replicated per trigger output, so that each one can have its own, independent configuration.

Hardware Setup

The Trigger Manager consists of both a hardware block that runs within the FPGA and a software framework to configure and use the Trigger Manager. You can see the instantiation of the Trigger Manager block as well as the default connections within the system.mhs file:

# Default configuration of the Trigger Manager in system.mhs

BEGIN w3_warplab_trigger_proc_axiw
 PARAMETER INSTANCE   = warplab_trigger_proc
 PARAMETER HW_VER     = 1.01.a
 PARAMETER C_BASEADDR = 0x77800000
 PARAMETER C_HIGHADDR = 0x7780ffff
 BUS_INTERFACE S_AXI  = axi4lite_1
 BUS_INTERFACE AXI_STR_ETH_RXD = ETH_A_AXI_STR_RXD
 PORT axi_aclk        = clk_160MHz
 PORT sysgen_clk      = clk_160MHz
 # Triggers
 PORT agc_done_in = agc_is_done
 PORT debug_0_in  = trig_0_in
 PORT debug_1_in  = trig_1_in
 PORT debug_2_in  = trig_2_in
 PORT debug_3_in  = trig_3_in
 PORT rfa_rssi    = warplab_rfa_rssi
 PORT rfb_rssi    = warplab_rfb_rssi
 PORT rfc_rssi    = net_gnd
 PORT rfd_rssi    = net_gnd
 PORT rssi_clk    = warplab_rssi_clk
 PORT trig_0_out  = baseband_trigger
 PORT trig_1_out  = agc_start
 PORT trig_2_out  = trig_2_out
 PORT trig_3_out  = trig_3_out
 PORT trig_4_out  = trig_4_out
 PORT trig_5_out  = trig_5_out
END

The trig_*_in and trig_*_out signals are connected to the debug header and can be used to externally trigger events.

Ethernet Triggers

An Ethernet Trigger is a specially formatted WARPLab Ethernet message in which the WARPLab Transport Header packet type is of type "TRIGGER" and the data directly after the transport header is the ID of the Ethernet trigger. In WARPLab, only broadcast transports (i.e. Java​ and MEX​ broadcast transports) support "TRIGGER" messages.

The Broadcast Ethernet Trigger​ is a class that is used to send an Ethernet Trigger to multiple boards using a broadcast Ethernet packet (i.e. it will send the Trigger to all nodes "simultaneously"; NOTE: There can be jitter between when Ethernet triggers are received even with WARP nodes on the same switch. To synchronize the triggering between nodes, it is best to use external triggers). To create a Broadcast Ethernet Trigger, one must be instantiated:

% Create a UDP broadcast trigger
eth_trig = wl_trigger_eth_udp_broadcast;

This will create a Broadcast Ethernet Trigger with a unique ID. A maximum of 32 Broadcast Ethernet Triggers can be created in order to guarantee that the Ethernet Trigger IDs are unique.

Once an Broadcast Ethernet Trigger has been created, then the Trigger Manager must be used to "sensitize" the node to that Ethernet Trigger ID:

% Tell each node to be ready for an Ethernet Triger that has the given ID
wl_triggerManagerCmd(nodes, 'add_ethernet_trigger', [eth_trig]);

Once a node has been "sensitized" to the given Ethernet Trigger, we can use the send() command to send the broadcast Ethernet packet containing the Ethernet Trigger:

% Send the Ethernet Trigger to all nodes
eth_trig.send();

To "de-sensitize" a node to an Ethernet Trigger, the given Ethernet Trigger can be deleted or all Ethernet Triggers can be removed

% Tell each node to not trigger on an Ethernet Triger that has the given ID
wl_triggerManagerCmd(nodes, 'delete_ethernet_trigger', [eth_trig]);

% Tell each node to remove all Ethernet Triggers
wl_triggerManagerCmd(nodes, 'clear_ethernet_triggers');

Examples

In our examples, we have two nodes, a transmitter ( nodes(1) ) and a receiver ( nodes(2) ):

NOTE: These examples are for the WARPLab 7.6.0 syntax. If looking for the legacy syntax for WARPLab 7.5.1 and prior, the please see the WARPLab 7.6.0 porting guide.

• Create a UDP broadcast trigger and set the transmitting node to trigger with an appropriate Ethernet packet

  eth_trig = wl_trigger_eth_udp_broadcast;
  wl_triggerManagerCmd(nodes(1), 'add_ethernet_trigger',[eth_trig]);
  

NOTE: This will allow a host, like Matlab, to create an Ethernet packet to begin transmission

• Read Trigger IDs into workspace:

  trig_in_ids  = wl_getTriggerInputIDs(nodes(1));
  trig_out_ids = wl_getTriggerOutputIDs(nodes(1));
  

NOTE: These trigger IDs will be the same for all nodes in the system and should not be modified by the user.

• For the transmit node, allow Ethernet to trigger the buffer baseband, the AGC, and Trigger output 0 (which is mapped by default in the WARPLab reference design to pin 8 on the debug header)

  wl_triggerManagerCmd(nodes(1), 'output_config_input_selection', [trig_out_ids.BASEBAND, trig_out_ids.AGC, trig_out_ids.EXT_OUT_P0], [trig_in_ids.ETH_A]);
  

NOTE: As of WARPLab 7.5.1, we only have to use the ETH_A trigger id to be compatible with both WARP v2 and WARP v3 hardware. In WARP v3, the Ethernet trigger can be set either through the hardware 'snooping' logic or through software. This is controlled by the set_ethernet_trigger_type command.

• For the receive node, allow the energy detector to trigger the buffer baseband and AGC core:

  wl_triggerManagerCmd(nodes(2), 'output_config_input_selection', [trig_out_ids.BASEBAND, trig_out_ids.AGC], [trig_in_ids.ENERGY_DET]);
  

Then enable the hold mode for the triggers driven by energy detection. This will prevent the buffer from being overwritten before we have a chance to read it:

wl_triggerManagerCmd(nodes(2), 'output_config_hold_mode', [trig_out_ids.BASEBAND, trig_out_ids.AGC], 'enable'); 

Then get the IDs for the interfaces on the board and setup the configuration of the energy monitoring:

ifc_ids = wl_getInterfaceIDs(nodes(2));

rssi_sum_len = 15;

wl_triggerManagerCmd(nodes(2), 'energy_config_average_length', rssi_sum_len);
wl_triggerManagerCmd(nodes(2), 'energy_config_busy_threshold', rssi_sum_len*500);
wl_triggerManagerCmd(nodes(2), 'energy_config_busy_minlength', 10);
wl_triggerManagerCmd(nodes(2), 'energy_config_interface_selection', ifc_ids.RF_ON_BOARD);

Finally, when done processing, we can clear the energy detection trigger since it is holding the output due to setting the 'output_config_hold_mode'

wl_triggerManagerCmd(nodes(2), 'output_state_clear', [trig_out_ids.BASEBAND, trig_out_ids.AGC]);

• For the receive node, allow trigger input to trigger the buffer baseband and the AGC (this example assumes the WARPLab reference design configuration where we should connect trigger output 0, pin 8 of the debug header, of the transmit node to trigger input 3, pin 15 of the debug header, of the receive node):

  wl_triggerManagerCmd(nodes(2), 'output_config_input_selection', [trig_out_ids.BASEBAND, trig_out_ids.AGC], [trig_in_ids.EXT_IN_P3]);
  

We will also enable the debounce circuitry on the trigger input to help with noise on the signal line:

wl_triggerManagerCmd(nodes(2), 'input_config_debounce_mode', [trig_in_ids.EXT_IN_P3], 'enable'); 

Since the debounce circuitry is enabled, there will be a delay at the receiver node for its input trigger. To better align the transmitter and receiver, we can artifically delay the transmitters trigger outputs that drive the buffer baseband and the AGC:

wl_triggerManagerCmd(nodes(1), 'output_config_delay', [trig_out_ids.BASEBAND, trig_out_ids.AGC], 56.25);  % 56.25ns delay (9 clock cycles @ 160 MHz)

NOTE: The 56.25 ns delay (ie 9 clock cycles at 160 MHz) was measured using the oscilloscope. If debounce is disabled, then the delay is 31.25 ns (ie 5 clock cycles at 160 MHz).

Getting Help

If you have any additional questions, please post to the ​WARP Forums.

Trigger Manager Commands

Trigger Manager commands are selected as string inputs to the wl_triggerManagerCmd method in wl_node.m​. These strings are each individual cases of the switch statement in procCmd method of wl_trigger_manager.m​.

Syntax

MATLAB allows two valid forms of syntax for calling methods

• Let N be a scalar or vector of wl_node objects
• Let command_string be a string containing a particular command
• Let arg be an argument for that command (optional)

Syntax 1: wl_triggerManagerCmd(N, command_string, arg1, arg2, ..., argN)

Syntax 2: N.wl_triggerManagerCmd(command_string, arg1, arg2, ..., argN)

These two different forms of syntax are identical and either may be used for issuing commands to WARP nodes.

Command List and Documentation

add_ethernet_trigger

Associates node to a trigger input

Arguments: (wl_trigger_manager TRIGGER)

Returns: none

delete_ethernet_trigger

De-associates node to a trigger input

Arguments: (wl_trigger_manager TRIGGER)

Returns: none

clear_ethernet_triggers

Clears all trigger associations in the node

Arguments: none

Returns: none

set_ethernet_trigger_type

Set the Ethernet trigger type

In WARP v3, the ability was added to the trigger manager to "sniff" the axi stream between the Ethernet controller and the AXI interface to the Ethernet controller, such as the AXI DMA or AXI FIFO. This allows for more predictable timing for Ethernet triggers since it does not depend on any SW interaction. However, this feature could not be added to the WARP v2 trigger manager due to differences in Ethernet components. Therefore, in reference designs since this feature was introduced, WARP v3 has used hardware for Ethernet triggers while WARP v2 has used software.

Unfortunately, this introduced a large timing difference between WARP v2 and WARP v3 when asserting the Ethernet trigger within the node in response to a broadcast Ethernet trigger. This adds a complication to experiments involving a mix of WARP v2 and WARP v3 nodes. Therefore, trigger manager v1.04.a addressed this by being able to select between using the hardware capabilities WARP v3 or using software, like WARP v2, for Ethernet triggers.

This command allows users to set whether the WARP v3 node uses hardware or software for Ethernet triggers. Since WARP v2 does not support using hardware for Ethernet triggers, this command does nothing.

Arguments: 'hardware' or 'software'

Returns: none

get_ethernet_trigger

Reads current trigger association from node

Arguments: node

Returns: (uint32 TRIGGER_ASSOCIATION) TRIGGER_ASSOCIATION: bit-wise AND of associated trigger IDs

output_config_input_selection

Selects which trigger inputs drive the selected outputs

Arguments: (uint32 OUTPUTS), (uint32 OR_INPUTS), ![optional] (uint32 AND_INPUTS)

• OUTPUTS: vector of output trigger IDs, provided by wl_getTriggerOutputIDs
  
• OR_INPUTS: vector of input trigger IDs, provided by wl_getTriggerInputIDs. Any triggers in this vector that assert will cause the output trigger to assert.
  
• AND_INPUTS: vector of input trigger IDs, provided by wl_getTriggerInputIDs. Only if all triggers in this vector assert will the output trigger assert.
  

Returns: none

NOTE: This command replaces the current input selection on the board for the specified outputs (unspecified outputs are not modified). The previous state of the output is not saved.

output_config_delay

Configures specified output triggers to be have an additional delay relative to their inputs

Arguments: (uint32 OUTPUTS), (double DELAY_NS)

• OUTPUTS: vector of output trigger IDs, provided by wl_getTriggerOutputIDs
  
• DELAY_NS: scalar value of the intended delay, specified in nanoseconds (1e-9 seconds)
  

Returns: none

output_config_hold_mode

Configures whether specified output triggers should hold their outputs once triggered

Arguments: (uint32 OUTPUTS), (boolean MODE)

• OUTPUTS: vector of output trigger IDs, provided by wl_getTriggerOutputIDs
  
• MODE: true enables output hold mode; false disables output hold mode
  

Returns: none

output_state_read

Reads current state of output triggers.

NOTE: This command is intended to be used on output triggers that have enabled their hold mode.

Arguments: (uint32 OUTPUTS)

• OUTPUTS: vector of output trigger IDs, provided by wl_getTriggerOutputIDs
  
• STATES: vector of (true, false) trigger states corresponding to state of OUTPUTS vector
  

Returns: (bool STATES)

output_state_clear

Clears current state of output triggers.

Arguments: (uint32 OUTPUTS)

• OUTPUTS: vector of output trigger IDs, provided by wl_getTriggerOutputIDs
  

Returns: none

input_config_debounce_mode

Configures specified input triggers to enable or disable debounce circuit.

NOTE: The debounce circuit adds a delay of 4 cycles, where each cycle is a duration specified in the input_delayStep_ns property of the wl_manager_proc.m class.

Arguments: (uint32 INPUTS), (boolean MODE)

• INPUTS: vector of output trigger IDs, provided by wl_getTriggerInputIDs
  
• MODE: true enables input debounce mode; false disables input debounce mode
  

Returns: none

input_config_delay

Configures specified input triggers to be have an additional delay relative to their inputs

Arguments: (uint32 INPUTS), (double DELAY_NS)

• INPUTS: vector of input trigger IDs, provided by wl_getTriggerInputIDs
  
• DELAY_NS: scalar value of the intended delay, specified in nanoseconds (1e-9 seconds)
  

Returns: none

energy_config_busy_threshold

Configures the threshold above which RSSI is considered as a "busy" medium.

Arguments: (uint32 THRESH)

• THRESH: busy threshold. For the MAX2829-based interfaces, WARP uses a 10-bit ADC for RSSI (range of [0,1023]).
  

Returns: none

Note: RSSI averaging in the core does NOT divide by the number of samples that are summed together. Averaging by N cycles means that the maximum possible RSSI post-averaging is N*1023.

energy_config_average_length

Configures the number of samples over which RSSI is averaged before it is compared to any threshold.

Arguments: (uint32 LENGTH)

• LENGTH: Number of samples over which RSSI is averaged.
  

Returns: none

NOTE: For all hardware versions, RSSI is sampled at 10 MHz. Each sample is, therefore, 100 ns.

energy_config_busy_minlength

Average RSSI samples must exceed the busy threshold for a minimum number of samples before the trigger is activated. This command sets this minimum value.

Arguments: (uint32 LENGTH)

• LENGTH: Minimum number of samples that RSSI must be busy before trigger is raised.
  

Returns: none

energy_config_interface_selection

Selects the interfaces from which energy detection should base its decision

Arguments: (uint32 IFCSELECTION)

• IFCSELECTION: One or more interfaces that the energy detector system should monitor
  

Returns: none

NOTE: IFCSELECTION is intended to be used with the return values from the wl_getInterfaceIDs method.

input_config_idelay

Configures the IDELAY values for specified input triggers.

Arguments: (uint32 INPUTS), (string TYPE), (uint32 VALUES)

• INPUTS: Vector of input trigger IDs, provided by wl_getTriggerInputIDs
  
• TYPE: 'ext_pin' or 'cm_pll' - Can modify the IDELAY for the path from the external pin or CM-PLL module
  
• VALUES: Scaler value in [0, 31] or Vector of values equal in length to the INPUTS vector
  

Returns: none

output_config_odelay

Configures the ODELAY values for specified output triggers.

Arguments: (uint32 OUTPUTS), (string TYPE), (uint32 VALUES)

• OUTPUTS: Vector of output trigger IDs, provided by wl_getTriggerOutputIDs
  
• TYPE: 'ext_pin' or 'cm_pll' - Can modify the ODELAY for the path to the external pin or CM-PLL module
  
• VALUES: Scaler value in [0, 31] or Vector of values equal in length to the OUTPUTS vector
  

Returns: none

test_trigger

Sends a test trigger

Arguments: none

Returns: none