Xmas doc

.gitignore

@@ -1,6 +1,7 @@
 .idea/
 .task/
 *.bkp
+.build_running_marker
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

source/_static/xmass/xmass_rf.drawio

@@ -1,6 +1,6 @@
 <mxfile host="Electron" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/29.3.0 Chrome/140.0.7339.249 Electron/38.7.2 Safari/537.36" version="29.3.0">
   <diagram name="Page-1" id="pqkOcmyr_G9dh7Q9kfkh">
-    <mxGraphModel dx="1237" dy="1168" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="413" pageHeight="583" math="0" shadow="0">
+    <mxGraphModel dx="1648" dy="1460" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="413" pageHeight="583" math="0" shadow="0">
       <root>
         <mxCell id="0" />
         <mxCell id="1" parent="0" />

source/hardware/xmass.rst

@@ -2,16 +2,14 @@
 xMASS SDR
 =========
 
-A modular, high-performance **8×8 MIMO transceiver** designed for **4G/5G applications** and other use cases.
+A modular, high-performance 8×8 MIMO transceiver optimized for **4G/5G application**, research, beamforming, direction finding and wideband spectrum monitoring. The xMASS provides eight synchronized RX and eight synchronized TX channels with flexible clocking, calibration and host I/O for coherent multi-channel acquisition and transmission. Its modular design allows for easy maintenance and enables the construction of high-order MIMO systems using the same building blocks.
 
 .. image:: ../_static/xmass-front-lg.png
    :alt: xmass sdr
 
 Overview
 ========
 
-The xMASS SDR is a modular, high-performance **MIMO transceiver** featuring **8 RX and 8 TX channels** which can be synchronized. Its modular design allows for easy maintenance and enables the construction of high-order MIMO systems using the same building blocks.
-
 .. image:: ../_static/xmass-iso-open-lg.png
    :alt: xmass sdr
 
@@ -34,7 +32,7 @@ General Specifications
   - 20W Typical
 
 **Extended Power Supply Range**  
-  - 2.85 - 5.5 V  
+  - 2.85 - 5.5 V
 
 RF Specifications
 -----------------
@@ -49,32 +47,52 @@ RF Specifications
   - 0.1 MSps - 100 MSps  
 
 **Channel Bandwidth**  
-  - 0.5 MHz - 90 MHz  
+  - 0.5 MHz - 90 MHz
 
-Bifurcation Modes
------------------
-
-- **Full 8×8 MIMO**  
-- **2 independent 4×4 MIMO systems**  
-- **4 independent 2×2 MIMO systems**  
 
 Target Applications
 -------------------
 
-**Spectrum Monitoring**  
-  - **4× M.2 2230 Key A+E xSDR** for comprehensive frequency analysis and monitoring  
+**Spectrum Monitoring**
+  - **4× M.2 2230 Key A+E xSDR** for comprehensive frequency analysis and monitoring
 
-**Cellular Communication**  
-  - Enables next-generation **4G/5G wireless networks** with high-order **massive MIMO**  
-  - Fully compatible with **Amarisoft** and **srsRAN**  
+**Cellular Communication**
+  - Enables next-generation **4G/5G wireless networks** with high-order **massive MIMO**
+  - Fully compatible with **Amarisoft** and **srsRAN**
 
-**Directional Finding**  
-  - Determines the **direction of arrival (DoA)** of incoming radio signals, enabling **precise localization** of transmitters  
+**Directional Finding**
+  - Determines the **direction of arrival (DoA)** of incoming radio signals, enabling **precise localization** of transmitters
 
-**Beamforming**  
-  - Focuses signal transmission and reception in specific directions  
+**Beamforming**
+  - Focuses signal transmission and reception in specific directions
   - Enhances range, improves signal quality, and reduces interference in multi-user environments
 
