docs: x440: Extend X4x0 Usage Manual for x440

- Extended FPGA Image Flavors sections
- Extended MCR and Converter Rates section
- Added Page for FBX daughterboard
- Added FBX_simplified_blockdiagram.png that is referenced by
  FBX daughterboard page and represents one transceiver chain.
- Added known issue regarding need for restarting MPM when mcr is
  changed and potential of dynamic QSFP28 configurations may getting
  lost.

3 files changed, 368 insertions, 96 deletions

diff --git a/host/docs/fbx.dox b/host/docs/fbx.dox
index fe67a3674..f454acab4 100644
--- a/host/docs/fbx.dox
+++ b/host/docs/fbx.dox
@@ -9,14 +9,190 @@ The FBX daughterboard is a four-channel, balun-coupled transceiver board.
 The FBX daughterboard is the daughterboard for the Ettus USRP X440.
 
 Feature list:
-- tbw
+- Frequency range (TX and RX): 30 MHz - 4 GHz (Note: UHD Tune range is 1 MHz - 4 GHz)
+- Maximum output power: up to 1 dBm (depending on Nyquist zone selection and 
+  tune frequency, see <em>TX Maximum Output Power</em> in <a href="https://www.ni.com//r/uhdx440specs">specifications</a>)
+- Maximum input power: 10 dBm (operational, see
+  <a href="https://www.ni.com//r/uhdx440specs">specifications</a> for damage levels)
 - Timed tuning is not supported by the X440, because timed tuning of the NCO
   (within the RFSoC) is not supported.
 
+See the RF section in the <a href="https://www.ni.com//r/uhdx440specs">Ettus
+USRP X440 Specifications</a> for a comprehensive FBX daughterboard
+specifications list.
+
+
 \section fbx_too Theory of Operation
 
