From 2a575bf9b5a4942f60e979161764b9e942699e1e Mon Sep 17 00:00:00 2001 From: Lars Amsel Date: Fri, 4 Jun 2021 08:27:50 +0200 Subject: uhd: Add support for the USRP X410 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Lars Amsel Co-authored-by: Michael Auchter Co-authored-by: Martin Braun Co-authored-by: Paul Butler Co-authored-by: Cristina Fuentes Co-authored-by: Humberto Jimenez Co-authored-by: Virendra Kakade Co-authored-by: Lane Kolbly Co-authored-by: Max Köhler Co-authored-by: Andrew Lynch Co-authored-by: Grant Meyerhoff Co-authored-by: Ciro Nishiguchi Co-authored-by: Thomas Vogel --- host/docs/dboards.dox | 13 + host/docs/devices.dox | 2 + host/docs/res/ZBX_simplified_blockdiagram.svg | 14492 ++++++++++++++++++++++++ host/docs/res/x410.png | Bin 0 -> 905376 bytes host/docs/res/x410_back_panel.png | Bin 0 -> 735111 bytes host/docs/res/x410_front_panel.png | Bin 0 -> 437613 bytes host/docs/res/x4xx_block_diagram.svg | 962 ++ host/docs/res/x4xx_rearpanel_status_leds.png | Bin 0 -> 28704 bytes host/docs/usrp_x4xx.dox | 953 ++ host/docs/zbx.dox | 469 + 10 files changed, 16891 insertions(+) create mode 100644 host/docs/res/ZBX_simplified_blockdiagram.svg create mode 100644 host/docs/res/x410.png create mode 100644 host/docs/res/x410_back_panel.png create mode 100644 host/docs/res/x410_front_panel.png create mode 100644 host/docs/res/x4xx_block_diagram.svg create mode 100644 host/docs/res/x4xx_rearpanel_status_leds.png create mode 100644 host/docs/usrp_x4xx.dox create mode 100644 host/docs/zbx.dox (limited to 'host/docs') diff --git a/host/docs/dboards.dox b/host/docs/dboards.dox index 7dc398f46..8898cfd37 100644 --- a/host/docs/dboards.dox +++ b/host/docs/dboards.dox @@ -467,6 +467,19 @@ Please refer to \ref e31x_dboards. Please refer to \ref n3xx_mg. +\subsection dboards_zbx ZBX XCVR board + +Features: +- Dual channel transceivers +- TX/RX and RX2 antenna ports per channel +- Frequency Range: 1 MHz to 8 GHz +- Relative Gain Range: 0 - 60 dB (RX gain range reduced below 500 MHz) + +The ZBX daughterboard only works with the X410 motherboard. + +More information: +\li \subpage page_zbx + \subsection dboards_clock_rate Daughterboard reference clock The USRP motherboard provides a reference clock to the daughterboards, which diff --git a/host/docs/devices.dox b/host/docs/devices.dox index dbe860382..c7609400d 100644 --- a/host/docs/devices.dox +++ b/host/docs/devices.dox @@ -32,6 +32,7 @@ ## USRP X-Series Devices \li \subpage page_usrp_x3x0 +\li \subpage page_usrp_x4xx ## USRP Legacy Series @@ -49,6 +50,7 @@ unless stated otherwise, they will still work with this version of UHD. \li \subpage page_dboards \li \subpage page_twinrx +\li \subpage page_zbx ## OctoClock diff --git a/host/docs/res/ZBX_simplified_blockdiagram.svg b/host/docs/res/ZBX_simplified_blockdiagram.svg new file mode 100644 index 000000000..53fa51649 --- /dev/null +++ b/host/docs/res/ZBX_simplified_blockdiagram.svg @@ -0,0 +1,14492 @@ + + + +image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + RFSoCDAC + +X410 Mother Board + +RFSoCADC + +IF + +RF + +LO + +DSA 1 + +IF + +RF + +LO + +Tx/Rx1 MHz 8 GHz + +Cal Loopback Path + +NC + +RF 4 + +IF1 1 + +IF1 2 + +IF1 3 + +IF1 4 + +IF1 5 + +RF 1 + +RF 2 + +RF 3 + +Rx2 Input1 MHz 8 GHz + +DSA 1 + +IF + +RF + +LO + +RF 3 + +RF 1 + +RF 2 + +IF2 1 + +IF2 2 + +IF2 1 + +IF2 2 + +IF1 1 + +IF1 2 + +IF + +RF + +LO + + + Sheet.2201 + + + + DSA 2 + +DSA 2 HB + +DSA 3b + +DSA 3a + +IF1 6 + +Sw 1 + +Sw 2 + +Sw 3 + +Sw 4 + +Sw 5 + +Sw 6 + +Sw 7 + +Sw 8 + +Sw 9 + +Sw 10 + +Sw 11 + +Sw 1 + +Sw 2 + +Sw 3 + +Sw 5 + +Sw 6 + +Sw 7 + +Sw 8 + +Sw 4 + +2nd Mixer + +1st Mixer + +2nd Mixer + +1st Mixer + +6.3V Bias + +600 MHz -8 GHz + +1 - 600 MHz + +Sw 11 + +NC + +NC + +NC + +NC + +1 MHz –3.0 GHz + +PLL + +LMX2572 + +RefIn + +Tx LO2 + +Rx LO2 + +DSA 2 LB + +Ganged + + + Sheet.2816 + + + + RF 3 + +IF1 3 + +IF1 4 + +Pwr Limiter + + +Sheet.2253ResistorSheet.2255Sheet.2256Sheet.2257Sheet.2258Sheet.2259IF2: 860-2250 MHz + +IF1: 2.8 - 8.2 GHz + +RF: 1 MHz - 8 GHz + +1060 MHz + +2050 MHz + +3.0 - 4.3 GHz + +4.3 - 5.1 GHz + +5.1 - 5.7 GHz + +5.7 - 6.4 GHz + +6.4 - 7.0 GHz + +7.0 - 8.0 GHz + +Tx LO1 + +PLL + +LMX2572 + +RefIn + +3.0 - 8 GHz + +1 MHz - 1.8 GHz + +1.8 - 2.3 GHz + +2.3 - 3 GHz + +3.2 - 8 GHz + +1060 MHz + +2050 MHz + +PLL + +LMX2572 + +RefIn + +Rx LO1 + +PLL + +LMX2572 + +RefIn + +IF2: 860-2250 MHz + +3.0 - 4.2 GHz + +4.2 - 5.6 GHz + +5.6 - 6.8 GHz + +6.8 - 8 GHz + +3.0 - 8 GHz + +3.2 - 8 GHz + +1 MHz - 1.8 GHz + +1.8 - 2.3 GHz + +2.3 - 3 GHz + +IF1: 2.8-8.2 MHz + +RF: 1 MHz - 8 GHz + + \ No newline at end of file diff --git a/host/docs/res/x410.png b/host/docs/res/x410.png new file mode 100644 index 000000000..215527d22 Binary files /dev/null and b/host/docs/res/x410.png differ diff --git a/host/docs/res/x410_back_panel.png b/host/docs/res/x410_back_panel.png new file mode 100644 index 000000000..782305c04 Binary files /dev/null and b/host/docs/res/x410_back_panel.png differ diff --git a/host/docs/res/x410_front_panel.png b/host/docs/res/x410_front_panel.png new file mode 100644 index 000000000..9df5ce9b4 Binary files /dev/null and b/host/docs/res/x410_front_panel.png differ diff --git a/host/docs/res/x4xx_block_diagram.svg b/host/docs/res/x4xx_block_diagram.svg new file mode 100644 index 000000000..760b2f442 --- /dev/null +++ b/host/docs/res/x4xx_block_diagram.svg @@ -0,0 +1,962 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + Xilinx RFSoC- Embedded Linux- Programmable Logic + + + ControlCPLD + + DB0 DigitalInterface + DB1 DigitalInterface + + + + DB1 RFInterface + DB0 RFInterface + ADCsDACs + + + + + DIOBoard + + + + + ClockingBoard + + + SCU + + + + + + + + + + + + DDR Bank 1 + + + + DDR Bank 0 + + DDR44 GB + + + DDR44 GB + + + + + DDR44 GB + + + + + DDR Bank 2 + + + + + + + SPI + + + + + SPI + + + + + + + + QSFP28Port 0 + QSFP28Port 1 + + + + Clock / TimeReference + 4x 25 Gbps + 4x 25 Gbps + + + RJ45 + + + I2C + + + + PL DRAM + PS DRAM + + diff --git a/host/docs/res/x4xx_rearpanel_status_leds.png b/host/docs/res/x4xx_rearpanel_status_leds.png new file mode 100644 index 000000000..e89563b3f Binary files /dev/null and b/host/docs/res/x4xx_rearpanel_status_leds.png differ diff --git a/host/docs/usrp_x4xx.dox b/host/docs/usrp_x4xx.dox new file mode 100644 index 000000000..f809e191e --- /dev/null +++ b/host/docs/usrp_x4xx.dox @@ -0,0 +1,953 @@ +/*! \page page_usrp_x4xx USRP X4x0 Series + +\tableofcontents + +\section x4xx_feature_list Comparative features list + +- Hardware Capabilities: + - Dual QSFP Ports (can be used with 10 GigE) + - External PPS input & output + - External 10 MHz input & output (other input reference frequencies also supported) + - Internal GPSDO for timing, location, and time/frequency reference + - External GPIO Connector (2xHDMI) + - USB-C debug port, providing JTAG and console access + - USB-C OTG port + - Xilinx RFSoC (XCZU28DR), includes quad-core ARM Cortex-A53 (1200 MHz), + dual-core ARM Cortex-R5F real-time unit, and UltraScale+ FPGA + - 4 GiB DDR4 RAM for Processing System, 2x4 GiB DDR4 RAM for fixed logic + - Up to 4x400 MHz of analog bandwidth, center frequency 1 MHz - 7.2 GHz using \ref page_zbx + - Configurable front-to-back or back-to-front airflow +- Software Capabilities: + - Full Linux system running on the ARM core + - Runs MPM (see also \ref page_mpm) +- FPGA Capabilities: + - Timed commands/sampling in FPGA + - RFNoC capable: Supports various CHDR bus widths from 64-bits (for minimal + footprint) up to 512 bits (for maximum throughput) +- Rack-mountable with additional rack mount kit (2 USRPs side-by-side, or 1 USRP per 1U) +- Stackable (with stack mount kit) +- Front-to-back or back-to-front airflow (switchable) + +\section x4xx_overview Overview and Features + +\image html x410.png "Ettus USRP X410" width=50% + +The Ettus USRP X410 is a fourth-generation Software Defined Radio (SDR) out of the USRP +family of SDRs. It contains two \ref page_zbx "ZBX Daughterboards" for a +total of 4 channels at up to 400 MHz of analog bandwidth each. The analog +features of the \ref page_zbx are described in a separate manual page. + +The USRP X410 features a Xilinx RFSoC, running an embedded Linux system. Like +other USRPs, it is addressable through a 1 GbE RJ45 connector, which allows full +access to the embedded Linux system, as well as data streaming at low rates. In +addition, it features two QSFP28 connectors, which allow for up to 4x10 GbE or +1x100 GbE connections each. + +The front panel provides access to the RF connectors (SMA), Tx/Rx status LEDs, +programmable GPIOs, and the power button. The rear panel is where the power and +data connections go (Ethernet, USB) as well as time/clock reference signals and +GPS antenna. + +X410's cooling system uses a field replaceable fan assembly and supports two +variants: one that pulls air front-to-back and one that pulls air back-to-front. +By default, the unit comes with the front-to-back fan assembly. + +\subsection x4xx_overview_rfsoc The RFSoC CPU/FPGA and host operating system + +The main chip (the SoC) of the X410 is a Xilinx RFSoC XCZU28DR. It contains an +ARM quad-core Cortex A53 CPU (referred to as the "APU"), an UltraScale+ FPGA +including peripherals such as built-in data converters and an SD-FEC core, and +an ARM Cortex-R5F real-time processor (the "RPU"). + +The programmable logic (PL, or FPGA) section of the SoC is responsible for +handling all sampling data, the high-speed network connections, and any other +high-speed utilities such as custom RFNoC logic. The processing system (PS, or CPU) +is running a custom-built OpenEmbedded-based Linux operating system. The OS is +responsible for all the device and peripheral management, such as running MPM, +configuring the network interfaces, running local UHD sessions, etc. + +The programmable logic bitfile contains certain hard-coded configurations of the +hardware, such as what type of connectivity the QSFP ports use, and how the RF +data converters are configured. That means to change the QSFP from a 10 GbE to a +100 GbE connection requires changing out the bitfile, as well as when +reconfiguring the data converters for different master clock rates. See +\ref x4xx_updating_fpga_types for more information. + +It is possible to connect to the host OS either via SSH or serial console (see +sections \ref x4xx_getting_started_ssh and \ref x4xx_getting_started_serial, +respectively). + +The X410 has a higher maximum analog bandwidth than previous USRPs. It can provide +rates up to 500 Msps, resulting in a usable analog bandwidth of up to 400 MHz. +In order to facilitate the higher bandwidth, UHD +uses a technology called \ref page_dpdk "Data Plane Development Kit (DPDK)". +See the DPDK page for details on how it can improve streaming, and how to use +it. + +\subsection x4xx_overview_dboards Daughterboard Connectivity + +The USRP X410 contains two ZBX daughterboards. They come pre-assembled. +To find out more about the capabilities of these analog front-end cards, see +\ref page_zbx. + +\subsection x4xx_overview_panels Front and Back Panels + +\image html x410_front_panel.png "X410 Front Panel" width=90% + +The X410 front panel provides access to the RF ports of the \ref page_zbx. +It also provides access to the front-panel GPIO connectors (2x HDMI) and the +power button. + +\image html x410_back_panel.png "X410 Back Panel" width=90% + +The back panel provides access to power, data connections, clocking and timing +related connections, and some status LEDs: + +- The QSFP28 connectors have different configurations dependent on the FPGA + image type (see also \ref x4xx_updating_fpga_types) +- The zHD/iPass connectors are unsupported +- GPS ANT, REF IN, and PPS IN allow connecting a GPS antenna, a reference clock + (e.g., 10 MHz) and a 1 PPS signal for timing purposes +- The TRIG IN/OUT port is not supported in default FPGA images +- The serial number is embedded in a QR code +- There are four user-configurable status LEDs (see also \ref x4xx_usage_rearpanelleds) +- The CONSOLE JTAG USB-C port is a debug port that allows serial access to the + SCU or the OS (see also \ref x4xx_getting_started_serial) +- The USB to PS USB-C port is accessible by the operating system, e.g., to + connect mass storage devices. It can also be used to expose the eMMC storage + as a mass storage device to an external computer, e.g., for updating the + filesystem +- The RJ45 Ethernet port allows accessing the operation system, e.g., via SSH. + It is also possible to stream data over this interface, albeit at a slow rate + (approx. 10 Msps). + +\subsection x4xx_overview_micro The STM32 microcontroller + +The STM32 microcontroller (also referred to as the "SCU") controls various +low-level features of the X4X0 series motherboard: It controls the power +sequencing, reads out fan speeds and some of the temperature sensors. +It is connected to the RFSoC via an I2C bus. It is running software based on +Chromium EC. + +It is possible to log into the STM32 using the serial interface +(see \ref x4xx_getting_started_serial_micro). This will allow certain low-level +controls, such as remote power cycling should the CPU have become unresponsive +for whatever reason. + +\subsection x4xx_overview_rackmount Rack Mounting and Cooling + +TODO fill out +- explain how to flip the fan direction +- maybe explain how to rack-mount + +\subsection x4xx_overview_storage eMMC Storage + +The main non-volatile storage of the USRP is a 16 GB eMMC storage. This storage +can be made accessible as a USB Mass Storage device through the USB-OTG connector +on the back panel. + +The entire root file system (Linux kernel, libraries) and any user data are +stored on the eMMC. It is partitioned into four partitions: + +1. Boot partition (contains the bootloader). This partition usually does not + require modification. +2. A data partition, mounted in /data. This is the only partition that is not + erased during file system updates. +3. Two identical system partitions (root file systems). These contain the + operating system and the home directory (anything mounted under / that is not + the data or boot partition). The reason there are two of these is to enable + remote updates: An update running on one partition can update the other one + without any effect to the currently running system. Note that the system + partitions are erased during updates and are thus unsuitable for permanently + storing information. + +Note: It is possible to access the currently inactive root file system by +mounting it. After logging into the device using serial console or SSH (see the +following two sections), run the following commands: + + $ mkdir temp + $ mount /dev/mmcblk0p3 temp # This assumes mmcblk0p3 is currently not mounted + $ ls temp # You are now accessing the idle partition: + bin data etc lib media proc sbin tmp usr + boot dev home lost+found mnt run sys uboot var + +The device node in the mount command might differ, depending on which partition +is currently already mounted. + +\section x4xx_getting_started Getting started + +Firstly, download and install UHD on a host computer following \ref page_install +or \ref page_build_guide. The USRP X410 requires UHD version 4.1 or above. + +\subsection x4xx_getting_started_assembling Assembling the X410 + +Inside the kit you will find the X410 and an X410 power supply. Plug these in, +connect the 1GbE RJ45 interface to your network, and power on the device by +pressing the power button. + +\subsection x4xx_network_connectivity Network Connectivity + +Once the X410 has booted, determine the IP address and verify network +connectivity by running `uhd_find_devices` on the host computer: + + $ uhd_find_devices + -------------------------------------------------- + -- UHD Device 0 + -------------------------------------------------- + Device Address: + serial: 1234ABC + addr: 10.2.161.10 + claimed: False + mgmt_addr: 10.2.161.10 + product: x410 + type: x4xx + +By default, an X410 will use DHCP to attempt to find an address. + +At this point, you should run: + + uhd_usrp_probe --args addr= + +to ensure functionality of the device. + +Note: If you receive the following error: + + Error: RuntimeError: Graph edge list is empty for rx channel 0 + +then you will need to download a UHD-compatible FPGA as described in +\ref x4xx_updating_fpga or using the following command (it assumes that FPGA +images have been downloaded previously using uhd_images_downloader, or that the +command is run on the device itself): + + uhd_image_loader --args type=x4xx,addr=,fpga=X4_200 + +When running on the device, use 127.0.0.1 as the IP address. + +You can now use existing UHD examples or applications (such as +rx_sample_to_file, rx_ascii_art_dft, or tx_waveforms) or other UHD-compatible +applications to start receiving and transmitting with the device. + +\subsection x4xx_getting_started_security Security-related settings + +The X410 ships without a root password set. It is possible to ssh into the +device by simply connecting as root, and thus gaining access to all subsystems. +To set a password, run the command + + $ passwd + +on the device. + +\subsection x4xx_getting_started_serial Serial connection + +It is possible to gain access to the device using a serial terminal +emulator. To do so, the USB debug port needs to be connected to a separate +computer to gain access. +Most Linux, OSX, or other Unix flavours have a tool called 'screen' +which can be used for this purpose, by running the following command: + + $ sudo screen /dev/ttyUSB2 115200 + +In this command, we prepend 'sudo' to elevate user privileges (by default, +accessing serial ports is not available to regular users), we specify the +device node (in this case, `/dev/ttyUSB2`), and the baud rate (115200). + +The exact device node depends on your operating system's driver and other USB +devices that might be already connected. Modern Linux systems offer alternatives +to simply trying device nodes; instead, the OS might have a directory of +symlinks under `/dev/serial/by-id`: + + $ ls /dev/serial/by-id + usb-Digilent_Digilent_USB_Device_2516351DDCC0-if02-port0 + usb-Digilent_Digilent_USB_Device_2516351DDCC0-if03-port0 + +Note: Exact names depend on the host operating system version and may differ. + +The first (with the `if02` suffix) connects to the STM32 microcontroller (SCU), whereas +the second (with the `if03` suffix) connects to Linux running on the RFSoC APU. + + $ sudo screen /dev/serial/by-id/usb-Digilent_Digilent_USB_Device_2516351DDCC0-if03-port0 115200 + +After entering the username `root` (no password is set by default), you should be presented with a shell prompt similar to the following: + + root@ni-x4xx-1234ABC:~# + +On this prompt, you can enter any Linux command available. Using the default +configuration, the serial console will also show all kernel log messages (unlike +when using SSH, for example), and give access to the boot loader (U-boot +prompt). This can be used to debug kernel or bootloader issues more efficiently +than when logged in via SSH. + +\subsubsection x4xx_getting_started_serial_micro Connecting to the microcontroller + +The microcontroller (which controls the power sequencing, among other things) +also has a serial console available. To connect to the microcontroller, use the +other UART device. In the example above: + + $ sudo screen /dev/serial/by-id/usb-Digilent_Digilent_USB_Device_2516351DDCC0-if02-port0 115200 + +It provides a very simple prompt. The command 'help' will list all available +commands. A direct connection to the microcontroller can be used to hard-reset +the device without physically accessing it (i.e., emulating a power button press) +and other low-level diagnostics. For example, running the command `reboot` will +reset the state of the device, and the command `powerbtn` will emulate a button +press, turning the device back on again. + +\subsection x4xx_getting_started_ssh SSH connection + +The USRP X4xx-Series devices have two network connections: The dual QSFP28 +ports, and an RJ-45 connector. The latter is by default configured by DHCP; by +plugging it into into 1 Gigabit switch on a DHCP-capable network, it will get +assigned an IP address and thus be accessible via ssh. + +In case your network setup does not include a DHCP server, refer to the section +\ref x4xx_getting_started_serial. A serial login can be used to assign an IP address manually. + +After the device obtained an IP address you can log in from a Linux or OSX +machine by typing: + + $ ssh root@ni-x4xx-1234ABC # Replace with your actual device name! + +Depending on your network setup, using a `.local` domain may work: + + $ ssh root@ni-x4xx-1234ABC.local + +Of course, you can also connect to the IP address directly if you know it (or +set it manually using the serial console). + +Note: The device's hostname is derived from its serial number by default +(`ni-x4xx-$SERIAL`). You can change the hostname by modifying the `/etc/hostname` +file and rebooting. + +On Microsoft Windows, the connection can be established using a tool such as +PuTTY, by selecting a username of root without password. + +Like with the serial console, you should be presented with a prompt like the +following: + + root@ni-x4xx-1234ABC:~# + +\subsection x4xx_updating_fpga Updating the FPGA + +The FPGA can be updated simply using `uhd_image_loader`: + + uhd_image_loader --args type=x4xx,addr= --fpga-path + +or + + uhd_image_loader --args type=x4xx,addr=,fpga=FPGA_TYPE + +A UHD install will likely have pre-built images in `/usr/share/uhd/images/`. +Up-to-date images can be downloaded using the `uhd_images_downloader` script: + + uhd_images_downloader + +will download images into `/usr/share/uhd/images/` (the path may differ, +depending on how UHD was installed). + +Also note that the USRP already ships with compatible FPGA images on the device - +these images can be loaded by SSH'ing into the device and running: + + uhd_image_loader --args type=x4xx,mgmt_addr=127.0.0.1,fpga=X4_200 + +\subsubsection x4xx_updating_fpga_types FPGA Image Flavors + +Unlike the USRP X310 or other third-generation USRP devices, the FPGA image +flavors do not only encode how the QSFP28 connectors are configured, but also +which master clock rates are available. This is because the data converter +configuration is part of the FPGA image (the ADCs/DACs on the X410 are on the +same die as the FPGA). +The image flavors consist of two short strings, separated by an underscore, e.g. +`X4_200` is an image flavor which contains 4x10GbE, and can handle an analog +bandwidth of 200 MHz. The first two characters describe the configuration of +the QSFP ports: 'X' stands for 10 GbE, 'C' stands for 100 GbE. See the following +table for more details. + +|  FPGA Image Flavor  | QSFP28 Port 0 Interface | QSFP28 Port 1 Interface | +|---------------------|-------------------------|-------------------------| +| X1_100 | 1x 10GbE (Lane 0) | N/C | +| X4_{100, 200} | 4x 10 GbE | N/C | +| XG_{100, 200} | 1x 10GbE (Lane 0) | 1x 10GbE (Lane 0) | +| X4_{100, 200} | 4x 10GbE (All Lanes) | N/C | +| X4C_{100, 200} | 4x 10GbE (All Lanes) | 100GbE | +| C1_400 | 100GbE | N/C | +| CG_{100, 400} | 100GbE | 100GbE | + +The analog bandwidth determines the available master clock rates. As of UHD 4.1, +only the X4_200 image is shipped with UHD, which allows a a 245.76 MHz or +250 MHz master clock rate. The other images are considered experimental (unsupported). + +\section x4xx_updating_filesystems Updating Filesystems + +Mender is a third-party software that enables remote updating of the root file +system without physically accessing the device (see also the [Mender +website](https://mender.io)). Mender can be executed locally on the device, or a +Mender server can be set up which can be used to remotely update an arbitrary +number of USRP devices. Mender servers can be self-hosted, or hosted by Mender +(see [mender.io](https://mender.io) for pricing and availability). + +When updating the file system using Mender, the tool will overwrite the root +file system partition that is not currently mounted (note: the onboard flash +storage contains two separate root file system partitions, only one is ever used +at a single time). Any data stored on that partition will be permanently lost, +including the currently loaded FPGA image. After updating that partition, it +will reboot into the newly updated partition. Only if the update is confirmed by +the user, the update will be made permanent. This means that if an update fails, +the device will be always able to reboot into the partition from which the +update was originally launched (which presumably is in a working state). Another +update can be launched now to correct the previous, failed update, until it +works. + +To initiate an update from the device itself, download a Mender artifact +containing the update itself. These are files with a `.mender` suffix. They can +be downloaded by using the uhd_images_downloader utility: + + $ uhd_images_downloader -t mender -t x4xx + +Append the `-l` switch to print out the URLs only: + + $ uhd_images_downloader -t mender -t x4xx -l + +Then run mender on the command line: + + $ mender install /path/to/latest.mender + +The artifact can also be stored on a remote server: + + $ mender install http://server.name/path/to/latest.mender + +This procedure will take a while. If the new filesystem requires an update to +the MB CPLD, see \ref x4xx_updating_cpld before proceeding. After mender has +logged a successful update, reboot the device: + + $ reboot + +If the reboot worked, and the device seems functional, commit the changes so +the boot loader knows to permanently boot into this partition: + + $ mender commit + +To identify the currently installed Mender artifact from the command line, the +following file can be queried: + + $ cat /etc/mender/artifact_info + +If you are running a hosted server, the updates can be initiated from a web +dashboard. From there, you can start the updates without having to log into the +device, and can update groups of USRPs with a few clicks in a web GUI. The +dashboard can also be used to inspect the state of USRPs. This is a simple way +to update groups of rack-mounted USRPs with custom file systems. + + +\subsection x4xx_resetting_boot_environment Resetting Boot Environment + +In the event that the new system has problems booting, you can attempt to reset +the boot environment using the following instructions. + +First, connect to the USB serial console at a baud rate of 115200. Boot the +device, and stop the boot sequence by typing `noautoboot` at the prompt. Then, +run the following commands in the U-boot command prompt: + + env default -a + env save + reset + +The last command will reboot the USRP. If the `/` filesystem was mounted to `mmcblk0p2` as +described in \ref x4xx_updating_filesystems, then stop the boot again and run: + + run altbootcmd + +Otherwise, let the boot continue as normal. + +\subsection x4xx_updating_cpld Updating MB CPLD + +Caution! Updating the MB CPLD has the potential to brick your device if done +improperly. + +You can update the MB CPLD by running the following command on the X410: + + python3 /usr/lib/python3.7/site-packages/usrp_mpm/periph_manager/x4xx_update_cpld.py --file= + +Filesystems will usually contain a compatible `cpld-x410.rpd` file at +`/lib/firmware/ni/cpld-x410.rpd`. If you're installing a new filesystem via +mender, you may have to mount the new filesystem (before you boot into it) in +order to access the new firmware: + + mkdir /mnt/other + mount /dev/mmcblk0p3 /mnt/other + cp /mnt/other/lib/firmware/ni/cpld-x410.rpd ~ + umount /mnt/other + +Note that the other filesystem may be either `/dev/mmcblk0p2` or `/dev/mmcblk0p3`. + +If the `x4xx_update_cpld.py` script returns an error, diagnose the error before +proceeding. + +After updating the MB CPLD, a power cycle is required for the changes to take +effect. Shut down the device using: + + shutdown -h now + +and then un-plug, wait several seconds, then re-plug the power to the USRP. + +Alternatively, in lieu of physical access, the microcontroller can be accessed +using the USB serial port as described in \ref x4xx_getting_started_serial, and +can be used to reboot the device: + + reboot + powerbtn + + +\subsection x4xx_updating_scu Updating the SCU + +The writable SCU image file is stored on the filesystem under +`/lib/firmware/ni/ec-titanium-revX.RW.bin` (where X is a revision compatibility +number). To update, simply replace the `.bin` file with the updated version and +reboot. + +\subsection x4xx_accessing_emmc_usb USB access to eMMC + +While Mender should be used for routine filesystem updates (see \ref +x4xx_updating_filesystems), it is also possible to access the X410's internal +eMMC from an external host over USB. This allows accessing or modifying the +filesystem, as well as the ability to flash the device with an entirely new +filesystem. + +In order to do so, you'll need an external computer with two USB ports, and two +USB cables to connect the computer to your X410. The instructions below assume +a Linux host. + +First, connect to the APU serial console at a baud rate of 115200. Boot the +device, and stop the boot sequence by typing `noautoboot` at the prompt. Then, +run the following command in the U-boot command prompt: + + ums 0 mmc 0 + +This will start the USB mass storage gadget to expose the eMMC as a USB mass +storage device. You should see a spinning indicator on the console, which +indicates the gadget is active. + +Next, connect your external computer to the X410's USB to PS port using an OTG +cable. Your computer should recognize the X410 as a mass storage device, and you +should see an entry in your kernel logs (`dmesg`) that looks like this: + + usb 3-1: New USB device found, idVendor=3923, idProduct=7a7d, bcdDevice= 2.23 + usb 3-1: New USB device strings: Mfr=1, Product=2, SerialNumber=0 + usb 3-1: Product: USB download gadget + usb 3-1: Manufacturer: National Instruments + sd 6:0:0:0: [sdc] 30932992 512-byte logical blocks: (15.8 GB/14.8 GiB) + sdc: sdc1 sdc2 sdc3 sdc4 + sd 6:0:0:0: [sdc] Attached SCSI removable disk + +The exact output will depend on your machine, but from this log you can see that +the X410 was recognized and `/dev/sdc` is the block device representing the +eMMC, with 4 partitions detected (see \ref x4xx_overview_storage for details on +the partition layout). + +It is now possible to treat the X410's eMMC as you would any other USB drive: +the individual partitions can be mounted and accessed, or the entire block +device can be read/written. + +Once you're finished accessing the device over USB, the u-boot gadget may be +stopped by hitting Ctrl-C at the APU serial console. + +\subsubsection x4xx_flash_emmc Flashing eMMC + +Once the X410's eMMC is accessible over USB, it's possible to write the +filesystem image using `bmaptool`. You can obtain the latest filesystem image by +running: + + uhd_images_downloader -t sdimg -t x4xx + +The output of this command will indicate where the downloaded image can be +found. + +Run: + + sudo bmaptool /path/to/usrp_x4xx_fs.sdimg.bz2 /dev/sdX + +to flash the eMMC with this image (replacing /dev/sdX with the block device +of the X410's eMMC as indicated by your kernel log). + +\subsection x4xx_jtag_boot Booting X410 over JTAG + +If the X410 is no longer able to boot from eMMC, it is possible to boot the +device into u-boot over JTAG. This will allow the filesystem to be reflashed +using the process described in \ref x4xx_accessing_emmc_usb. + +In order to boot the X410 over JTAG, you'll first need to have either the +Xilinx SDK, or the freely available Vivado Lab Edition. The following steps +require that one of these is installed and available in your environment. + +For convenience, pre-compiled bootloader binaries are provided, along with a +script to handle downloading these into the X410's memory and booting the +device. These are included in the sdimg package with the name +`usrp_x4xx_recovery.zip`, which can be downloaded using: + + uhd_images_downloader -t sdimg -t x4xx + +To boot the device over JTAG, first ensure the X410 is powered off, and that you +have serial consoles open to both the SCU and the APU. Configure the device to +boot over JTAG by running `zynqmp bootmode jtag` on the SCU console, and press +the power button (or run the `powerbtn` command at the SCU console). At this +point, the device is powered on and the APU is held in reset. + +Run `xsdb boot_u-boot.tcl` in the directory where you've extracted the +bootloader binaries. This will download the various binaries needed to boot the +device into memory, and bring the APU out of reset. Once this script completes, +you should see u-boot loading on the APU serial console. From here, you can +follow the steps in \ref x4xx_accessing_emmc_usb to reflash the eMMC. + +After the eMMC has been flashed, run `reboot` at the SCU console to reset the +device and return back to the default boot mode. A subsequent press of the power +button will boot the device from the eMMC. + +\section x4xx_usage Using a USRP X4x0 from UHD + +Like any other USRP, all X4x0 USRPs are controlled by the UHD software. To +integrate a USRP X4x0 into your C++ application, you would generate a UHD +device in the same way you would for any other USRP: + +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp} +auto usrp = uhd::usrp::multi_usrp::make("type=x4xx"); +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For a list of which arguments can be passed into make(), see Section +\ref x4xx_usage_args. + +\subsection x4xx_usage_args Device Arguments + + Key | Description | Example Value +-----------------------|------------------------------------------------------------------------------|--------------------- + addr | IPv4 address of primary SFP+ port to connect to. | addr=192.168.30.2 + second_addr | IPv4 address of secondary SFP+ port to connect to. | second_addr=192.168.40.2 + mgmt_addr | IPv4 address or hostname to which to connect the RPC client. Defaults to `addr'.| mgmt_addr=ni-sulfur-311FE00 + find_all | When using broadcast, find all devices, even if unreachable via CHDR. | find_all=1 + master_clock_rate | Master Clock Rate in Hz. | master_clock_rate=250e6 + serialize_init | Force serial initialization of daughterboards. | serialize_init=1 + skip_init | Skip the initialization process for the device. | skip_init=1 + time_source | Specify the time (PPS) source. | time_source=internal + clock_source | Specify the reference clock source. | clock_source=internal + ref_clk_freq | Specify the external reference clock frequency, default is 10 MHz. | ref_clk_freq=20e6 + discovery_port | Override default value for MPM discovery port. | discovery_port=49700 + rpc_port | Override default value for MPM RPC port. | rpc_port=49701 + +\subsection x4xx_usage_gps GPS + +The X410 includes a Jackson Labs LTE-Lite GPS module. Its antenna port is on the +rear panel (see \ref x4xx_overview_panels). When the X410 has access to GPS +satellite signals, it can use this module to read out the current GPS time and +location as well as to discipline an onboard OCXO. + +To use the GPS as a clock and time reference, simply use `gpsdo` as a clock or +time source. Alternatively, set `gpsdo` as a synchronisation source: + +~~~{.cpp} +// Set clock/time individually: +usrp->set_clock_source("gpsdo"); +usrp->set_time_source("gpsdo"); +// This is equivalent to the previous commands, but faster, as it sets +// both settings simultaneously and avoids duplicating settings that are shared +// between these calls. +usrp->set_sync_source("clock_source=gpsdo,time_source=gpsdo"); +~~~ + +Note the GPS module is not always enabled. Its power-on status can be queried +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. + +\subsection x4xx_usage_gpio Front-Panel Programmable GPIOs + +The USRP X410 has two HDMI front-panel connectors, which are connected to the +FPGA. + +Support for using these with UHD is not yet available. + + +\subsection x4xx_usage_subdevspec Subdev Specifications + +The RF ports on the front panel of the X410 + ZBX correspond to the following +subdev specifications: + +Label | Subdev Spec +------------|------------ +DB 0 / RF 0 | A:0 +DB 0 / RF 1 | A:1 +DB 1 / RF 0 | B:0 +DB 1 / RF 1 | B:1 + +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. + +\subsection x4xx_usage_sensors The Sensor API + +Like other USRPs, the X4x0 series have daughterboard and motherboard sensors. +For daughterboard sensors, cf. \ref zbx_sensors. + +When using uhd::usrp::multi_usrp, the following API calls are relevant to +interact with the motherboard sensor API: + +- uhd::usrp::multi_usrp::get_mboard_sensor_names() +- uhd::usrp::multi_usrp::get_mboard_sensor() + +The following motherboard sensors are always available: + +- `ref_locked`: This will check that all the daughterboards have locked to the + external reference. +- `temp_fpga`: The temperature of the RFSoC die itself. +- `temp_main_power`: The temperature of the PM-BUS devices which supply 0.85V + to the RFSoC. +- `temp_scu_internal`: The internal temperature reading of the STM32 microcontroller. +- `fan0`: Fan 0 speed (RPM) +- `fan1`: Fan 1 speed (RPM) + +The GPS sensors will return empty values if the GPS is inactive (note it may be +inactive when using a different clock than `gpsdo`, see also \ref x4xx_usage_gps). +There are two types of GPS sensors. The first set requires an active GPS module +and is acquired by calling into gpsd on the embedded device, which in turn +communicates with the GPS via a serial interface. For this reason, these sensors +can take a few seconds before returning a valid value: + +- `gps_time`: GPS time in seconds since the epoch +- `gps_tpv`: A TPV report from GPSd serialized as JSON +- `gps_sky`: A SKY report from GPSd serialized as JSON +- `gps_gpgga`: GPGGA string + +The seconds set of GPS sensors probes pins on the GPS module. They are all boolean +sensors values. If the GPS is disabled, they will always return false. + +- `gps_enabled`: Returns true if the GPS module is powered on. +- `gps_locked`: Returns the state of the 'LOCK_OK' pin. +- `gps_alarm`: Returns the state of the 'ALARM' pin. +- `gps_warmed_up`: Returns the state of the 'WARMUP_TRAINING' pin. Indicates + warmup phase, can be high for minutes after enabling GPS. +- `gps_survey`: Returns the state of the 'SURVEY_ACTIVE' pin. Indicates state of + auto survey process. Indicates that module is locked to GPS, and + that there are no events on the GPS module pending. + +\subsection x4xx_usage_rearpanelleds Rear Panel Status LEDs + +The USRP X410 is equipped with three user-configurable LEDs located on the +device's rear panel: `LED 0`, `LED 1`, and `LED 2`. +Each LED supports four different states: Off, Green, Red, and Amber. +Different behaviors are supported for each LED (see \ref x4xx_usage_rearpanelleds_suppbeh +below) which are user-configurable. Refer to \ref x4xx_usage_rearpanelleds_defaults +for default functionality. + + + +\subsubsection x4xx_usage_rearpanelleds_suppbeh Supported LED Behaviors + +- `activity`: flash green LED for CPU activity +- `emmc`: flash green LED for eMMC activity +- `heartbeat`: flash green LED with a heartbeat +- `fpga`: change LED to green when FPGA is loaded +- `netdev `: green LED indicates interface link, amber indicates activity + - Where `` is the name of any network interface (e.g. `eth0`) +- `none`: LED is constantly off +- `panic`: red LED turns on when kernel panics +- `user0`: off, green, red or amber LED state is controlled by FPGA application, User LED 0 +- `user1`: off, green, red or amber LED state is controlled by FPGA application, User LED 1 +- `user2`: off, green, red or amber LED state is controlled by FPGA application, User LED 2 + +\subsubsection x4xx_usage_rearpanelleds_defaults Behavior + +| LED Number | Default Behavior | +|------------|------------------| +| LED 0 | `heartbeat` | +| LED 1 | `fpga` | +| LED 2 | `emmc` | + +A user may change the X410 LEDs' default behavior via running a utility on the +on-board ARM processor (Linux). + +### Temporarily change the LED Behavior + +1. Establish a connection (serial or SSH) to the X410's Linux terminal. +2. Use the `ledctrl` utility to configure each LED based on desired supported behavior + + ledctrl + +Where `` valid options are: `led0`, `led1`, and `led2`. These options +correspond to the rear panel labels. +The `` valid options are listed in the \ref x4xx_usage_rearpanelleds_suppbeh +section above, with their corresponding description. + +Examples: + + root@ni-x4xx-1111111:~# ledctrl led0 user0 + +Sets the X410's LED 0 to be controlled via the FPGA application using "User LED 0". + +### Persistently change the LED + +The above method will not persist across reboots. In order to persist the +changes, modify the ledctrl service unit files which are run by the init +system at boot. These files can be found on a running filesystem at, e.g., +`/lib/systemd/system/ledctrl-led0.service`. + + +### Using FPGA LED Control + +When selecting `user0`, `user1`, and/or `user2` as LED behavior (see +\ref x4xx_usage_rearpanelleds_suppbeh above), the FPGA application gains control +of that given LED. The following paragraph describes how the FPGA application can +control the state for each setting. + +FPGA application access to User LED 0-2 requires modification of the FPGA source +code and is achieved directly via Verilog, using a 2-bit vector to control the state. + +Below is an excerpt of the FPGA source code, setting the `user0`, `user1`, and +`user2` values to green, red, and amber respectively. +~~~{.v} + // Rear panel LEDs control + // Each LED is comprised of a green (LSB) and a red (MSB) LED + // which the user can control through a 2-bit vector once fabric + // LED control is configured on the X410's Linux shell. + localparam LED_OFF = 2'b00; + localparam LED_GREEN = 2'b01; + localparam LED_RED = 2'b10; + localparam LED_AMBER = 2'b11; + + wire [1:0] user_led_ctrl [0:2]; + assign user_led_ctrl[0] = LED_GREEN; + assign user_led_ctrl[1] = LED_RED; + assign user_led_ctrl[2] = LED_AMBER; +~~~ + +\section x4xx_too Theory of Operation + +\image html x4xx_block_diagram.svg "X4x0 Motherboard Block Diagram" width=60% + +The USRP X410 has three processors on the motherboard: The RFSoC, the SCU, and a +control CPLD. The RFSoC does the bulk of the work. It houses the programmable +logic (PL), the APU and RPU processors (the former running the embedded Linux +system), connects to the data ports (RJ45, QSFP28) and also includes RF data +converters (ADC/DAC) which are exposed to the daughterboards through a connector. +The FPGA configuration for the RFSoC can be found in the source code repository +under `fpga/usrp3/top/x400`. The OpenEmbedded Linux configuration can be found +on a [separate repository](https://github.com/EttusResearch/meta-ettus). + +The SCU is a microcontroller running a baremetal control stack. It controls the +power sequencing, the fan speeds, connects various peripherals and sensors to +the Linux kernel, and performs other low-level tasks. It can be accessed through +a serial console directly from the back-panel. This can be a useful debugging +tool if the device is not responding to other inputs, and can be used to +power-cycle and reboot the USRP. It is connected to the RFSoC using an I2C +interface. + +The motherboard control CPLD performs various control tasks, such as controlling +the clocking card and the DIO connector (note that the DIO pins are also available +without using the CPLD, which is the normal case when programming the pins for +an application with higher rates and precise timing). +The motherboard CPLD is accessible from the RFSoC through a SPI interface, and +also acts as a SPI mux for accessing peripherals such as the clocking card. +Access to the motherboard CPLD from within a UHD session always goes through MPM, +meaning it is not used for high-speed or high-precision control. +Its source code can be found in the UHD source code repository under +`fpga/usrp3/top/x400/cpld`. + +The RJ45 Ethernet connector is connected directly to the PS and is made available +in Linux as a regular Ethernet interface. It is possible to stream data to and +from the FPGA, but the data is tunneled through the operating system, which +makes it a relatively slow interface. +The QSFP28 connectors are directly connected to the RFSoC transceivers. Different +FPGA images configure these either as 10 GbE or 100 GbE interfaces. It +is possible to access the PS through these interfaces (when configured as Ethernet +interfaces), but their main purpose is to stream data from and to the FPGA at +high rates. + +\subsection x4xx_too_clocking Clocking + +The clocking architecture of the motherboard is spread out between a clocking +auxiliary board, which contains an OCXO (either GPS-disciplined or controlled by +a DAC), but also connects an external reference to the motherboard. Furthermore, +it houses a PLL for deriving a clock from the network (eCPRI). + +The motherboard itself has two main PLLs for clocking purposes: The Sample PLL +(also SPLL) is used to create all clocks used for RF-related purposes. It creates +the sample clock (a very fast clock, ~3 GHz) and the PLL reference clock (PRC) +which is used as a reference for the LO synthesizers (50-64 MHz). + +Its input is called the base reference clock (BRC). It has four possible sources: +- The OCXO, which always produces a 10 MHz reference clock. When the clock source + is set to `internal`, this OCXO is only disciplined by a DAC (control of that + DAC is not exposed in this version of UHD), but there is no further control + loop. By selecting `gpsdo` as a clock source, a GPS module is used to + discipline the OCXO (see also \ref x4xx_usage_gps). +- The external reference input SMA port. When an external reference is used (by + selecting `external` as the clock source), the X410 assumes a 10 MHz reference + clock (it is possible to drive the device with a different external clock + frequency by providing the `ref_clk_freq` device argument, but this is not a + supported use case for this UHD version). Note the clocking card can also import + a PPS signal (when setting the time source to `external`) as well as export it. +- The eCPRI PLL (when using the `nsync` clock source). It will generate a 10 MHz + BRC. Note the intention is to use this for scenarios where the clock is derived + from the network port (e.g., eCPRI), but this version of UHD does not include + such a feature. +- The reference PLL, when the clock source is set to `mboard` (this is a 25 MHz + BRC). This is not a common use case, as it is not possible to synchronize the + on-board clock. This is the only clock that does not come from the auxiliary + clocking board. + +The reference PLL (RPLL) produces clocks that are consumed by the GTY banks (for +Ethernet), as well as the on-board BRC. By default, its reference is a fixed +100 MHz clock, but it can also be driven by the eCPRI PLL. + +The eCPRI PLL is typically driven by a clock derived from the GTY banks, which +is the assumption if the clock source is set to 'nsync'. The eCPRI PLL can also be +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 +also \ref x4xx_updating_fpga_types). The actual clock running at this frequency +is generated digitally, within the RFSoC, and is derived from the SPLL clock. + +Block diagram: +``` + ┌────────────────────────────────────────────────────────┐ + │ Clocking Aux Board │ + │ ┌──────┐ ┌───────┐ ┌────────┐ │ + │ │GPSDO │ │ DAC │ │External│ │ + │ └─────┬┘ └─┬─────┘ └───┬────┘ │ + │ ┌v────v┐ │ ┌──────┐ │ + │ │ OCXO │ │ │ <───────┼──┐ + │ └──┬───┘ │ ┌───┐ │ MUX <───────┼─┐│ + │ │ │ │ │ └──┬───┘ │ ││ + │ ┌────v──────────────v───v─┐ │ ┌───────v───┐ │ ││ + │ │ │ └─┤eCPRI PLL │ │ ││ + │ └┐ MUX ┌┘ │LMK05318 │ │ ││ + │ └─┐ ┌─┘ │ │ │ ││ + │ └─┬─────────────────┘ └──┬────────┘ │ ││ + │ │ │ │ ││ + └───────────┼───────────────────────────┼────────────────┘ ││ + │ │ ││ + │ ┌─────────────┐ │ ││ + ┌──v──v┐ │ │ ││ + │ MUX │ │ │ ┌───── 100 MHz ││ + └──┬───┘ │ │ │ ││ + │Base Ref. Clock │ │ │ ││ + ┌───────v───────┐ │ ┌───────v──v──┐ ││ + │ Sample PLL │ └──┤Reference PLL│ ││ + │ LMK04832 │ │LMK03328 │ ││ + └──┬─────────┬──┘ └────┬────────┘ │└─ PL/Fabric Clock + │ │ │ │ + v v v │ + Sample PLL Reference GTY Banks GTY Recovered + Clock Clock Clock +``` + +Note that this section does not cover every single clock signal present on the +X410, but mainly those clock signals relevant for the operation of the RF +components. Refer to the schematic for more details. + +*/ +// vim:ft=doxygen: diff --git a/host/docs/zbx.dox b/host/docs/zbx.dox new file mode 100644 index 000000000..76c5585f6 --- /dev/null +++ b/host/docs/zbx.dox @@ -0,0 +1,469 @@ +/*! \page page_zbx ZBX Daughterboard + +\tableofcontents + +\section zbx_overview Overview + +The ZBX daughterboard is a two-channel superheterodyne transceiver with a focus +of telecommunication applications in the frequency range below 8 GHz. It supports +analog bandwidths of up to 400 MHz. + +The ZBX daughterboard is designed for use with the Ettus USPR X410. + +Feature list: +- Frequency range (Tx and Rx): 1 MHz - 7.2 GHz (Note: Tune range extends to 8 GHz) +- Maximum analog bandwidth: 400 MHz +- Gain range: 0-60 dB. + - Note: Rx gain range is reduced to 0-38 dB for frequencies below 500 MHz. +- On-board CPLD for high flexibility +- Maximum output power: 5-20 dBm (depending on frequency) +- Maximum input power limit: +15 dBm + +\section zbx_too Theory of Operations + +The ZBX daughterboard has two transceiver chains. The following simplified block +diagram shows their structure: + +\image html ZBX_simplified_blockdiagram.svg "ZBX Block Diagram" + +It is a superheterodyne transceiver with up to two IF stages. The second IF +stage is only used for center frequencies below 3 GHz. Above that frequency, the +desired center frequency becomes the first intermediate frequency (IF1). The +second LO stage is always enabled, and moves the IF to a value between 1 and 2 +GHz. The USRP ADC/DAC (running at a sampling rate of approx. 3 GHz) will sample +the IF directly, and downconvert to or from DC digitally. + +The TX and RX paths are almost symmetric, with slight variations on the various +frequency bands. The various gain stages are spread out along the TX and RX +paths (see also \ref zbx_gain_control, note that the TX path includes selectable +amplifiers as well as DSAs). All LO synthesizers are identical (LMX2572). + +\subsection zbx_too_cpld Digital Control + +For digital controls, the ZBX includes a CPLD (its source code is part of the +UHD repository, and can be found under `fpga/usrp3/top/x400/dboards/zr/cpld/`). +The CPLD is controlled via registers. Its register space is exposed as a subset +of the Radio RFNoC block register space (starting at address 0x80000). The CPLD +is used to control all switches, DSAs, amplifiers, LEDs, LO synthesizers and +power rails. The CPLD also controls state-dependent behaviour of the ZBX (i.e., +behaviour depending on the RX/TX state). For this purpose, ATR signals from the +FPGA are routed to the CPLD. Parts of the CPLD feature set are also described in +\ref zbx_gain_control. + + +\subsection zbx_too_lo_control LO Control + +The normal operation of the ZBX daughterboard is to simply tune it to a desired +center frequency, and UHD will internally calculate frequencies for the +individual LOs as well as the NCO. UHD uses a few rules when calculating LO and +NCO frequencies: + +- To simplify the algorithms, LO frequencies are quantized to multiples + of the LO reference frequency (which itself depends on the master clock rate). +- To reduce LO spurs, the LO synthesizer outputs are filtered with an analog + bandpass filter with a minimum frequency of 3.2 GHz. +- To avoid injection locking (an effect where nearby synthesizers + influence each other), UHD is programmed to choose different frequencies for + the various synthesizers. When programming the two channels to the same + frequency, the LOs will thus intentionally run at different frequencies. The + combination of the various LOs and the NCO frequency still results in the same + center frequency. + +The state of individual LOs can be queried and configured independently. Use the +following API calls to do so: +- multi_usrp API: + - uhd::usrp::multi_usrp::get_rx_lo_freq() + - uhd::usrp::multi_usrp::get_rx_lo_freq_range() + - uhd::usrp::multi_usrp::set_rx_lo_freq() + - uhd::usrp::multi_usrp::get_tx_lo_freq() + - uhd::usrp::multi_usrp::get_tx_lo_freq_range() + - uhd::usrp::multi_usrp::set_tx_lo_freq() +- RFNoC API: + - uhd::rfnoc::radio_control::get_rx_lo_freq() + - uhd::rfnoc::radio_control::get_rx_lo_freq_range() + - uhd::rfnoc::radio_control::set_rx_lo_freq() + - uhd::rfnoc::radio_control::get_tx_lo_freq() + - uhd::rfnoc::radio_control::get_tx_lo_freq_range() + - uhd::rfnoc::radio_control::set_tx_lo_freq() + +Note that manually modifying LOs is considered advanced behaviour, and may result +in a bad state of the device. To undo manual changes, use the regular API calls +to set a center frequency. + +\section zbx_ant_ports Antenna Ports + +The ZBX has two SMA 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. + +\section zbx_phase_alignment Phase Alignment + +Like the UBX and SBX daughterboards, the ZBX allows to be phase-aligned. This is +done by setting a command time before tuning the individual channels: +~~~{.cpp} +// Assume that `usrp` is a multi_usrp object +// 1) Set a command time in the future, e.g. 500ms from now: +usrp->set_command_time(usrp->get_time_now() + .5); +// 2) Tune to a new frequency on all channels, e.g., 2 GHz: +usrp->set_rx_freq(2e9); // The ALL_CHANS argument is implied here +// 3) Wait until we're past the command time: +std::this_thread::sleep_for(500ms); +// Channel phases are now at a deterministic offset. Repeating this procedure +// will lead to the same offset. +~~~ + +\section zbx_pwr_cal Power Calibration + +The ZBX supports the UHD power API (see also \ref page_power). UHD ships with +nominal calibration data which will allow setting the reference power levels +without previously manually calibrating the device. + +\section zbx_sensors Sensors + +Every channel has three "locked" sensors for the LO stages (`lo1_locked`, +`lo2_locked`, and `nco_locked`). A "virtual" sensor called `lo_locked` confirms +that all LOs that are currently engaged are locked. The "NCO lock" sensor is a +special case: The NCO is not on the daughterboard (it is part of the +RFSoC FPGA), but to simplify the API it was placed together with the LO lock +sensors. Unlike the (analog) synthesizers on the daughterboard, the NCO "unlock" +is not used to signify a loss of reference lock, but to signal that the NCO is +still in reset. + +Additionally, the ZBX has a temperature sensors `temperature`. While the UHD +API allows addressing a sensors based on direction (RX/TX) and channel (0/1), +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 zbx_gain_control Gain Control + +The ZBX has a sophisticated gain control, capable of controlling either an +overall gain, or manually controlling its individual gain stages. Furthermore, +the onboard CPLD can store gain tables as well, which can be accessed from other +RFNoC blocks via RFNoC commands. + +The TX path has three gain-related components: Two DSAs, as well an amplifier path. +The former have an individual gain range of 31 dB. The amplifier path allows +selecting one of two amplifiers, one with a nominal gain of 14 dB for lower +frequencies, and one with a nominal gain of 21 dB for higher frequencies. Their +actual amplification values depend on the specific frequency, and may also vary +from device to device. The amplifiers can be bypassed. + +The RX path consists of four DSAs, each with a gain range of 15 dB. + +Different gain behaviours of the ZBX daughterboard are controlled by gain +profiles, which may be set independently for TX and RX. Different gain +profiles have different API behaviours as explained in the rest of this section. + +To switch between gain profiles, use the uhd::usrp::multi_usrp::set_tx_gain_profile() +or uhd::usrp::multi_usrp::set_rx_gain_profile() API calls. When using the RFNoC +API, use the uhd::rfnoc::radio_control::set_tx_gain_profile() or +uhd::rfnoc::radio_control::set_rx_gain_profile() API calls. The main difference +between these APIs is that the multi_usrp API calls allow a default channel +value, which the RFNoC API calls do not. + +As with all other devices, the following API calls set or query gain values: +- Multi USRP: + - uhd::usrp::multi_usrp::set_tx_gain() + - uhd::usrp::multi_usrp::get_tx_gain() + - uhd::usrp::multi_usrp::set_rx_gain() + - uhd::usrp::multi_usrp::get_rx_gain() +- RFNoC + - uhd::rfnoc::radio_control::set_tx_gain() + - uhd::rfnoc::radio_control::get_tx_gain() + - uhd::rfnoc::radio_control::set_rx_gain() + - uhd::rfnoc::radio_control::get_rx_gain() + +These API calls come in different flavours, with an optional 'gain name' argument. +Note the multi_usrp API calls default to setting the overall gain value, which +is not allowed in all gain profiles. All API calls have a corresponding API call +to query the allowable gain range. + +\b Note: The RX gain range is not consistent on ZBX. Below 500 MHz, the gain +range is reduced to 0-38 dB. It is recommended to use get_rx_gain_range() to +query the currently valid gain range. + +\b Note: Some gain profiles require changing on both TX and RX. For example, +changing from `default` to `table_noatr` must happen on TX and RX at the same +time. UHD will automatically change the gain profile accordingly. It is therefore +recommended to call get_rx_gain_profile() or get_tx_gain_profile() to verify the +correct gain profile when in doubt. + +\subsection zbx_gain_default Default Gain Profile + +This gain profile is active by default. It allows setting a single, scalar gain +value. UHD will internally use a gain table to linearize the overall gain (meaning +that a 1 dB gain increase will also increase the transmit or receive power by 1 dB). +However, the UHD-internal gain table is not calibrated per-device, nor does it +take into account temperature or other changes. + +In this gain mode, it is not possible to set the individual gain stages directly, +but it is possible to read them back. This may be helpful when trying to fine-tune +gain settings in software. + +~~~{.cpp} +// Assumption: 'usrp' is a multi_usrp object +usrp->set_tx_gain_profile("default"); // Only necessary if the gain profile was set to something else before +usrp->set_tx_gain(30); // Will set the gain to 30 dB on all associated daughterboards +std::cout << usrp->get_tx_gain() << std::endl; // Should print "30" +usrp->set_tx_gain(0, "DSA1"); // Will cause an exception +// Individual DSAs may still be queried. Note that even though this is an +// attenuator, the return value is a gain (higher values mean more TX power): +auto dsa1_gain = usrp->get_tx_gain("DSA1"); +~~~ + +ATR Behaviour: The gains will apply to their respective ATR state, i.e., +RX gains will be applied to both the RX and full-duplex state, and TX gains will +be applied to the TX and full-duplex state. In the idle state, gains are set to +minimum gain. + +RFNoC Commands: All DSA values are on one register for a given ATR state, +and the TX amplifier shares a register with the antenna controls. +That means that changing the DSA values +in this gain profile will cause two register writes (one for RX/TX, and one for +full-duplex). Changing the TX amplifier gain value will incur another two writes. + +\subsection zbx_gain_manual Manual Gain Profile + +When more control is desired, the manual gain profile can be applied. Here, it +is no longer possible to request an overall gain value. However, it is now +possible to set the DSA and amplifier values directly. + +~~~{.cpp} +usrp->set_tx_gain_profile("manual"); +usrp->set_tx_gain(30); // ERROR: Now, we have to specify a name +usrp->set_tx_gain(5, "DSA1"); // Set DSA1 to 5 dB gain (equals 26 dB attenuation) +// The following line will return an undefined value and print a warning, but +// will not throw. That's because calling the overall gain is a common API call +// done by many utilities, and this behaviour is considered most backward compatible. +std::cout << usrp->get_tx_gain() << std::endl; +std::cout << usrp->get_tx_gain("DSA1") << std::endl; // Should print '5' +~~~ + +\subsection zbx_gain_table CPLD-Table Gain Profile with ATR control + +In this profile, UHD exposes access to the gain table stored on the CPLD. By default, +the CPLD is initialized with the same gain table as UHD uses internally, i.e., +there is no difference in behaviour when using this profile, unless the gain +table is modified. + +Setting DSA values directly from UHD is not possible in this profile, nor is setting +an overall gain value. However, it is now possible to load an entry from the +CPLD gain table and apply it to the current DSA settings. +In this profile, the ATR behaviour for the DSAs is the same as in the 'default' +or 'manual' profiles. That means loading a DSA table entry requires two writes +to the CPLD, one for TX/RX, and one for full-duplex. + +The gain "values" are no longer interpreted as dB values, but refer to DSA table +indices. + +An important use case of this gain profile is when testing CPLD gain tables, but +not changing other aspects of the software control. Often, this is an intermediate +debugging step while developing applications that use RFNoC commands to control +the gain. + +Another use case of this profile is when running RFNoC applications, where the +gain is controlled from another RFNoC block, but the ATR behaviour is left in +its default state. + +~~~{.cpp} +usrp->set_tx_gain_profile("table"); +usrp->set_tx_gain(30); // ERROR: Now, we have to specify a name +usrp->get_radio_control().set_tx_gain(5); // This works, though. The radio_control + // object is smart enough to infer that + // this is the only action left. +// The previous line and the following have the same effect: +usrp->set_tx_gain(5, "TABLE"); +// The CPLD DSA table entry at index 5 is now loaded and applied to the TX and +// full-duplex ATR modes. In other words, the register values TX0_TABLE_DSA* +// are copied to TX0_DSA*. +// The following line will return an undefined value and print a warning, but +// will not throw. That's because calling the overall gain is a common API call +// done by many utilities, and this behaviour is considered most backward compatible. +std::cout << usrp->get_tx_gain() << std::endl; +// The following line will print the actual value of DSA1. Note, however, that +// UHD needs to read back the value from the CPLD, since it can't know what's +// stored on the CPLD. That means the following call will require a read from +// the CPLD, which is not possible if there are timed commands queued up. +std::cout << usrp->get_tx_gain("DSA1") << std::endl; // Should print whatever + // was originally stored + // in TX0_TABLE_DSA1, which + // was copied to TX0_DSA1 +~~~ + +\subsection zbx_gain_tablenoatr CPLD-Table Gain Profile without ATR control + +When running applications where the FPGA has full control over the gain, and the +ATR behaviour should also be replaced by register writes, this profile may be +used. + +The main difference to the previous profile is that when the radio switches +between RX, TX, full duplex, and idle states, there is no automatic update of +the gain values. Instead, the current gain values are selected by writing to the +`SW_RF0_DSA_CONFIG` and `SW_RF1_DSA_CONFIG` registers. Changing these registers +will select an entry from the `RX/TX DSA` tables. Unlike the gain tables, these +are not prepopulated. + +~~~{.cpp} +usrp->set_tx_gain_profile("table_noatr"); +usrp->set_tx_gain(30); // ERROR: Now, we have to specify a name +usrp->get_radio_control().set_tx_gain(5); // This works, though. The radio_control + // object is smart enough to infer that + // this is the only action left. +// The previous line and the following have the same effect (but it's a different +// effect than when using gain profile 'table'): +usrp->set_tx_gain(5, "TABLE"); +// The CPLD SW_RF0_DSA_CONFIG register is now set to 5. That means the DSA values +// stored in TX0_DSA1[5] and TX0_DSA2[5] are now being used, assuming no other +// entity is sending commands to the CPLD via RFNoC. +// Copying CPLD gain table entries into the TX0_DSA* registers is not possible +// from software in this profile. Rather, we are hands-off and let the FPGA take +// control. +// +// Let's assume that an RFNoC block has sent register writes to the radio block +// in order to load new gain table entries, and apply them. We can still read +// back the current DSA values (the ones being currently used on the RF chain) +// by reading back from the CPLD. +// This is not possible if there are timed commands queued up. +std::cout << usrp->get_tx_gain("DSA1") << std::endl; // Should print whatever + // is currently in TX0_DSA1[i], + // where i is the value of + // SW_RF0_DSA_CONFIG. +~~~ + +\section zbx_atr Auto-Transmit-Receive Registers (ATR) + +Like other USRPs, the X410 provides GPIOs to the daughterboards that communicate +the RX/TX state. The ZBX 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. A total of 4 +GPIOs between the motherboard FPGA and the daughterboard CPLD are used for this +purpose, two pins per channel. + +ZBX uses these pins to select between different RF control values +(e.g., the aforementioned TX/RX antenna switch position; this also includes the +front-panel LEDs) as well as DSA controls (e.g., when doing RX only, the TX gain +stages can be set to zero to minimize leakage). Internally, this works by +converting the ATR pins into a control word. This control word is used to index +tables that contain different values for RF control/LEDs as well as DSAs. + +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. The transmit gain is controlled by DSA values that are +stored in tables called TX0_DSA1 and TX0_DSA2, respectively. For the duration +of the transmission, the DSA values at table position TX0_DSA1[2] and TX0_DSA2[2] +will thus be used. Similarly, tables for RF path control and LEDs are used to +configure those. This mode of using the ATR pins is called the "classic ATR" mode +and is the default behaviour. + +The ZBX daughterboard provides two additional modes of utilizing those pins: +- "Software Defined": In this mode, the ATR pins are ignored. The control word + is derived from another register. In this case, changing the table index + requires another register write as opposed to the almost instantaneous tracking + of the ATR state in the other modes. +- "FPGA controlled": This is similar to the classic ATR mode, but it combines + the pins from channel 0 and 1. The downside is that channel 0 and 1 are no + longer independent, but it allows using 16 entries from the tables instead of + four as in the classic ATR mode. + +The ATR pin mode can be set independently for channel 0 and 1, and also for DSA +tables vs. RF control/LED tables. 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 ZBX. 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. + +The "software defined" mode can be enabled for the DSA tables by using the +`table_noatr` gain profile (see the previous section). + +\section zbx_updating_cpld Updating the ZBX CPLD + +If you need to update the ZBX CPLD, you can do so by running the following command +on the device: + + python3 /usr/lib/python3.?/site-packages/usrp_mpm/dboard_manager/zbx_update_cpld.py + +By default, the script will attempt to install an image from the default path to +both daughterboards. To specify which file or dboards to program, use the +following options when running the updater script: + +- `--dboards=0,1` +- `--file=` + +By default, the `cpld-zbx.rpd` file will be provided at +`/lib/firmware/ni/cpld-zbx.rpd`. Note that after downloading the ZBX CPLD, you +will need to completely shut down and power-cycle the device. + +\subsection zbx_updating_cpld_details CPLD Programming: Details + +Read this section if you want to create your own ZBX CPLD image, or require more +information on how the CPLD image is updated. + +The source code for the ZBX CPLD is provided within the UHD code repository, at +`fpga/usrp3/top/x400/dboards/zbx/cpld`. Read the Makefile for more instructions +on how to build images. + +The build process will produce two CPLD bitfiles: A `.rpd` file and a `.svf` file. +Both are required for different programming methods. There are two programming +methods: + +- Flash mode: This requires the `.rpd` file. It uses the motherboard CPLD as a + programming device. This is the default mode. +- Legacy mode: This directly calls into openocd to flash the ZBX CPLD. It requires + the `.svf` file. + +Before running the updater, ensure that MPM is installed on your device as some +resources from MPM code are used. + +You should also ensure that the power rails to the daughterboard are up and that +MPM can successfully communicate with the daughterboard when running (running +`uhd_usrp_probe` successfully is sufficient). + +MPM does not need to be running when the updater script is executed, but you +should start it once to ensure a valid FPGA image is loaded and communication to +the daughterboard is working before attempting this. + +To specify a programming mode, use the `--updater` argument. For example, to +force the legacy mode, use the following command: + + python3 /usr/lib/python3.?/site-packages/usrp_mpm/dboard_manager/zbx_update_cpld.py \ + --updater=legacy \ + --file=/lib/firmware/ni/cpld-zbx.svf + +This will program the image from the default location onto the CPLD using the +'legacy' method. + +\section zbx_flash Flash Memory and EEPROM + +Every ZBX daughterboard has 2 MB of non-volatile flash memory which can be used +to store data such as daughterboard-specific information. When +logged into the X410 Linux system, the flash memory is mounted into the +filesystem under `/mnt/db0_flash` and `/mnt/db1_flash`, respectively. The +daughterboard also uses a separate EEPROM to store revision, serial, and product +ID of the daughterboard. + +*/ +// vim:ft=doxygen: -- cgit v1.2.3