+
+Bifurcation Modes
+-----------------
+
+The xMASS supports configurable bifurcation modes that partition the physical 8 RX / 8 TX channel array into one or more independent logical streams.
+Bifurcation determines how RF channels, FPGA resources, and host I/O are grouped and advertised to the host.
+Selecting a bifurcation mode affects aggregate throughput, per-device sample-rate limits, synchronization behaviour, calibration routing, and the available MIMO processing scope.
+
+Available bifurcation modes are:
+
+- **Full 8×8 MIMO**
+
+  - All 8 RX and 8 TX channels are presented as a single logical device with full cross-channel synchronization and shared calibration paths. This mode enables true 8×8 spatial processing (beamforming, full-array DoA, high-order MIMO benchmarks).
+  - When to use: research/measurement requiring maximum antenna aperture, advanced beamforming or direction-finding, or when coherent processing across all channels is required.
+
+- **2 independent 4×4 MIMO systems**
+
+  - The 8×8 array is split into two independent 4×4 logical devices. Each group has its own stream context and can be controlled separately while still retaining 4×4 MIMO capability within the group.
+  - When to use: deploying two separate 4×4 systems (for example, two co-located base stations or one monitoring system plus one comms system), or when slightly reduced MIMO order still meets spatial processing requirements but host/throughput constraints dictate partitioning.
+
+- **4 independent 2×2 MIMO systems**
+
+  - The array is split into four independent 2×2 logical devices, each suitable for small-scale MIMO links or parallel monitoring tasks.
+  - When to use: scenarios requiring multiple independent narrow-band links or many small testbeds.
+
+
 Connections
 ===========
 
@@ -98,6 +116,9 @@ The MHF4 connector of each xSDR module should be connected as shown in the pictu
 Back side
 ---------
 
+The back side of the xMASS SDR contains the clocking and synchronization circuitry, RF distribution network and calibration sources.
+The picture below shows the standard standalone configuration with one xMASS SDR board.
+
 .. image:: ../_static/xmass_back_zoom_light.jpg
    :alt: xmass sdr
 
@@ -115,8 +136,8 @@ Clocks and synchronization
 
 There are two clock domains on the xMASS SDR:
 
-* **REFCLK**: Reference clock used for phase synchronization and RF frequency calibration.
-* **SYSREF**: Event synchronization: start, stop, and other control signals.
+* **REFCLK**: The continuous reference frequency distributed to the xMASS board and all attached xSDR modules. It provides the master frequency reference used to lock local PLLs, generate sampling clocks and to perform RF frequency calibration across channels.
+* **SYSREF**: A timing/event synchronization pulse distributed to all xSDR modules. It defines deterministic frame boundaries and is used to align converters, FIFOs and JESD-like datastream boundaries so that samples across multiple channels/boards have known, repeatable timing.
 
 The **LMK05318B** serves as the central clocking IC on the xMASS SDR and can use different clock sources:
 
@@ -130,30 +151,51 @@ The IC produces the following output signals:
 * SYSREF output to all xSDR modules.
 * Calibrated reference clock output for the RF calibration loop.
 
+.. note::
+   | Bold blue dotted lines in the picture above show the connections for standalone mode.
+   | Bold green dotted lines in the picture above show the connections for multiboard mode.
+
+
 Standalone mode
 ---------------
 
-Standalone mode is used when only one xMASS SDR is present. In this mode most distribution schemes can be avoided, and synchronization buses should be connected as follows:
+The standalone mode provides a self-contained clock and event synchronization scheme for a single xMASS board.
 
-* ``REF_OUT_A`` to ``REF_IN``.
-* ``SYSREF_OUT`` to ``SYSREF_IN``.
+**Signal flow**
+
+Physical connections:
+
+  - ``REF_OUT_A`` -> ``REF_IN`` (local reference routing to module A).
+  - ``SYSREF_OUT`` -> ``SYSREF_IN`` (local SYSREF distribution).
+
+**Logical behaviour:**
+
+  - LMK05318B drives local REFCLK and SYSREF to all onboard xSDR modules.
+  - An optionally-attached external source or GPS may be selected as the REFCLK input.
 
-.. note::
-   | Bold blue dotted lines in the picture above show the connections for standalone mode.
 
 Multiboard mode
 ---------------
 
-If you need to use multiple xMASS SDR boards synchronized together, you can use the following connection scheme:
+The multiboard mode provides a distributed clock and event synchronization architecture for multiple xMASS boards so that REFCLK and SYSREF are common and phase-aligned across the whole array.
 
