[[TracNav(WARPLab/TOC)]]

= Baseband Buffers Module Implementation =

The WARPLab Reference Design implements a [wiki:../../../Framework/Modules#Baseband Baseband] module that buffers incoming and outgoing samples from radio interfaces. It supports up to 4 interfaces, including both I/Q and RSSI. On WARP v3 hardware, each buffer is 2^15^ samples long. On WARP v2 hardware, each buffer is 2^14^ samples long.

'''Related Components:'''
 * MATLAB:
  * [source:ResearchApps/PHY/WARPLAB/WARPLab7/M_Code_Reference/classes/wl_baseband_buffers.m wl_baseband_buffers] class
 * WARP Hardware:
  * [source:ResearchApps/PHY/WARPLAB/WARPLab7/Sysgen_Reference/w3/warplab_buffers warplab_buffers] peripheral
  * warplab_agc peripheral
  * [source:ResearchApps/PHY/WARPLAB/WARPLab7/C_Code_Reference/wl_baseband.c wl_baseband] C software


= Baseband Commands =

Baseband commands are selected as string inputs to the {{{wl_basebandCmd}}} method in [browser:ResearchApps/PHY/WARPLAB/WARPLab7/M_Code_Reference/classes/wl_node.m wl_node.m]. These strings are each individual cases of the switch statement in {{{procCmd}}} method of [browser:ResearchApps/PHY/WARPLAB/WARPLab7/M_Code_Reference/classes/wl_baseband_buffers.m wl_baseband_buffers.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_basebandCmd(N, command_string, arg1, arg2, ..., argN)}}}

Syntax 2: {{{N.wl_basebandCmd(command_string, arg1, arg2, ..., argN)}}}

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

=== Optional Buffer Selection Syntax ===

Some baseband commands require the selection of one or more buffers. This requirement is specified in the below documentation with {{{Requires BUFF_SEL:}}}. If a command requires a buffer selection, then the following syntaxes are valid:

 * Let {{{buffer_selection}}} be a collection of interfaces or the string {{{'RF_ALL'}}}

Syntax 1: {{{wl_interfaceCmd(N, buffer_selection, command_string, arg1, arg2, ..., argN)}}}

Syntax 2: {{{N.wl_interfaceCmd(buffer_selection, command_string, arg1, arg2, ..., argN)}}}


== Command List and Documentation == 

=== {{{tx_delay}}} ===
Transmit delay- gets or sets the number of sample periods the baseband
waits between the trigger and starting the transmission[[BR]]


'''Requires BUFF_SEL:''' No

'''Arguments:''' none or (uint32 TX_DLY)

'''Returns:''' (uint32 TX_DLY) or none

If an argument is specified, this command enters a write mode where
that argument is written to the board. If no argument is specified,
the current value of TX_DLY is read from the board.[[BR]]



=== {{{tx_length}}} ===
Transmit length- sets the duration of each transmit cycle, in sample periods [[BR]]


'''Requires BUFF_SEL:''' No

'''Arguments:''' (uint32 TX_LEN)

'''Returns:'''   none

NOTE:  This will error if the user tries to read tx_length from the board.
the 'tx_buff_max_num_samples' command should be used to determine the 
capabilities of the board.[[BR]]



=== {{{rx_length}}} ===
Receive length- reads or sets the duration of each receive cycle, in sample periods [[BR]]


'''Requires BUFF_SEL:''' No

'''Arguments:''' (uint32 RX_LEN)

'''Returns:''' none

NOTE:  This will error if the user tries to read tx_length from the board.  
the 'tx_buff_max_num_samples' command should be used to determine the 
capabilities of the board.[[BR]]



=== {{{tx_buff_max_num_samples}}} ===
Maximum number of TX samples[[BR]]


'''Requires BUFF_SEL:''' Yes

'''Arguments:''' none

'''Returns:''' (uint32 MAX_TX_LEN)



=== {{{rx_buff_max_num_samples}}} ===
Maximum number of RX samples[[BR]]


'''Requires BUFF_SEL:''' Yes

'''Arguments:''' none

'''Returns:''' (uint32 MAX_RX_LEN)



=== {{{continuous_tx}}} ===
Enable/disable continuous transmit mode[[BR]]


'''Requires BUFF_SEL:''' No

'''Arguments:''' (boolean CONT_TX)
CONT_TX:[[BR]]
true enables continuous transmit mode[[BR]]
false disable continuous transmit mode[[BR]]