-The FBX daughterboard has four transceiver chains. The following simplified block
-diagram shows their structure:
+The FBX daughterboard has four independent transceiver chains. The following 
+simplified block diagram shows the structure of a single chain:
+
+\image html FBX_simplified_blockdiagram.png "FBX Block Diagram (single transceiver)"
+
+It is a balun-coupled transceiver, with symmetric TX and RX path. The FBX is 
+a passive design, with no gain or filter stages and complements the direct 
+IF sampling design of the X440. Compared to most other Ettus USRPs this 
+requires consideration of the utilized Nyquist zone and resulting aliasing 
+effects. As a result, most applications will require external filters or 
+signal conditioning. UHD provides help coordinating the control of such 
+front ends in the form of the \ref page_extension.
+
+One property of this design is that signal aliases need to be considered. On 
+the ADC all observed alias tones are actually the same frequency but the RFDC 
+cannot distinguish the incoming frequencies. In contrast, the DAC will send 
+out all alias frequencies at once. Signal aliases will occur in each Nyquist 
+zone and appear as mirrored signal tones around multiples of half the converter 
+rate (Fc/2). The first Nyquist zone (N1) is defined as the frequency range 
+between 0 and Fs/2, and the second Nyquist zone (N2) stretches from Fs/2 to Fs. 
+Other Nyquist zones are defined in ascending order, each extending Fs/2. The 
+following diagrams illustrate the Nyquist zones and tone aliases for select 
+converter rates (Fc). Note that the diagrams do not show that the achievable 
+passband within a Nyquist zone gets smaller the higher the Nyquist zone order.
+The passband in lower Nyquist zones can be roughly calculated as 0.4 * Fc. 
+
+Nyquist Zone example with Converter Rate = 1GS/s
+```
+   ^                                                                                    ____
+   │____   _________   _________   _________   _____                                   |    \
+   │ N1 \ / N2 │ N3 \ / N4 │ N5 \ / N6 │ N7 \ / N8 │                              ^    |     |
+   │     │     │     │     |     │     |     │     |                              |    |     |
+   │   ^ │ ^   │   ^ │ ^   │   ^ │ ^   │   ^ │ ^   │                              |    |     |
+   │   │ │ |   │   │ │ |   │   │ │ |   │   │ │ |   │   ^                          ┴    └─────┘
+   │   │ │ |   │   │ │ |   │   │ │ |   │   │ │ |   │   |   ^       ^            Tone   Nyquist
+   └───┴─┼─┴───┼───┴─┼─┴───┼───┴─┼─┴───┼───┴─┼─┴───┼───┴───┴───────┴──>                 Zone
+               1           2           3           4     f/GHz
+                                                                       
+```
+Nyquist Zone example with Converter Rate = 4GS/s
+```
+   ^                                                                                    ____
+   │______________________   ______________________                                    |    \
+   │           N1         \ /          N2          │                              ^    |     |
+   │                       |                       |                              |    |     |
+   │               ^       │       ^               │                              |    |     |
+   │               │       │       |               │               ^              ┴    └─────┘
+   │               │       │       |               │               |            Tone   Nyquist
+   └───────────┬───┴───────┼───────┴───┬───────────┼───────────────┴──>                 Zone
+               1           2           3           4     f/GHz
+                                                                       
+```
+Applications should prefer converter rates that can contain the desired 
+signal spectrum in a single Nyquist zone, or split the signal spectrum among 
+multiple channels and devices. For details about the relationship between 
+converter rate (Fc) and IQ sample rate (Fs) refer to 
+\ref x4xx_usage_mcrs "Master Clock Rates".
+
+The Xilinx RFDC used in the X440 consists of an integrated design that
+interleaves multiple converters to realize the high RF-ADC rates. In this design
+an RF-ADC consists of 8 interleaved sub-ADCs. The resulting interleaved 
+spurs are minimized by the integrated self-calibration executed by UHD. For 
+details on controlling the self calibration execution refer to \ref x4xx_adc_self_cal.
+
+\section fbx_too_dctrl Digital Control
+
+All switches on the FBX are controlled via registers that are exposed as a
+subset of the Radio RFNoC block register space (starting at address 0x80000).
+The design differentiates between switches that are directly controlled
+by the FPGA and support fast switching times, and ones that the FPGA controls
+via an I/O expander.
+
+The first kind are the switches referenced by the UHD driver as RF switches
+(e.g. RFx_TDDS, RFx_RX_RFS, RFx_TX_RX_RFS). These can also be controlled
+via ATR states (see also \ref fbx_atr).
+
+The second kind are the SYNC_CTRL switches. Use of the I/O expander makes
+their operation slower and requires readbacks from the I/O expander. For that
+reason they are at the utmost set when an antenna setting is changed, and
+their position is unaffected by ATR state changes. These switches are intended
+to connect signal chains to optional synchronization signals, that UHD may
+support in a future release.
+
+\section fbx_antenna Antenna Ports
+
+The FBX has two MMPX ports per channel, called "TX/RX0" and "RX1".
+In addition, the antenna values can be set to "CAL_LOOPBACK"
+to loop back the Tx path into the Rx path (this is sometimes required for
+calibration purposes). The Rx antenna value can also be set to "TERMINATION" to
+terminate the Rx path.
+
+Use the uhd::usrp::multi_usrp::get_rx_antennas() or uhd::usrp::multi_usrp::get_tx_antennas()
+API calls to enumerate the valid antenna names. When using RFNoC API, use the
+uhd::rfnoc::radio_control::get_rx_antennas() and
+uhd::rfnoc::radio_control::get_tx_antennas() calls, respectively.
+
+Additionally, the FBX has a single MMPX port, called SYNC IN. This input is
+intended to route an optional synchronization signal to the signal chains, and
+may be supported by UHD in a future release (see also SYNC_CTRL switches in 
+\ref fbx_too_dctrl). 
+
+\subsection fbx_leds Status LEDs
+
+The FBX daughterboard is equipped with two LEDs per channel, one for "TX/RX0"
+and one for "RX1". These LEDs behave as follows:
+
+| LED State | TX/RX0               | RX1               |
+|-----------|----------------------|-------------------|
+| Off       | Port is inactive     | Port is inactive  |
+| Green     | Port is receiving    | Port is receiving |
+| Red       | Port is transmitting | N/A               |
+
+\section fbx_sensors Sensors
+
+Every channel has one "locked" sensor for the LO stages (`nco_locked`). 
+A "virtual" sensor called `lo_locked` confirms that the LOs that are currently 
+engaged are locked. The "NCO lock" sensor is not on the daughterboard (it is 
+part of the RFSoC FPGA), but to simplify the API it was categorized like 
+typical LO lock sensors. The NCO "unlock" state is not used to signify a loss 
+of reference lock, but to signal that the NCO is still in reset.
+
+Additionally, the FBX has a temperature sensor: `temperature`. While the UHD
+API allows addressing a sensor based on direction (RX/TX) and channel (0/1/2/3),
+there is only one physical temperature sensor, and it will return the same value
+regardless of which channel or direction is selected.
+
+The following API calls can be used to enumerate available sensors, and query
+their values:
+- multi_usrp API:
+  - uhd::usrp::multi_usrp::get_rx_sensor_names()
+  - uhd::usrp::multi_usrp::get_rx_sensor()
+  - uhd::usrp::multi_usrp::get_tx_sensor_names()
+  - uhd::usrp::multi_usrp::get_tx_sensor()
+- RFNoC API:
+  - uhd::rfnoc::radio_control::get_rx_sensor_names()
+  - uhd::rfnoc::radio_control::get_rx_sensor()
+  - uhd::rfnoc::radio_control::get_tx_sensor_names()
+  - uhd::rfnoc::radio_control::get_tx_sensor()
+
+\section fbx_atr Auto-Transmit-Receive Registers (ATR)
+
+Like other USRPs, the X440 provides GPIOs to the daughterboards that 
+communicate the RX/TX state. The FBX is, by default, configured to switch 
+settings based on the current state (RX, TX, full duplex, idle). For example, 
+the TX/RX antenna is switched between the TX and RX channels depending on 
+the state.
+
+Example: Assume the device is transmitting, but not receiving, on channel 0. 
+The FPGA will set the ATR pins for channel 0 to a binary value of 0b10, which 
+equals a decimal value of 2. This mode of using the ATR pins is called the 
+"classic ATR" mode and is the default behavior. UHD currently supports 
+configuring channel 0 and 1 as ATR sources for GPIO pins.
+
+The FBX daughterboard provides one additional mode of utilizing those pins:
+- "FPGA controlled": This is similar to the classic ATR mode, but it combines
+  the pins from channels 0 and 1. The downside is that these channels are no
+  longer independent, but it allows using 16 combinations instead of four 
+  as in the classic ATR mode.
+
+Note that combining the "FPGA controlled" mode on one channel with the 
+"classic" mode on the other channel would yield a possibly conflicting 
+configuration.
+
+Usage of these modes is considered highly advanced usage of FBX. The "FPGA
+controlled" mode is not supported by UHD without custom modifications (it is
+possible, however, to manually write to the appropriate registers to use this
+mode). Using this mode would also require modifications of the FPGA image to
+add custom controls to the ATR GPIO pins.
+
 
 */
 // vim:ft=doxygen:
diff --git a/host/docs/res/FBX_simplified_blockdiagram.png b/host/docs/res/FBX_simplified_blockdiagram.png
new file mode 100644
index 000000000..ee5547bb2
--- /dev/null
+++ b/host/docs/res/FBX_simplified_blockdiagram.png
diff --git a/host/docs/usrp_x4xx.dox b/host/docs/usrp_x4xx.dox
index 5033b3c2f..7692c89ef 100644
--- a/host/docs/usrp_x4xx.dox
+++ b/host/docs/usrp_x4xx.dox
@@ -98,7 +98,7 @@ The X4x0 has a higher maximum analog bandwidth than previous USRPs. The USRP X41
 can provide rates up to 500 Msps, resulting in a usable analog bandwidth of up to 400 MHz.
 
 The USRP X440 can, depending on the FPGA image used, provide up to 2048 Msps of
-sampling rate, resulting  in a usable analog bandwidth of up to 1.6 GHz on two
+sampling rate, resulting in a usable analog bandwidth of up to 1.6 GHz on two
 channels, or 8 channels at 500 Msps.
 
 In order to facilitate the higher bandwidth, UHD may use a technology called
@@ -112,10 +112,10 @@ capabilities of these analog front-end cards, see \ref page_zbx.
 
 \subsection x4xx_overview_x440_dboards USRP X440 Daughterboard Connectivity
 
-The Ettus USRP X440 contains two FBX daughterboards. Unlike the ZBX daughtercards,
+The Ettus USRP X440 contains two FBX daughterboards. Unlike the ZBX daughterboards,
 they have no analog mixers or filters, but directly connect the converters to the
 RF connectors. To find out more about the
-capabilities of these analog front-end cards, see \ref page_zbx and \ref page_fbx.
+capabilities of these analog front-end cards, see \ref page_fbx.
 
 \subsection x4xx_overview_panels Front and Back Panels
 
@@ -300,18 +300,20 @@ The Ettus USRP X4x0 has various network interfaces:
 The configuration files for these network interfaces are stored in:
 `/data/network/<interface>.network`.
 