-* ``OUT_REF_B0`` to ``REF_IN`` on the same (master) board.
-* ``OUT_REF_B1``, ``OUT_REF_B2`` and ``OUT_REF_B3`` to ``REF_IN`` on each additional (slave) board, respectively.
-* ``SYSREF_OUT`` to ``SYSREF_B_IN`` on the same (master) board.
-* ``SYSREF_B_0`` to ``SYSREF_IN`` on the same (master) board.
-* ``SYSREF_B_1``, ``SYSREF_B_2`` and ``SYSREF_B_3`` to ``SYSREF_IN`` on each additional (slave) board, respectively.
+**Signal flow (master / slave)**
+
+  - Master board:
+
+    - ``OUT_REF_B0`` -> ``REF_IN`` on master (primary reference distribution output).
+    - ``SYSREF_OUT`` -> ``SYSREF_B_IN`` on master (SYSREF distribution input/output routing).
+
+  - Slave boards:
+
+    - ``OUT_REF_B1``, ``OUT_REF_B2``, ``OUT_REF_B3`` -> ``REF_IN`` on each slave board as required.
+    - ``SYSREF_B_1``, ``SYSREF_B_2``, ``SYSREF_B_3`` -> ``SYSREF_IN`` on each slave board respectively.
+
+**Logical behaviour**
+
+  - One board acts as the master reference source; other boards lock to that source for both REFCLK and SYSREF.
+  - LMK05318B on the master can be driven by GPS or an external disciplined source to provide absolute time/frequency across the entire array.
 
-.. note::
-   | Bold green dotted lines in the picture above show the connections for multiboard mode.
 
 RF distribution
 ===============
@@ -165,15 +207,34 @@ RF distribution
    | The diagram above shows the RF distribution for one pair of RX/TX channels.
    | The rest of the channels are connected in the same way.
 
-In standalone mode, the RF distribution should be connected as follows:
 
-* ``RF_CAL_OUT`` to ``RF_CAL_IN``.
+Standalone mode
+---------------
+
+The standalone mode provides a closed-loop calibration path and a local RF calibration reference when a single xMASS board is used.
+
+**Signal flow**
+
+  - ``RF_CAL_OUT`` -> ``RF_CAL_IN`` (local calibration loop through the frontend on the same board).
+  - Calibration source (``NOISE`` or ``CAL``) is switched into LNA/RX paths under software control when required.
+
+
+Multiboard mode
+---------------
 
-In multiboard mode, the RF distribution should be connected as follows:
+The multiboard mode provides calibration and routing scheme for multiple synchronized xMASS boards so that calibration signals and RF paths are common across the array, enabling coherent multi-board MIMO and consistent calibration measurements.
+
+**Signal flow (master / slave)**
+
+  - Master board:
+
+    - ``RF_CAL_OUT`` -> ``RF_B_IN`` (feeds the distributed calibration bus that other boards listen to).
+    - ``RF_0`` -> ``RF_CAL_IN`` (local calibration loop using the master board's RF path).
+
+  - Slave boards:
+
+    - ``RF_1``, ``RF_2``, ``RF_3`` -> ``RF_CAL_IN`` on each additional (slave) board, respectively (receive the calibration reference from the master).
 
-* ``RF_CAL_OUT`` to ``RF_B_IN`` on the same (master) board.
-* ``RF_0`` to ``RF_CAL_IN`` on the same (master) board.
-* ``RF_1``, ``RF_2`` and ``RF_3`` to ``RF_CAL_IN`` on each additional (slave) board, respectively.
 
 .. note::
    | Bold blue dotted lines in the picture above show connections for standalone mode.
@@ -194,7 +255,7 @@ The possible RF paths are:
 * Calibration path: NOISE or CAL signal to xSDR module for RX calibration.
 * Loopback path: TX from xSDR module to RX of the same channel for loopback testing.
 
-In addition, the NOISE/CAL signal can be routed to the first channel(LNAL_A) of each xSDR module directly through the M.2 socket.
+In addition, the ``NOISE``/``CAL`` signal can be routed to the first channel(LNAL_A) of each xSDR module directly through the M.2 socket.
 This avoids using the RF frontend, resulting in more accurate calibration.
 
 
@@ -209,35 +270,40 @@ Frontend control
 GENERAL
 -------
 
-.. list-table::
-   :header-rows: 1
+This section describes the general control of the board.
 
-   * - Register
-     - Type
-     - Description
-   * - /dm/sdr/refclk/path
-     -  - internal - Internal clock source/Single board operation
+
+.. image:: ../_static/xmass/xmass_control_general.png
+   :alt: xmass sdr frontend control screenshot
+
+
+
+* - ``/dm/sdr/refclk/path`` - Reference clock source selection
+
+    - Options:
+
+        - internal - Internal clock source/Single board operation
         - external - External clock source/Multi board operation
-     - Reference clock source selection
-   * - /dm/sdr/refclk/frequency
-     - int
-     - Reference clock frequency in Hz
-   * - /dm/sdr/0/sync/cal/path
-     -  - 0 - Normal operation
+
+* - ``/dm/sdr/refclk/frequency`` - Reference clock frequency in Hz
+
+* - ``/dm/sdr/0/sync/cal/path`` - Calibration path selection
+
+    - Options:
+
+        - 0 - Normal operation
         - 1 - LO
         - 2 - NOISE
         - 3 - LO_LNA3
         - 4 - NOISE_LNA3
-     - Calibration path selection
-   * - /dm/sdr/0/sync/cal/freq
-     - int
-     - LO calibration frequency in Hz
+
+* - ``/dm/sdr/0/sync/cal/freq`` - LO calibration frequency in Hz
 
 
 SYSREF
 ------
 
-In order to enable sysref mode, you have to pass one of the following values to the ``usdr_dms_sync`` api call.
+In order to select synchronization mode, you have to pass one of the following values to the ``usdr_dms_sync`` api call.
 
 - ``all`` - enable all supported sync sources (sysref, stream-based, external PPS, etc.).
 - ``1pps`` or ``sysref`` - explicit sysref via an external 1PPS pulse (external PPS/sysref).
@@ -256,7 +322,7 @@ This section describes the low level control of the board.
 
 
 .. image:: ../_static/xmass/xmass_control_xmass.png
-   :alt: xmass sdr frontend control screenshot
+   :alt: xmass sdr lowlevel control screenshot
 
 
 .. list-table::
@@ -322,7 +388,6 @@ Software
 
 
 In order to use xMASS SDR, you can use the **usdr_dm_create** utility to receive or transmit data.
-B
 The following example creates a raw IQ data file with a sample rate of 10 MSamples per second per channel, a center frequency of 1700 MHz, using all 8 RX channels:
 
 
@@ -331,6 +396,13 @@ The following example creates a raw IQ data file with a sample rate of 10 MSampl
    usdr_dm_create -D bus=pci/dev/usdr0:/dev/usdr1:/dev/usdr2:/dev/usdr3 -r10e6 -l3 -e1700e6 -c -f output.raw
 
 
+If you want to enable synchronization using SYSREF, you can add the ``-s sysref`` option to the command line:
+
+.. code-block:: bash
+
+   usdr_dm_create -D bus=pci/dev/usdr0:/dev/usdr1:/dev/usdr2:/dev/usdr3 -s sysref -r10e6 -l3 -e1700e6 -c -f output.raw
+
+
 The first device in the list(usdr0 in this example) should be the master xMASS SDR board(slot A).
 
 The software stack supports the **SoapySDR** interface, so you can use any compatible application.

source/software/usdr_registers.rst

@@ -49,8 +49,16 @@ The code below shows how to do this with ``usdr_dm_create`` utility.
 The ``usdr_dm_create`` utility should start normally. Debug mode instructs the uSDR library to create the ``usdr_debug_pipe`` named pipe for communication with the ``usdr_registers`` tool.
 Now you should open the second terminal window at the same directory when the application was started and run the ``usdr_registers`` tool.
 
+
+.. code-block:: bash
+
+   usdr_dm_create
+
+Alternatively, you can specify the named pipe path directly using the ``--pipe`` option of the ``usdr_registers`` tool.
+
+
 .. code-block:: bash
 
-   usdr_registers
+   usdr_registers --pipe /path/to/usdr_debug_pipe
 
 The ``usdr_registers`` tool will connect to the running application via the named pipe and display the control window.