'''Returns:''' none

Restrictions on continuous transmit waveform length:[[BR]]

WARPLab 7.5.0 and higher:[[BR]]
{{{
0 to 2^15   --> Waveform will be transmitted for the exact number of samples
   > 2^15   --> Waveform must be a multiple of 2^14 samples for the waveform
                to be transmitted exactly.  Otherwise, waveform will be appended 
                with whatever IQ data is in the transmit buffer to align the 
                waveform to be a multiple of 2^14 samples.
}}}

NOTE:  In WARPLab 7.5.x, it is an error to perform a Read IQ while in continuous transmit mode.

WARPLab 7.4.0 and prior:
{{{
0 to 2^15   --> Waveform will be transmitted for the exact number of samples
   > 2^15   --> Not supported
}}}


=== {{{tx_buff_en}}} ===
Enable transmit buffer for one or more interfaces. When a buffer is enabled it will
drive samples into its associated interface when a trigger is received. The interface
itself must also be enabled (wl_interfaceCmd(...,'tx_en')) to actually transmit the samples[[BR]]


'''Requires BUFF_SEL:''' Yes

'''Arguments:''' none

'''Returns:''' none



=== {{{rx_buff_en}}} ===
Enable receive buffer for one or more interfaces. When a buffer is enabled it will
capture samples from its associated interface when a trigger is received. The interface
itself must also be enabled (wl_interfaceCmd(...,'rx_en'))[[BR]]


'''Requires BUFF_SEL:''' Yes

'''Arguments:''' none

'''Returns:''' none



=== {{{tx_rx_buff_dis}}} ===
Disable the Tx and Rx buffers for one or more interfaces. When a buffer is disabled it will not
output/capture samples when a trigger is received, even if the associated interface is enabled[[BR]]


'''Requires BUFF_SEL:''' Yes

'''Arguments:''' none

'''Returns:''' none



=== {{{read_buff_state}}} ===
Read the current state of the buffer[[BR]]


'''Requires BUFF_SEL:''' Yes

'''Arguments:''' none

'''Returns:''' Current state of the buffer:  TX, RX or STANDBY



=== {{{tx_buff_clk_freq}}} ===
Read the transmit sample clock frequency out of the buffer core.[[BR]]


'''Requires BUFF_SEL:''' No

'''Arguments:''' none

'''Returns:''' (uint32 Fs_Tx)
Fs_Tx: Tx sample frequency of buffer core in Hz[[BR]]



=== {{{rx_buff_clk_freq}}} ===
Read the receive sample clock frequency out of the buffer core.[[BR]]


'''Requires BUFF_SEL:''' No

'''Arguments:''' none

'''Returns:''' (uint32 Fs_Rx)
Fs_Rx: Rx sample frequency of buffer core in Hz[[BR]]



=== {{{rx_rssi_clk_freq}}} ===
Read the receive RSSI sample clock frequency out of the buffer core.[[BR]]


'''Requires BUFF_SEL:''' No

'''Arguments:''' none

'''Returns:''' (uint32 Fs_RxRSSI)
Fs_RxRSSI: Rx RSSI sample frequency of buffer core in Hz[[BR]]



=== {{{write_iq}}} ===
Write I/Q samples to the specified buffers. The dimensions of the buffer selection and samples matrix
must agree. The same samples can be written to multiple buffers by combining buffer IDs[[BR]]


'''Requires BUFF_SEL:''' Yes (combined BUFF_SEL values ok)

'''Arguments:''' (complex double TX_SAMPS, int OFFSET)
TX_SAMPS: matrix of complex samples. The number of columns must match the length of BUFF_SEL
OFFSET: buffer index of first sample to write (optional; defaults to 0)[[BR]]

Examples:[[BR]]
{{{
TxLength = 2^14;
Ts = 1/(wl_basebandCmd(node0,'tx_buff_clk_freq'));
t  = ![0:Ts:(TxLength-1)*Ts].';                      % column vector
X  = exp(t*1i*2*pi*3e6);                             % 3MHz sinusoid
Y  = exp(t*1i*2*pi*5e6);                             % 5MHz sinusoid

% Write X to RFA
wl_basebandCmd(node, RFA, 'write_IQ', X);

% Write X to RFA and RFB
wl_basebandCmd(node, (RFA + RFB), 'write_IQ', X);

% Write X to RFA, Y to RFB
wl_basebandCmd(node, ![RFA RFB], 'write_IQ', ![X Y]);
}}}


