1 files changed, 106 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: