changes to improve multiboard sync

docs/topics/index.rst

@@ -11,3 +11,4 @@ Specific topics
    gen_config
    units
    changing_fs
+   reference_clock

docs/topics/reference_clock.rst

@@ -0,0 +1,38 @@
+Reference clock generation
+==========================
+
+It's an advantage of the RFSoC that all of the DAC and ADC clocks are synthesized from a common reference and are always phase-locked with respect to each other.
+This reference is generated by dedicated clock synthesizer chips which are normally locked to an on-board reference oscillator.
+The on-board oscillator is pretty good (sub-ppm stability, check the board schematics), better than the linewidths of most devices.
+
+The clock chips are configured the first time you initialize :class:`.QickSoc()` after powering on your board; after that, they are normally only reconfigured if you are specifying a certain configuration (such as external clock, see below).
+You will see some LEDs come on when the clocks are configured; they should then stay on continously without flickering, except when reconfigured.
+On the ZCU216/ZCU208, the clock chips and their status LEDs are on the CLK104 daughterboard. For the other boards, the clock chips and LEDs are on the main board.
+
+* ZCU111: four LEDs in a row, labeled "4208 STATUS" and "MUXOUT RF1/2/3"
+* ZCU216/ZCU208: the clock chips and LEDs are on the CLK104 daughterboard; one LED is a power indicator and three are status
+* RFSoC4x2: four LEDs in a row, labeled "CLOCK STATUS"
+
+External clock
+--------------
+
+You might want to lock your board to an external clock source for two reasons:
+
+* Frequency stability: the on-board reference oscillator is good but not perfect.
+  If you play a continuous tone from a DAC into a spectrum analyzer and put your finger on the oscillator's metal can, you will see the frequency shift by hundreds of Hz. 
+  You might need better stability, such as what you get from a rubidium reference.
+* Synchronization: you may need the RFSoC to be phase- or frequency-locked to other instrumentation or other RFSoCs.
+
+QICK, and all of the supported RFSoC boards, accept an external reference clock. 
+To make your board lock to a reference, use the ``external_clk=True`` argument to :class:`.QickSoc()`.
+See the API documentation for the connector and the needed frequency.
+To figure out the needed power in whatever unit makes sense to you, the input circuit is as follows:
+
+* ZCU111: 3 dB attenuator to single-ended AC-coupled LMK04208 input.
+* ZCU216/ZCU208 (the clock references are on the CLK104 daughterboard): 3 dB attenuator to single-ended AC-coupled LMK04828B input.
+* RFSoC4x2: no attenuation, to single-ended AC-coupled LMK04828B input.
+
+The LMK04208/LMK04828B data sheets specify an input signal of 0.25/0.35 to 2.4 Vpp. You can work out the details, but 0-10 dBm is a safe range.
+
+There is also an ``clk_output=True`` argument that you can use to output a reference signal (you can use this independently of whether you're using an external clock).
+This is at a frequency that's not likely to be useful to you, except as a way to monitor the lock.

firmware/ip/qick_processor/component.xml

@@ -2236,7 +2236,7 @@
         <spirit:parameters>
           <spirit:parameter>
             <spirit:name>viewChecksum</spirit:name>
-            <spirit:value>203158e2</spirit:value>
+            <spirit:value>b6bbf956</spirit:value>
           </spirit:parameter>
         </spirit:parameters>
       </spirit:view>
@@ -2255,7 +2255,7 @@
         <spirit:parameters>
           <spirit:parameter>
             <spirit:name>viewChecksum</spirit:name>
-            <spirit:value>203158e2</spirit:value>
+            <spirit:value>b6bbf956</spirit:value>
           </spirit:parameter>
         </spirit:parameters>
       </spirit:view>
@@ -2284,7 +2284,7 @@
         <spirit:parameters>
           <spirit:parameter>
             <spirit:name>viewChecksum</spirit:name>
-            <spirit:value>8738b4a6</spirit:value>
+            <spirit:value>4ab07b4f</spirit:value>
           </spirit:parameter>
         </spirit:parameters>
       </spirit:view>
@@ -6487,7 +6487,7 @@
       <spirit:file>
         <spirit:name>xgui/qick_processor_v2_0.tcl</spirit:name>
         <spirit:fileType>tclSource</spirit:fileType>
-        <spirit:userFileType>CHECKSUM_8738b4a6</spirit:userFileType>
+        <spirit:userFileType>CHECKSUM_4ab07b4f</spirit:userFileType>
         <spirit:userFileType>XGUI_VERSION_2</spirit:userFileType>
       </spirit:file>
     </spirit:fileSet>
@@ -6511,7 +6511,7 @@
     </spirit:parameter>
     <spirit:parameter>
       <spirit:name>REG_AW</spirit:name>
-      <spirit:displayName>General Purpouse Register Address Width</spirit:displayName>
+      <spirit:displayName>General Purpose Register Address Width</spirit:displayName>
       <spirit:value spirit:format="long" spirit:resolve="user" spirit:id="PARAM_VALUE.REG_AW" spirit:minimum="3" spirit:maximum="5" spirit:rangeType="long">4</spirit:value>
     </spirit:parameter>
     <spirit:parameter>
@@ -6631,42 +6631,17 @@
   </spirit:parameters>
   <spirit:vendorExtensions>
     <xilinx:coreExtensions>
-      <xilinx:supportedFamilies>
-        <xilinx:family xilinx:lifeCycle="Production">virtex7</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">qvirtex7</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">versal</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">kintex7</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">kintex7l</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">qkintex7</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">qkintex7l</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">akintex7</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">artix7</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">artix7l</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">aartix7</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">qartix7</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">zynq</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">qzynq</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">azynq</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">spartan7</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">aspartan7</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">virtexu</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">zynquplus</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">virtexuplus</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">virtexuplusHBM</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">virtexuplus58g</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">kintexuplus</xilinx:family>
-        <xilinx:family xilinx:lifeCycle="Production">kintexu</xilinx:family>
-      </xilinx:supportedFamilies>
       <xilinx:taxonomies>
         <xilinx:taxonomy>/UserIP</xilinx:taxonomy>
       </xilinx:taxonomies>
       <xilinx:displayName>qick_processor</xilinx:displayName>
+      <xilinx:autoFamilySupportLevel>level_2</xilinx:autoFamilySupportLevel>
       <xilinx:definitionSource>package_project</xilinx:definitionSource>
-      <xilinx:coreRevision>23</xilinx:coreRevision>
+      <xilinx:coreRevision>24</xilinx:coreRevision>
       <xilinx:upgrades>
         <xilinx:canUpgradeFrom>user.org:user:axis_tproc_B:1.0</xilinx:canUpgradeFrom>
       </xilinx:upgrades>
-      <xilinx:coreCreationDateTime>2025-03-31T21:28:59Z</xilinx:coreCreationDateTime>
+      <xilinx:coreCreationDateTime>2025-06-05T23:02:03Z</xilinx:coreCreationDateTime>
       <xilinx:tags>
         <xilinx:tag xilinx:name="ui.data.coregen.dd@648bece3_ARCHIVE_LOCATION">/home/mdifeder/Projects/20.2/IPs/TPROCB_1</xilinx:tag>
         <xilinx:tag xilinx:name="ui.data.coregen.dd@7858384c_ARCHIVE_LOCATION">/home/mdifeder/Projects/20.2/IPs/TPROCB_1</xilinx:tag>
@@ -7509,10 +7484,10 @@
       <xilinx:xilinxVersion>2023.1</xilinx:xilinxVersion>
       <xilinx:checksum xilinx:scope="busInterfaces" xilinx:value="2897c82e"/>
       <xilinx:checksum xilinx:scope="memoryMaps" xilinx:value="769c350d"/>
-      <xilinx:checksum xilinx:scope="fileGroups" xilinx:value="8c3df720"/>
+      <xilinx:checksum xilinx:scope="fileGroups" xilinx:value="760adee5"/>
       <xilinx:checksum xilinx:scope="ports" xilinx:value="f423e66e"/>
       <xilinx:checksum xilinx:scope="hdlParameters" xilinx:value="0a52d470"/>
-      <xilinx:checksum xilinx:scope="parameters" xilinx:value="18f0ddd6"/>
+      <xilinx:checksum xilinx:scope="parameters" xilinx:value="4960cdd2"/>
     </xilinx:packagingInfo>
   </spirit:vendorExtensions>
 </spirit:component>

firmware/ip/qick_processor/src/dsp_macro_0/dsp_macro_0.xci

@@ -154,7 +154,7 @@
       },
       "project_parameters": {
         "ARCHITECTURE": [ { "value": "zynquplusRFSOC" } ],
-        "BASE_BOARD_PART": [ { "value": "xilinx.com:zcu216:part0:2.0" } ],
+        "BASE_BOARD_PART": [ { "value": "" } ],
         "BOARD_CONNECTIONS": [ { "value": "" } ],
         "DEVICE": [ { "value": "xczu49dr" } ],
         "PACKAGE": [ { "value": "ffvf1760" } ],
@@ -710,4 +710,4 @@
       }
     }
   }
