docs: Add N320 frontend correction section

2 files changed, 164 insertions, 1 deletions

diff --git a/host/docs/calibration.dox b/host/docs/calibration.dox
index 90beda82d..68c8b5b2e 100644
--- a/host/docs/calibration.dox
+++ b/host/docs/calibration.dox
@@ -1,4 +1,4 @@
-/*! \page page_calibration Device Calibration
+/*! \page page_calibration Device Calibration and Frontend Correction
 
 \tableofcontents
 
@@ -131,5 +131,110 @@ Using tx_waveforms as an example, the user can apply this argument as follows:
 
     tx_waveforms --args="addr=192.168.10.2,ignore-cal-file=1" --freq=100e6 --rate=1e6
 
+
+\section calibration_fe_corr Frontend Corrections
+
+The calibrations for IQ imbalance and DC offset compensation rely on frontend
+correction logic that is located in the FPGA.
+
+Note that USRP E310, E320, N320, and B200-Series use a dedicated RFIC which does
+its own calibration. For those, any calibrations are very device-specific and
+are not covered in this section.
+
+\subsection calibration_fe_corr_dc_offset Single-Tap DC Offset Compensation
+
+A DC offset is a fixed voltage that is permanently present on the signal of
+interest. It is an additive error, meaning if the signal of interest is x(t),
+the actual, observed signal y(t) includes a constant offset:
+
+\f[
+    y(t) = x(t) + D
+\f]
+
+If the constant value D is known, it can simply be subtracted again. For this
+reason, the DC offset compensation consists of a simple adder. The calibration
+tool `uhd_cal_tx_dc_offset` will estimate the value D' which minimizes the DC
+offset for various frequencies (i.e., D' is approximately equal to -D).
+
+To program the adder, set the DC offset correction value using these API calls:
+
+- uhd::usrp::multi_usrp::set_tx_dc_offset()
+- uhd::usrp::multi_usrp::set_rx_dc_offset()
+- uhd::rfnoc::radio_control::set_tx_dc_offset()
+- uhd::rfnoc::radio_control::set_rx_dc_offset()
+
+For RX DC offset compensation, the estimation of D can be difficult. Therefore,
+the RX DC offset compensation also includes an automatic mode, which acts as a
+notch filter around DC. It is implemented as a single-tap IIR filter with the
+following difference equation:
+
+\f[
+    y[k] = x[k] - \alpha * y[k-1]
+\f]
+
+The values for \f$\alpha\f$ are device-dependent, but the default value is \f$2^{-20}\f$.
+
+To enable the automatic DC offset correction, call one of these API calls with
+an argument of 'true':
+
+- uhd::usrp::multi_usrp::set_rx_dc_offset()
+- uhd::rfnoc::radio_control::set_rx_dc_offset()
+
+DC offset is often caused by LO leakage. It is therefore advised to offset-tune
+the radio to avoid having the LO in the band of interest. The DC offset
+compensation will not only remove LO spurs, but also affect the signal of
+interest if the LO is within the band of interest.
+
+Superheterodyne receivers such as the TwinRX do usually not require DC offset
+correction values.
+
+\subsection calibration_fe_corr_iq_offset Single-Point IQ offset compensation
+
+In order to correct IQ imbalance, the user can specify two real values A and B.
+In the FPGA, the complex signal is modified according to the following equation:
+
+\f[
+\begin{pmatrix}
+I' \\
+Q'
+\end{pmatrix}
+=
+\begin{pmatrix}
+A+1 & 0 \\
+B   & 1 \\
+\end{pmatrix}
+\begin{pmatrix}
+I \\
+Q
+\end{pmatrix}
+\f]
+
+This is a normalized version of the usual correction matrix for IQ imbalance
+which is easier to implement in the FPGA. Because the top-left value of this
+matrix depends on the magnitude error of the IQ imbalance, and the bottom row
+depends on the phase error, the value "A" is often referred to as the "magnitude
+correction value", and the value "B" is referred to as the "phase correction value".
+These values are however not identical to the actual phase and magnitude error
+caused by IQ imbalance.
+
+The `uhd_cal_tx_iq_balance` and `uhd_cal_rx_iq_balance` tools will simply search
+for A and B values which minimize the error caused by IQ imbalance.
+
+Notes:
+- The API calls uhd::usrp::multi_usrp::set_rx_iq_balance() and
+  uhd::usrp::multi_usrp::set_tx_iq_balance() take complex numbers as a correction
+  value, which is generated by `std::complex<double>(A, B)`. The complex math is
+  not necessary, given the correction algorithm, but the argument was chosen due
+  to its symmetry to the DC offset correction APIs, and also because treating the
+  correction value as a complex number lets it be handled and stored easily and
+  exactly as with the DC offset correction.
+- This correction algorithm is suboptimal for high bandwidths, albeit better
+  than nothing.
+
+IQ imbalance is caused by the inphase and quadrature paths of a direct-conversion
+receiver being slightly different in amplitude as well as their phase not being
+exactly 90 degrees apart (due to analog components). It is therefore not
+required for superheterodyne architectures like the TwinRX.
+
 */
 // vim:ft=doxygen:
diff --git a/host/docs/usrp_n3xx.dox b/host/docs/usrp_n3xx.dox
index 67be84cd3..5b641aae7 100644
--- a/host/docs/usrp_n3xx.dox
+++ b/host/docs/usrp_n3xx.dox
@@ -1479,6 +1479,64 @@ QSFP+ lane 1 | Unused | Unused | Unused       | 10 GbE       | Aurora
 QSFP+ lane 2 | Unused | Unused | Unused       | Unused       | Aurora
 QSFP+ lane 3 | Unused | Unused | Unused       | Unused       | Aurora
 
+\subsection n3xx_rh_frontend_corrections N320/N321 Frontend Corrections
+
+In an unmodified FPGA image, N320/N321 perform several steps of digital signal
+processing between the RFNoC Radio block and the ADC/DAC.
+
+It should be noted that the DACs/ADCs run at twice the master clock rate (e.g.,
+if the master clock rate is 250 MHz, the DACs/ADCs are clocked at 500 MHz). We
+perform a sample rate conversion to the master clock rate within the FPGA.
+
+```
+  ┌───────┐  ┌──────────────┐   ┌─────────────┐  ┌──────────────┐         ┌─────┐
+  │       │  │ TX           │   │TX           │  │ Halfband     │ 2x MCR  │     │
+  │       ├─>│ IQ Offset    ├──>│DC Offset    ├─>│ Interpolator ├────────>│ DAC │
+  │       │  │ Compensation │   │Compensation │  │ (47 taps)    │         │     │
+  │ RFNoC │  └──────────────┘   └─────────────┘  └──────────────┘         └─────┘
+  │ Radio │
+  │ Block │  ┌──────────────┐   ┌─────────────┐  ┌──────────────┐         ┌─────┐
+  │       │  │ RX           │   │RX           │  │Halfband      │ 2x MCR  │     │
+  │       │<─┤ IQ Offset    │<──┤DC Offset    │<─┤Decimator     │<────────┤ ADC │
+  │       │  │ Compensation │   │Compensation │  │(47 taps)     │         │     │
+  └───────┘  └──────────────┘   └─────────────┘  └──────────────┘         └─────┘
+```
+
+The IQ and DC offset compensation components can be controlled from the host
+side using the correction APIs. The following snippet shows the control of these
+APIs from the host side using the multi_usrp APIs:
+
+~~~{.cpp}
+// Generate an N320/N321 multi_usrp object
+auto usrp = uhd::usrp::multi_usrp::make("type=n3xx");
+// Set TX IQ offset value on channel zero:
+usrp->set_tx_iq_balance(my_tx_iq_offset_value, 0);
+// Set TX DC offset value on channel zero:
+usrp->set_tx_dc_offset(my_tx_dc_offset_value, 0);
+// Set RX IQ offset value on channel zero:
+usrp->set_tx_iq_balance(my_rx_iq_offset_value, 0);
+// Enable auto-RX-DC-offset on all channels:
+usrp->set_rx_dc_offset(true);
+// Set RX DC offset value to specific value on channel zero:
+usrp->set_tx_dc_offset(my_tx_dc_offset_value, 0);
+~~~
+
+When using the RFNoC API, use the uhd::rfnoc::radio_control API calls with the
+same names.
+
+Notes:
+- Other than the RX DC offset calibration, there are no automatic compensation
+  procedures. N320 uses a simple, single-tap IIR filter for automatic DC offset
+  correction (like X310).
+- The automatic RX DC offset correction acts as a notch filter around the LO
+  frequency.
+- For more details on the internals of these corrections, see \ref calibration_fe_corr.
+
+The halfband decimators/interpolators are not configurable. They are 47-tap
+halfband filters with the following coefficients:
+
+-62, 0, 194, 0, -440, 0, 855, 0, -1505, 0, 2478, 0, -3900, 0, 5990, 0, -9187, 0, 14632, 0, -26536, 0, 83009, 131071, 83009, 0, -26536, 0, 14632, 0, -9187, 0, 5990, 0, -3900, 0, 2478, 0, -1505, 0, 855, 0, -440, 0 194, 0, -62.
+
 \subsection n3xx_rh_eeprom_flags EEPROM flags
 
 EEPROM flags can be set with