=== {{{write_iq_checksum}}} ===
Write IQ checksum - gets the current Write IQ checksum from the node. [[BR]]


'''Requires BUFF_SEL:''' No

'''Arguments:''' none

'''Returns:''' (uint32 WRITE_IQ_CHECKSUM)



=== {{{read_iq}}} ===
Read I/Q samples from the specified buffers. The elements of the buffer selection must be scalers which
identify a single buffer. To read multiple buffers in one call, pass a vector of individual buffer IDs[[BR]]


'''Requires BUFF_SEL:''' Yes (combined BUFF_SEL values not allowed)

'''Arguments:''' (int OFFSET, int NUM_SAMPS)
OFFSET: buffer index of first sample to read (optional; defaults to 0)[[BR]]
NUM_SAMPS: number of complex samples to read (optional; defaults to length(OFFSET:rxIQLen-1))[[BR]]

Examples:[[BR]]
{{{
% Read full buffer for RFA
%     NOTE:  size(X) will be ![rxIQLen, 1]
X = wl_basebandCmd(node, RFA, 'read_IQ');

% Read partial buffer for RFA (samples 1000:4999)
%     NOTE:  size(X) will be ![5000, 1]
X = wl_basebandCmd(node, RFA, 'read_IQ', 1000, 5000);

% Read full buffers for RFA and RFB
%     NOTE:  size(X) will be ![rxIQLen, 2]
X = wl_basebandCmd(node, ![RFA RFB], 'read_IQ');
}}}


=== {{{read_rssi}}} ===
Read RSSI samples from the specified buffers. The elements of the buffer selection must be scalers which
identify a single buffer. To read multiple buffers in one call, pass a vector of individual buffer IDs.[[BR]]

See 'read_iq' for arguments/returns[[BR]]



=== {{{agc_state}}} ===
Read AGC state from the specified buffers. The elements of the buffer selection must be scalers which 
identify a single buffer. To read multiple buffers in one call, pass a vector of individual buffer IDs[[BR]]


'''Requires BUFF_SEL:''' Yes (combined BUFF_SEL values not allowed)

'''Arguments:''' none


'''Returns:''' agc_state -- column vector per buffer BUFF_SEL
agc_state(1): RF gain chosen by AGC[[BR]]
agc_state(2): BB gain chosen by AGC[[BR]]
agc_state(3): RSSI observed by AGC at time of lock[[BR]]



=== {{{agc_thresh}}} ===
Read or write AGC threshold.[[BR]]



=== {{{agc_target}}} ===
Set the AGC target[[BR]]


'''Requires BUFF_SEL:''' No. Values apply to all RF paths

'''Arguments:''' (int32 target)
target: target receive power (in dBm)[[BR]]
default value: -16[[BR]]

'''Returns:''' none

This command is the best way to tweak AGC behavior
to apply more or less gain. For example, a target of
-5dBm will apply more gain thatn a target of -10dBm,
so the waveform will be larger at the inputs of the I
and Q ADCs.[[BR]]



=== {{{agc_dco}}} ===
Enable/disable DC offset correction[[BR]]


'''Requires BUFF_SEL:''' No

'''Arguments:''' (boolean DCO)
DCO:[[BR]]
true enables DC offset correction[[BR]]
false disable DC offset correction[[BR]]

'''Returns:''' none



=== {{{agc_trig_delay}}} ===

Command is deprecated. Use the output_config_delay[[BR]]
command of the trigger manager instead.[[BR]]



=== {{{agc_reset}}} ===
Resets the AGC to its default state[[BR]]


'''Requires BUFF_SEL:''' No. Values apply to all RF paths

'''Arguments:''' none

'''Returns:''' none



=== {{{agc_done_addr}}} ===
Sample index where AGC finished[[BR]]


'''Requires BUFF_SEL:''' No. Values apply to all RF paths

'''Arguments:''' 

'''Returns:''' (uint32) sample_index



=== {{{agc_reset_on_timeout}}} ===
Gets / Sets whether the AGC will reset on timeout[[BR]]


'''Arguments:''' 'true' or 'false'; none on read

'''Returns:'''   none on write; 'true' or 'false'



=== {{{agc_reset_timeout_value}}} ===
Gets / Sets the AGC Reset Timeout Value[[BR]]


'''Arguments:''' timeout value in usec on write; none on read

'''Returns:'''   none on write; timeout value in usec on read