-}
+}

firmware/ip/qick_processor/src/qick_processor.sv

@@ -183,8 +183,6 @@ qproc_ctrl # (
    .t_rst_ni        ( t_rst_ni           ),
    .c_clk_i         ( c_clk_i            ),
    .c_rst_ni        ( c_rst_ni           ),
-   .ps_clk_i        ( ps_clk_i           ),
-   .ps_rst_ni       ( ps_rst_ni          ),
    .proc_start_i    ( proc_start_i       ),
    .proc_stop_i     ( proc_stop_i        ),
    .core_start_i    ( core_start_i       ),
@@ -195,8 +193,10 @@ qproc_ctrl # (
    .int_time_en     ( int_time_pen       ),
    .int_time_cmd    ( core_usr_operation[3:0] ),
    .int_time_dt     ( core_usr_b_dt      ),
-   .xreg_TPROC_CTRL ( xreg_TPROC_CTRL    ),
-   .xreg_TPROC_CFG  ( xreg_TPROC_CFG     ),
+   .PS_TPROC_CTRL   ( xreg_TPROC_CTRL    ),
+   .PS_TPROC_CFG    ( xreg_TPROC_CFG[10:9]),
+   // .xreg_TPROC_CTRL ( xreg_TPROC_CTRL    ),
+   // .xreg_TPROC_CFG  ( xreg_TPROC_CFG     ),
    .xreg_TPROC_W_DT ( xreg_TPROC_W_DT[0] ),
    .all_fifo_full_i ( all_fifo_full      ),
    .core_rst_o      ( core_rst           ),
@@ -410,8 +410,6 @@ qproc_mem_ctrl # (
 qproc_axi_reg QPROC_xREG (
    .ps_aclk          ( ps_clk_i            ) , 
    .ps_aresetn       ( ps_rst_ni           ) , 
-   .c_clk_i          ( c_clk_i             ) , 
-   .c_rst_ni         ( c_rst_ni            ) , 
    .IF_s_axireg      ( IF_s_axireg         ) ,
    .TPROC_CTRL       ( xreg_TPROC_CTRL     ) ,
    .TPROC_CFG        ( xreg_TPROC_CFG      ) ,
@@ -428,6 +426,7 @@ qproc_axi_reg QPROC_xREG (
    .TIME_USR         ( c_time_usr        ) ,
    .TPROC_STATUS     ( xreg_TPROC_STATUS   ) ,
    .TPROC_DEBUG      ( xreg_TPROC_DEBUG    ) );
+
 // AXI_REG TPROC_R_DT source selection
 ///////////////////////////////////////////////////////////////////////////////
 wire [ 3:0] tproc_src_dt;

firmware/ip/qick_processor/src/qproc_axi_reg.sv

@@ -5,28 +5,28 @@
 module qproc_axi_reg(
    input wire            ps_aclk      ,    
    input wire            ps_aresetn   ,
-   input wire            c_clk_i      ,    
-   input wire            c_rst_ni     ,
+   // input wire            c_clk_i      ,    
+   // input wire            c_rst_ni     ,
    TYPE_IF_AXI_REG.slave       IF_s_axireg  ,
-   output wire  [15:0]   TPROC_CTRL   ,    
-   output reg   [15:0]   TPROC_CFG    ,
-   output reg   [15:0]   MEM_ADDR     ,    
-   output reg   [15:0]   MEM_LEN      ,    
-   output reg   [31:0]   MEM_DT_I     ,    
-   output reg   [31:0]   TPROC_W_DT1  ,    
-   output reg   [31:0]   TPROC_W_DT2  ,    
-   output reg   [7:0]    CORE_CFG   ,    
-   output reg   [7:0]    READ_SEL   ,    
-   input  reg   [31:0]   MEM_DT_O     ,    
-   input  reg   [31:0]   TPROC_R_DT1  ,    
-   input  reg   [31:0]   TPROC_R_DT2  ,    
-   input  reg   [31:0]   TIME_USR     ,    
-   input  reg   [31:0]   TPROC_STATUS ,    
-   input  reg   [31:0]   TPROC_DEBUG     
-   );
+   output logic [15:0]   TPROC_CTRL   ,    
+   output logic [15:0]   TPROC_CFG    ,
+   output logic [15:0]   MEM_ADDR     ,    
+   output logic [15:0]   MEM_LEN      ,    
+   output logic [31:0]   MEM_DT_I     ,    
+   output logic [31:0]   TPROC_W_DT1  ,    
+   output logic [31:0]   TPROC_W_DT2  ,    
+   output logic [7:0]    CORE_CFG   ,    
+   output logic [7:0]    READ_SEL   ,    
+   input  wire  [31:0]   MEM_DT_O     ,    
+   input  wire  [31:0]   TPROC_R_DT1  ,    
+   input  wire  [31:0]   TPROC_R_DT2  ,    
+   input  wire  [31:0]   TIME_USR     ,    
+   input  wire  [31:0]   TPROC_STATUS ,    
+   input  wire  [31:0]   TPROC_DEBUG     
+);
 
 
-wire [15:0] PS_TPROC_CTRL, PS_TPROC_CFG;
+// wire [15:0] PS_TPROC_CTRL, PS_TPROC_CFG;
 
 // AXI Slave.
 axi_slv_qproc QPROC_xREG (
@@ -51,8 +51,8 @@ axi_slv_qproc QPROC_xREG (
    .rresp         ( IF_s_axireg.axi_rresp        ) , 
    .rvalid        ( IF_s_axireg.axi_rvalid       ) , 
    .rready        ( IF_s_axireg.axi_rready       ) , 
-   .TPROC_CTRL    ( PS_TPROC_CTRL                ) ,
-   .TPROC_CFG     ( PS_TPROC_CFG                 ) ,
+   .TPROC_CTRL    ( TPROC_CTRL                ) ,
+   .TPROC_CFG     ( TPROC_CFG                 ) ,
    .MEM_ADDR      ( MEM_ADDR                  ) ,
    .MEM_LEN       ( MEM_LEN                   ) ,
    .MEM_DT_I      ( MEM_DT_I                  ) ,
@@ -67,26 +67,29 @@ axi_slv_qproc QPROC_xREG (
    .TPROC_STATUS  ( TPROC_STATUS           ) ,
    .TPROC_DEBUG   ( TPROC_DEBUG            ) );
 
-
-reg [15:0] tproc_ctrl_rcd, tproc_ctrl_r, tproc_ctrl_2r;
-reg [15:0] tproc_cfg_rcd;
+//-------------------------------------------------------
+// Moved to qproc_ctrl due to issue #33
 
-// From PS_CLK to C_CLK
-always_ff @(posedge c_clk_i) 
-   if (!c_rst_ni) begin
-      tproc_ctrl_rcd  <= 0 ;
-      tproc_ctrl_r    <= 0 ;
-      tproc_ctrl_2r   <= 0 ;
-      tproc_cfg_rcd   <= 0 ;
-   end else begin 
-      tproc_ctrl_rcd  <= PS_TPROC_CTRL    ;
-      tproc_ctrl_r    <= tproc_ctrl_rcd  ;
-      tproc_ctrl_2r   <= tproc_ctrl_r  ;
-      tproc_cfg_rcd   <= PS_TPROC_CFG     ;
-      TPROC_CFG     <= tproc_cfg_rcd ;
-   end
+// reg [15:0] tproc_ctrl_rcd, tproc_ctrl_r, tproc_ctrl_2r;
+// reg [15:0] tproc_cfg_rcd;
 
-// The C_TPROC_CTRL is only ONE clock.
-assign TPROC_CTRL       = tproc_ctrl_r & ~tproc_ctrl_2r ;
+// // From PS_CLK to C_CLK
+// always_ff @(posedge c_clk_i) 
+//    if (!c_rst_ni) begin
+//       tproc_ctrl_rcd  <= 0 ;
+//       tproc_ctrl_r    <= 0 ;
+//       tproc_ctrl_2r   <= 0 ;
+//       tproc_cfg_rcd   <= 0 ;
+//    end else begin 
+//       tproc_ctrl_rcd  <= PS_TPROC_CTRL    ;
+//       tproc_ctrl_r    <= tproc_ctrl_rcd  ;
+//       tproc_ctrl_2r   <= tproc_ctrl_r  ;
+//       tproc_cfg_rcd   <= PS_TPROC_CFG     ;
+//       TPROC_CFG     <= tproc_cfg_rcd ;
+//    end
+
+// // The C_TPROC_CTRL is only ONE clock.
+// assign TPROC_CTRL       = tproc_ctrl_r & ~tproc_ctrl_2r ;
+//-------------------------------------------------------
 
 endmodule

firmware/ip/qick_processor/src/qproc_ctrl.sv

@@ -18,8 +18,6 @@ module qproc_ctrl # (
    input   wire        t_rst_ni        ,
    input   wire        c_clk_i         ,
    input   wire        c_rst_ni        ,
-   input   wire        ps_clk_i        ,
-   input   wire        ps_rst_ni       ,
 // External Control  
    input  wire         proc_start_i    ,
    input  wire         proc_stop_i     ,
@@ -33,8 +31,10 @@ module qproc_ctrl # (
    input  wire  [3:0]  int_time_cmd     , //core_usr_operation
    input  wire  [31:0] int_time_dt     , //core_usr_operation
 // AXI  Control  
-   input wire [15:0]   xreg_TPROC_CTRL ,
-   input wire [15:0]   xreg_TPROC_CFG  ,
+   input wire [15:0]   PS_TPROC_CTRL,
+   input wire [10:9]   PS_TPROC_CFG,
+   // input wire [15:0]   xreg_TPROC_CTRL ,
+   // input wire [15:0]   xreg_TPROC_CFG  ,
    input wire [31:0]   xreg_TPROC_W_DT ,
 // QPROC_STATE  
    input wire          all_fifo_full_i ,
@@ -54,6 +54,34 @@ module qproc_ctrl # (
    output reg   [ 6:0]  c_debug_do
 );
 
+//-------------------------------------------------------
+// Code moved from qproc_axi_reg due to issue #33
+logic [15:0]   xreg_TPROC_CTRL;
+logic [10:9]   xreg_TPROC_CFG, TPROC_CFG;
+
+logic [15:0]   tproc_ctrl_rcd, tproc_ctrl_r, tproc_ctrl_2r;
+logic [10:9]   tproc_cfg_rcd;
+
+// From PS_CLK to C_CLK
+always_ff @(posedge c_clk_i) 
+   if (!c_rst_ni) begin
+      tproc_ctrl_rcd  <= 0 ;
+      tproc_ctrl_r    <= 0 ;
+      tproc_ctrl_2r   <= 0 ;
+      tproc_cfg_rcd   <= 0 ;
+   end else begin 
+      tproc_ctrl_rcd  <= PS_TPROC_CTRL ;
+      tproc_ctrl_r    <= tproc_ctrl_rcd ;
+      tproc_ctrl_2r   <= tproc_ctrl_r ;
+      tproc_cfg_rcd   <= PS_TPROC_CFG ;
+      TPROC_CFG       <= tproc_cfg_rcd ;
+   end
+
+// The C_TPROC_CTRL is only ONE clock.
+assign xreg_TPROC_CTRL  = tproc_ctrl_r & ~tproc_ctrl_2r ;
+assign xreg_TPROC_CFG   = TPROC_CFG;
+//-------------------------------------------------------
+
 
 // Control
 reg            t_core_rst_prev_net; // NET Request to RESET the Processor and go to previous state

firmware/ip/qick_processor/xgui/qick_processor_v2_0.tcl

@@ -3,8 +3,7 @@ proc init_gui { IPINST } {
   ipgui::add_param $IPINST -name "Component_Name"
   #Adding Page
   set Page_0 [ipgui::add_page $IPINST -name "Page 0"]
-  ipgui::add_static_text $IPINST -name "Version" -parent ${Page_0} -text {Qick_Processor Revision 22 - 2024_10, ( Use Assembler Version v3 rev23 )}
-  ipgui::add_static_text $IPINST -name "Introduction" -parent ${Page_0} -text {Values for Memory size Port quantity and register amount can be modified in order to make a smaller and Faster processor }
+  ipgui::add_static_text $IPINST -name "Introduction" -parent ${Page_0} -text {Values for Memory size, port quantity, and register amount can be modified in order to make a smaller and faster processor}
   #Adding Group
   set Process [ipgui::add_group $IPINST -name "Process" -parent ${Page_0} -display_name {Processor Options}]
   set_property tooltip {Process} ${Process}
@@ -44,6 +43,7 @@ proc init_gui { IPINST } {
   ipgui::add_param $IPINST -name "OUT_WPORT_QTY" -parent ${GROUP1}
   ipgui::add_param $IPINST -name "OUT_DPORT_QTY" -parent ${GROUP1}
   ipgui::add_param $IPINST -name "OUT_DPORT_DW" -parent ${GROUP1}
+  ipgui::add_param $IPINST -name "FIFO_DEPTH" -parent ${GROUP1} -widget comboBox
 
   #Adding Group
   set GROUP [ipgui::add_group $IPINST -name "GROUP" -parent ${OUT_Port_Configuration} -display_name {QICK SIGNALS}]