-Interface Name | Description                            | Default Configuration | Configuration File | Example: X4_200 FPGA image |
----------------|----------------------------------------|-----------------------|--------------------|----------------------------|
-`eth0`         | RJ45                                   | DHCP                  | eth0.network       | DHCP                       |
-`int0`         | Internal                               | 169.254.0.1/24        | int0.network       | 169.254.0.1/24             |
-`sfp0`         | QSFP28 0 (4-lanes interface or lane 0) | 192.168.10.2/24       | sfp0.network       | 192.168.10.2/24            |
-`sfp0_1`       | QSFP28 0 (lane 1)                      | 192.168.11.2/24       | sfp0_1.network     | 192.168.11.2/24            |
-`sfp0_2`       | QSFP28 0 (lane 2)                      | 192.168.12.2/24       | sfp0_2.network     | 192.168.12.2/24            |
-`sfp0_3`       | QSFP28 0 (lane 3)                      | 192.168.13.2/24       | sfp0_3.network     | 192.168.13.2/24            |
-`sfp1`         | QSFP28 1 (4-lanes interface or lane 0) | 192.168.20.2/24       | sfp1.network       | N/C                        |
-`sfp1_1`       | QSFP28 1 (lane 1)                      | 192.168.21.2/24       | sfp1_1.network     | N/C                        |
-`sfp1_2`       | QSFP28 1 (lane 2)                      | 192.168.22.2/24       | sfp1_2.network     | N/C                        |
-`sfp1_3`       | QSFP28 1 (lane 3)                      | 192.168.23.2/24       | sfp1_3.network     | N/C                        |
+Interface Name | Description                           | Default Configuration | Configuration File | Ex.: X4_xxx FPGA image | Ex.: CG_xxx FPGA image |
+---------------|---------------------------------------|-----------------------|--------------------|------------------------|------------------------|
+`eth0`         | RJ45                                  | DHCP                  | eth0.network       | DHCP                   | DHCP                   |
+`int0`         | Internal                              | 169.254.0.1/24        | int0.network       | 169.254.0.1/24         | 169.254.0.1/24         |
+`sfp0`         | QSFP28 0 (4-lane interface or lane 0) | 192.168.10.2/24       | sfp0.network       | 192.168.10.2/24        | 192.168.10.2/24        |
+`sfp0_1`       | QSFP28 0 (lane 1)                     | 192.168.11.2/24       | sfp0_1.network     | 192.168.11.2/24        | N/A                    |
+`sfp0_2`       | QSFP28 0 (lane 2)                     | 192.168.12.2/24       | sfp0_2.network     | 192.168.12.2/24        | N/A                    |
+`sfp0_3`       | QSFP28 0 (lane 3)                     | 192.168.13.2/24       | sfp0_3.network     | 192.168.13.2/24        | N/A                    |
+`sfp1`         | QSFP28 1 (4-lane interface or lane 0) | 192.168.20.2/24       | sfp1.network       | N/C                    | 192.168.20.2/24        |
+`sfp1_1`       | QSFP28 1 (lane 1)                     | 192.168.21.2/24       | sfp1_1.network     | N/C                    | N/A                    |
+`sfp1_2`       | QSFP28 1 (lane 2)                     | 192.168.22.2/24       | sfp1_2.network     | N/C                    | N/A                    |
+`sfp1_3`       | QSFP28 1 (lane 3)                     | 192.168.23.2/24       | sfp1_3.network     | N/C                    | N/A                    |
+
+For FPGA image capability comparison and FPGA naming convention refer to \ref x4xx_updating_fpga_types
 
 For example, `/data/network/eth0.network` by default looks like:
 ```
@@ -534,45 +536,51 @@ The following port types are available:
 | C         | 100 GbE        |
 | U         | Unused         |
 
-If the QSFP 1 configuration is not specified, then that port is unused. XG and
-CG indicate that each QSFP port has a single 10 GbE or 100 GbE, respectively
+If the QSFP 1 configuration is not specified, then that port is unused. CG 
+indicates that each QSFP port has a single 100 GbE, respectively
 (same as previous USRPs). The 'G' in this case is short for 'gigabit'.
 
-As of UHD 4.4, the following USRP X410 images flavors are shipped with UHD:
+As of UHD 4.5, the following USRP X410 images flavors are shipped with UHD:
 
-| FPGA Image Flavor | Bandwidth | QSFP28 Port 0 Interface | QSFP28 Port 1 Interface | DDC/DUC | DRAM                     |
-|-------------------|-----------|-------------------------|-------------------------|---------|--------------------------|
-| X4_200            | 200 MHz   | 4x 10 GbE (All Lanes)   | Unused                  | Yes     | Yes (4 GiB, 4-Ch Replay) |
-| UC_200            | 200 MHz   | Unused                  | 100 GbE                 | Yes     | Yes (4 GiB, 4-Ch Replay) |
-| CG_400            | 400 MHz   | 100 GbE                 | 100 GbE                 | No      | No                       |
+| FPGA Image Flavor | Number of \n Channels | Bandwidth \n per Channel | QSFP28 Port 0 Interface | QSFP28 Port 1 Interface | DDC/DUC | DRAM                     |
+|-------------------|-----------------------|--------------------------|-------------------------|-------------------------|---------|--------------------------|
+| X4_200            | 4 (2 per ZBX)         | 200 MHz                  | 4x 10 GbE (All Lanes)   | Unused                  | Yes     | Yes (4 GiB, 4-Ch Replay) |
+| UC_200            | 4 (2 per ZBX)         | 200 MHz                  | Unused                  | 100 GbE                 | Yes     | Yes (4 GiB, 4-Ch Replay) |
+| CG_400            | 4 (2 per ZBX)         | 400 MHz                  | 100 GbE                 | 100 GbE                 | No      | No                       |
 
 As of UHD 4.5, the following USRP X440 images flavors are shipped with UHD:
 
-| FPGA Image Flavor | Bandwidth | QSFP28 Port 0 Interface | QSFP28 Port 1 Interface | DDC/DUC | DRAM                     |
-|-------------------|-----------|-------------------------|-------------------------|---------|--------------------------|
-| X4_400            | 400 MHz   | 4x 10 GbE (All Lanes)   | Unused                  | No      | No                       |
-| CG_400            | 400 MHz   | 100 GbE                 | 100 GbE                 | No      | No                       |
-| X4_1600           | 1600 MHz  | 4x 10 GbE (All Lanes)   | Unused                  | No      | Yes (8 GiB, 2-Ch Replay) |
-| CG_1600           | 1600 MHz  | 100 GbE                 | 100 GbE                 | No      | No                       |
+| FPGA Image Flavor | Number of \n Channels | Bandwidth \n per Channel | QSFP28 Port 0 Interface | QSFP28 Port 1 Interface | DDC/DUC | DRAM                     |
+|-------------------|-----------------------|--------------------------|-------------------------|-------------------------|---------|--------------------------|
+| X4_400            | 8 (4 per FBX)         | 400 MHz                  | 4x 10 GbE (All Lanes)   | Unused                  | No      | Yes (8 GiB, 8-Ch Replay) |
+| CG_400            | 8 (4 per FBX)         | 400 MHz                  | 100 GbE                 | 100 GbE                 | No      | No                       |
+| X4_1600           | 2 (1 per FBX)         | 1600 MHz                 | 4x 10 GbE (All Lanes)   | Unused                  | No      | Yes (8 GiB, 2-Ch Replay) |
+| CG_1600           | 2 (1 per FBX)         | 1600 MHz                 | 100 GbE                 | 100 GbE                 | No      | No                       |
 
 The following list shows some potential use-cases for different FPGA images:
 
-- `X4_200` or `UC_200`: 200 MHz analog bandwidth, or below (using RFNoC
+- `X4_200` or `UC_200`: 200 MHz analog bandwidth per channel, or below (using RFNoC
   DDC/DUCs), streaming between the X410 and an external host computer, or
   streaming to/from on-board DRAM using the RFNoC Record/Replay block.
-- `CG_400`: Full-rate (400 MHz analog bandwidth) streaming between the X410 and
+- `CG_400`: 400 MHz analog bandwidth streaming per channel between the X4x0 and
   an external host computer. The current implementation requires dual 100 GbE
   connections for 4 full-duplex channels or a single 100 GbE connection for 2
   full-duplex channels.
-- `X4_400`: Full-rate (400 MHz analog bandwidth) streaming to/from on-board
+- `X4_400`: 400 MHz analog bandwidth per channel streaming to/from on-board
   DRAM using the RFNoC Record/Replay block. Up to 4 x 10 GbE connections may be
   used to access the DRAM from an external host computer. Note that 10 GbE is
   not fast enough for continuous full-rate streaming at this rate.
+  (For USRP X410 this design is available as source, and not shipped as precompiled bitfile)
+- `CG_1600` (USRP X440 only): Highest bandwidth streaming between the X440 and 
+  an external host computer. Streaming requires one 100 GbE connections per 
+  channel. Due to the available FPGA bandwidth only 2 channels are enabled,
+  the first channel on each daughterboard.
 - `X4_1600` (USRP X440 only): Highest bandwidth streaming including DRAM support.
   This is a useful image for capture/replay from DRAM. Note that streaming at
   full rate (2 Gsps) exceeds the streaming capabilities of 10 GbE, which means
   that direct streaming (without using DRAM) is not possible at these rates with
-  this image.
+  this image. Due to the available FPGA bandwidth only 2 channels are enabled,
+  the first channel on each daughterboard.
 
 Run `make help` in the `fpga/usrp3/top/x400` directory of the UHD repository to
 see a complete list of FPGA images that can be built, some of which are
@@ -581,22 +589,28 @@ experimental (unsupported).
 The analog bandwidth determines the available master clock rates. See section
 \ref x4xx_usage_mcrs for more information on available mater clock rates.
 
-Applications that require more than 200 MHz bandwidth should use the full rate
-of the 400 MHz images. Applications that require 200 MHz bandwidth or less
-should use the 200 MHz images and make use the DDC/DUC for lower rates.
+Applications that require 200 MHz bandwidth or less (X410 only)
+should use the 200 MHz images and make use the DDC/DUC for lower rates. 
+Applications that require higher bandwidth and use limited signal durations 
+should use the DRAM enabled X4_xxx images to ease streaming requirements.
+Applications that require the full device bandwidth or require on-the-fly 
+data access should use the CG_xxx images. 
 
 \subsubsection x4xx_pl_dram DDR4 Memory for Programmable Logic
 
 The USRP X4x0 has two banks of DDR4 memory available for use by the
-programmable logic in the FPGA. Each bank has a 4 GiB capacity. The DRAM can be
-run at up to 2.4 GT/s but is clocked at 2.0 GT/s by default to ease FPGA timing
-closure.
-
-The FPGA memory controller exposes each bank of DRAM as a 512-bit interface
-clocked at 250 MHz. This interface is then presented to RFNoC as up to 4 AXI
-interfaces. For 200 MHz images, each AXI interface is 64-bit at 250 MHz. For
-400 MHz images, each AXI interface is 128-bit at 250 MHz. This allows for the
-maximum sample rate to be read and written to DRAM for up to 4 channels
+programmable logic in the FPGA. Each bank has a 4 GiB capacity. Because the
+banks are independent, applications are normally limited to 4 GiB per channel.
+The DRAM can be run at up to 2.4 GT/s but is clocked at 2.0 GT/s on X410 by
+default to ease FPGA timing closure.
+
+The FPGA memory controller exposes each bank of DRAM as a 512-bit interface,
+which is clocked at 300 MHz for X440 and 250 MHz on X410. This interface is
+then presented to RFNoC as multiple AXI interfaces (one interface for each RF
+channel). Each AXI interface is sized in order to match the expected throughput
+for a single channel. For example, on X410 200 MHz images, each AXI interface
+is 64-bit at 250 MHz. For 400 MHz images, each AXI interface is 128-bit at 250
+MHz. This allows for the maximum sample rate to be read and written to DRAM
 simultaneously.
 
 The default use for the DRAM is the Replay RFNoC block, which supports
@@ -932,30 +946,76 @@ For a list of which arguments can be passed into make(), see Section
  cal_ch_list           | Selects the channels to be calibrated.                                          | cal_ch_list=1;2;3
  skip_adc_selfcal      | Skips the ADC self-cal on clock-reconfig.                                       | skip_adc_selfcal=true
 
-\subsection x4xx_usage_mcrs Master clock rates
+\subsection x4xx_usage_mcrs Master Clock Rates
 
-The available master clock rates depend on the FPGA image flavor that is
+The available master clock rates (MCR) depend on the FPGA image flavor that is
 currently installed on the device (see \ref x4xx_updating_fpga_types).
 
-The USRP X410 has a small number of fixed master clock rates available for
-every image type:
-
+\paragraph x410_usage_mcrs USRP X410
+The USRP X410 has a few fixed MCR available for every image type:
 The 200 MHz images allow master clock rates of 245.76 MHz or 250 MHz. The 400
 MHz images allow master clock rates of 491.52 MHz or 500 MHz.
 
-The USRP X440 has a much broader range of available master clock rates.
+\paragraph x440_usage_mcrs USRP X440
+The USRP X440 has a much broader range of available master clock rates, and 
+supports a fixed set of rates between 125 Msps and 2 Gsps. The maximum available 
+MCR is further dependent on the FPGA image type. The master clock rate depends 
+on the converter rate (Fc) and selected RFDC divider, and in the absence of 
+further digital down or up conversation, equals to the IQ sample rate. 
+\n Simplified signal path block diagram for X440
+```
 
-FIXME link to the tool or amend this
+  Analog Frequency       Converter    Tuning Frequency           Master Clock         IQ Sample
+     Range [Hz]        Rate (Fc) [Hz]     Ftune [Hz]           Rate (MCR) [Hz]     Rate (Fs) [S/s]
+  ┌─────────────┐      ┌───────────────────────────────────────────┐  │  ┌─────────────┐  │
+  │             │      │    Xilinx RFDC (RF Digital Converter)     │  │  │             │  │  ┌──────────────────┐
+  │             │      │┌─────────┐   ┌─────────┐  ┌──────────────┐│  V  │    RFNoC    │  V  │   Transport      │
+  │ FPX (Balun) │──────││   ADC   │___|   IQ    │__│ Decimation   ││─────│    Radio    │─────│      with        │
+  │             │      ││   DAC   │   │  Mixer  │  │ Interpolation││     │    Block    │     │ Data Rate [Bit/s]│
+  │             │      │└─────────┘   └─────────┘  └──────────────┘│     │             │     └──────────────────┘
+  └─────────────┘      └─────^────────────^────────────────────────┘     └─────────────┘
+                             │            │                          
+                             │            │               
+                         Converter       NCO            
+                           Clock        Clock
+                       [1..4.096 GHz] [0..4 GHz]
 
+```
+For a full clocking block diagram see \ref x4xx_too_clocking
+
+By default, UHD will choose the highest possible converter rate that can be 
+achieved with one of the available RFDC dividers (2,4,8). If an MCR can be 
+achieved with multiple converter rates, then the converter rate can be 
+overridden with the `converter_rate` device argument (see also 
+\ref x4xx_usage_args). The broad range of available MCR required a focus on a 
+select set of MCR during testing and design validation. For the X440, these are:
+| Master Clock \n Rate (MCR) | Converter \n Rate (Fc) | RFDC Divider | Digital Bandwidth \n (0.8 * MCR) | Available in\n Default Bitfile | Motivation/ \n Common Usage |
+|:--:|:--:|:--:|:--:|:--:|--|
+|368.64 MHz|2.94912 GHz| 8 | 295 MHz | xx_400, \n xx_1600 | Same Fc as X410, UHD default |
+|2000 MHz | 4.0 GHz | 2 | 1600 MHz | xx_1600 | Maximum Digital Bandwidth |
+|1000 MHz | 4.0 GHz | 4 | 1600 MHz | xx_1600 |  |
+|500 MHz | 4.0 GHz | 8 | 400 MHz | xx_400, \n xx_1600 | Maximum Fc |
+|400 MHz | 3.2 GHz | 8 | 320 MHz | xx_400, \n xx_1600 |  |
+|360 MHz | 2.88 GHz | 8 | 288 MHz | xx_400, \n xx_1600 | L-Band Applications |
+|327.68 MHz | 2.62144 GHz | 8 | 262 MHz | xx_400, \n xx_1600 | L-Band Applications |
+|307.2 MHz | 2.4576 GHz | 8 | 245.76 MHz | xx_400, \n xx_1600 | Highest PLL VCO Rate |
+|125 MHz | 1.0 GHz | 8 | 100 MHz | xx_400, \n xx_1600 | Minimum Fc |
+
+\n
 For all devices, changing the master clock rate during a running session is not
 supported. Once a UHD session is initialized, the master clock rate is fixed.
-For that reason, uhd::usrp::multi_usrp::get_master_clock_rate_range() will not return
-a list of multiple entries, but only the currently active master clock rate.
-This behaviour is identical to that of the USRP X3x0.
+For that reason, uhd::usrp::multi_usrp::get_master_clock_rate_range() will 
+not return a list of multiple entries, but only the currently active 
+master clock rate. This behavior is identical to that of the USRP X3x0.\n
+When the master clock rate or clock and time sources change, UHD needs to
+perform clock reconfigurations. On the X440 this currently requires that UHD
+restarts MPM during session creation, which may cause non-persistent 
+network configurations for the QSFP28 interfaces to be reset. See 
+\ref x4xx_getting_started_network_connectivity_ifcs for a persistent 
+configuration option that is maintained during MPM reboots. 
 
 When selecting a master clock rate, UHD will coerce to the next available master
 clock rate. Example:
-
 ~~~{.cpp}
 // Assumption: We are using a USRP X410, with a 200 MHz FPGA image
 auto usrp = uhd::usrp::multi_usrp::make("type=x4xx,master_clock_rate=245e6");
@@ -967,6 +1027,7 @@ std::cout << usrp->set_master_clock_rate(250e6) << std::endl; // Prints 245.76e6
 std::cout << usrp->get_master_clock_rate_range().start() << std::endl; // Prints 245.76e6
 std::cout << usrp->get_master_clock_rate_range().stop() << std::endl; // Prints 245.76e6
 ~~~
+For details see \ref x4xx_too_convrate. 
 
 \subsection x4xx_usage_timedcmds Timed Commands
 
@@ -1015,9 +1076,9 @@ using the `gps_enabled` GPS sensor (see also \ref x4xx_usage_sensors). When
 disabled, none of the sensors will return useful (if any) values.
 
 When selecting `gpsdo` as a clock source, the GPS will always be enabled. Note
-that acquiring a GPS lock can take some time after enabling the GPS, so if a UHD
-application is enabling the GPS dynamically, it might take some time before a
-GPS lock is reported.
+that acquiring a GPS lock can take some time after enabling the GPS, so if 
+a UHD application is enabling the GPS dynamically, it might take some time 
+before a GPS lock is reported.
 
 \subsection x4xx_usage_gpio Front-Panel Programmable GPIOs
 
@@ -1026,16 +1087,19 @@ FPGA. For a description of the GPIO control API, see \subpage page_x400_gpio_api
 
 There are multiple sources that can control the state of the GPIO lines.
 UHD has the capability of controlling which source each pin is driven from.
-The source control block is located in the X4x0 core logic block in the FPGA, and is also accessible
-via MPM. There are also local registers in the source control block that control the state
-of GPIOs manually if none of the additionally supported control schemes are required.
-
-Source selection is performed via an array of muxes, each accessible via an independent register.
-The diagram below indicates the arrangement of muxes controlling GPIO source selection.
+The source control block is located in the X4x0 core logic block in the FPGA, 
+and is also accessible via MPM. There are also local registers in the 
+source control block that control the state of GPIOs manually if none of the 
+additionally supported control schemes are required.
+
+Source selection is performed via an array of muxes, each accessible via an 
+independent register. The diagram below indicates the arrangement of muxes 
+controlling GPIO source selection.
 \image html x4xx_dio_source_muxes.svg "X4x0 GPIO Source Control" width=60%
 
-UHD has access to all radio-controlled blocks. In the diagram above, this includes
-one ATR DIO control block and one digital interface block for each radio.
+UHD has access to all radio-controlled blocks. In the diagram above, 
+this includes one ATR DIO control block and one digital interface block 
+for each radio.
 
 When ATR control is selected as the source, it uses the Daughterboard state to determine
 the behavior of the GPIOs. The Daughterboard state is the concatenation of the
@@ -1064,8 +1128,8 @@ DB 0 / RF 1 | A:1
 DB 1 / RF 0 | B:0
 DB 1 / RF 1 | B:1
 
-The RF ports on the front panel of the X440 + FBX correspond to the following
-subdev specifications:
+The RF ports on the front panel of the X440 + FBX (xx_400 images) correspond 
+to the following subdev specifications:
 
 Label       | Subdev Spec
 ------------|------------
@@ -1078,9 +1142,18 @@ DB 1 / RF 1 | B:1
 DB 1 / RF 2 | B:2
 DB 1 / RF 3 | B:3
 
-The subdev spec slot identifiers "A" and "B" are not reflected on the front panel.
-They were set to match valid subdev specifications of previous USRPs, maintaining
-backward compatibility.
+The RF ports on the front panel of the X440 + FBX (xx_1600 images) correspond 
+to the following subdev specifications (Note: The xx_1600 images enable the 
+use of only 2 channels, corresponding to the first channel of each daughterboard):
+
+Label       | Subdev Spec
+------------|------------
+DB 0 / RF 0 | A:0
+DB 1 / RF 0 | B:0
+
+The subdev spec slot identifiers "A" and "B" are not reflected on the 
+front panel. They were set to match valid subdev specifications of previous 
+USRPs, maintaining backward compatibility.
 
 These values can be used for uhd::usrp::multi_usrp::set_rx_subdev_spec() and
 uhd::usrp::multi_usrp::set_tx_subdev_spec() as with other USRPs.
@@ -1293,20 +1366,44 @@ high rates.
 
 \subsection x4xx_too_convrate Converter Rates
 
-The RFSoC internally has a decimation/interpolation chain which can resample by
-a factor of up to 8. For example, if the converter is running at 2 GHz, then
-the RFSoC can produce a signal at a master clock rate of 1 Gsps, 500 Msps, or
-250 Msps (it must resample at least by 2 to convert the signal to a complex one).
-
-By default, UHD will choose the largest converter rate available. This can be
-overridden by specifying the `converter_rate` device argument (see also \ref x4xx_usage_args).
+The USRP X4x0 uses a Xilinx RFSoC Gen1, whose RFDC includes a decimation/interpolation 
+block which can resample by a factor of up to 8. For example, if the converter 
+is running at 2 GHz, then the RFSoC can produce a signal at a master clock 
+rate of 1 Gsps, 500 Msps, or 250 Msps (it must resample at least by 2 to 
+convert the signal to a complex one). In the USRP X4x0 design all ADC and DAC 
+converter rates are identical and use the same RFDC decimation/interpolation 
+settings.
+
+\paragraph x410_too_convrate USRP X410
+The USRP X410 only supports a few fixed master clock rates (see \ref x4xx_usage_mcrs), 
+with predefined converter rates around 3 GHz, and uses in addition to the RFDC 
+decimation/interpolation block also a 3/2 decimation (2/3 interpolation) block 
+implemented in FPGA fabric.
+
+\paragraph x440_too_convrate USRP X440
+The USRP X440 supports a large, finite number of master clock rates (see
+\ref x4xx_usage_mcrs), and utilizes converter rates between 1GHz and the maximum 
+supported converter rate of 4.096 GHz. The smallest possible master clock rate 
+is thus 125 Msps (1 GHz decimated by eight), and the maximum possible master 
+clock rate is 2.048 Gsps (4.096 GHz resampled by two).
+\n By default, UHD will choose the largest converter rate available. This can 
+be overridden by specifying the `converter_rate` device argument (see also 
+\ref x4xx_usage_args).
+
+After opening a UHD session the current converter rate can be read from the 
+rfdc_rate sensor. Example:
+~~~{.cpp}
+// Assumption: We are using a USRP X440, with a 1600 MHz FPGA image
+auto usrp = uhd::usrp::multi_usrp::make("type=x4xx,master_clock_rate=1000e6");
+// Verify selected master clock rate
+std::cout << usrp->get_master_clock_rate() << std::endl; // Prints 1000.00e6
+// Read 'rfdc_rate' either rx or tx sensor 
+std::cout << usrp->get_rx_sensor('rfdc_rate').to_real() << std::endl; //Prints 4000.00e6
 
-The USRP X410 only supports a small number of fixed master clock rates (see
-\ref x4xx_usage_mcrs), with a predefined converter rate.
+~~~
 
-Note that the maximum supported converter rate is 4.096 GHz. The minimum supported
-converter rate is 1 GHz. Without further DSP, the smallest possible master clock rate is
-thus 125 Msps (1 GHz resampled by eight), which is only supported on the X440.
+Note: The selected FPGA bitfile may further limit the maximum supported 
+      master clock. 
 
 \subsection x4xx_too_clocking Clocking
 
@@ -1354,11 +1451,11 @@ is the assumption if the clock source is set to 'nsync'. The eCPRI PLL can also
 driven from the RFSoC ("fabric clock") for testing purposes.
 
 The master clock rate (MCR) depends on the sample clock rate. It also depends on
-the RFDC settings, which are different for different flavours of FPGA images (see
+the RFDC settings, which are different for different flavors of FPGA images (see
 also \ref x4xx_updating_fpga_types). The actual clock running at this frequency
 is derived from the PRC within the RFSoC, using an MMCM. The MMCM provides
 various clocks that enable resampling in the RFSoC and streaming data into RFNoC
-at a rate dependant on the master clock rate and the number of samples per cycle
+at a rate dependent on the master clock rate and the number of samples per cycle
 that the RFdc will produce.
 
 The ADCs/DACs themselves make use of the sample reference clock, but may additionally use
@@ -1484,11 +1581,10 @@ a loopback connection between TX and RX.
   and LO settings on RX and TX.
 
 To loop in a CW tone for calibration, MPM offers the `set_dac_mux_data`
-which takes two signed 16 bit values for I and Q of the tone. Using
-`set_dac_mux_enable` with the daughterboard and channel number and the 1
-for enabled the tone becomes the signal that is sent out by TX of the
-corresponding channel on the daughterboard.
-Use 0 for the enable to switch back to the signal generated
+function which takes two signed 16 bit values for I and Q of the tone. Using
+`set_dac_mux_enable` with parameters for daughterboard, channel number and 
+a value of 1 to enable transmitting this tone at the corresponding channel 
+on the daughterboard. Use a value of 0 to return back to the signal generated
 by UHD. The DAC mux does not affect the ATR state of the device.
 From an UHD perspective it looks like no data is transmitted in TX or
 RX direction during calibration.
@@ -1497,7 +1593,7 @@ For different daughterboards, different frequencies and gain values are
 used at which the ADC self-calibration is run.
 
 To cover corner-cases especially in X440, the ADC self calibration can
-be parameterized with the following parameters:
+be parameterized with the following parameters (ref x4xx_usage_args):
 - `cal_freq`: The frequency of the cal tone. Must be within the first Nyquist 
   zone (converter rate / 2)
 - `cal_dac_mux_i`: 16 bit I value for the cal tone
@@ -1509,7 +1605,7 @@ be parameterized with the following parameters:
 - `cal_ch_list`: List of channels to calibrate
 - `skip_adc_selfcal`: Skip the entire self-cal (may result in bad RF performance)
 
-It is not recommended to run without any self-cal. Therefore, if `skip_adc_selfcal`
+It is not recommended to skip self-cal altogether. Therefore, if `skip_adc_selfcal`
 is used, a self-cal should be run manually before doing any kind of RF reception.
 If not all channels are used in an application, using the `cal_ch_list` may save
 some time in case the self-cal needs to run.