Spi engine abstraction fifo mode enable

docs/library/spi_engine/axi_spi_engine.rst

@@ -42,8 +42,8 @@ Configuration Parameters
      - Configures the size of the serial-data out FIFO.
    * - SDI_FIFO_ADDRESS_WIDTH
      - Configures the size of the serial-data in FIFO.
-   * - NUM_OFFLOAD
-     - The number of offload control interfaces.
+   * - OFFLOAD_EN
+     - Enable the offload module interface.
 
 Signal and Interface Pins
 --------------------------------------------------------------------------------

docs/library/spi_engine/tutorial.rst

@@ -72,32 +72,49 @@ each IP individually or by using the function provided by the
 
 Using the script ensures that the correct connections are being made and that
 the IP cores will receive the correct parameter configuration since certain
-parameters need to be set to the same value. The function takes the following
-arguments:
+parameters need to be set to the same value. The same script can be used for
+Intel and Xilinx projects, and it is expected to have the same script for other
+vendors in the future. The function takes the following arguments:
 
 .. code:: tcl
 
-   proc spi_engine_create {{name "spi_engine"} {data_width 32} {async_spi_clk 1} {num_cs 1} {num_sdi 1} {num_sdo 1} {sdi_delay 0} {echo_sclk 0} {cmd_mem_addr_width 4} {data_mem_addr_width 4} {sdi_fifo_addr_width 5} {sdo_fifo_addr_width 5} {sync_fifo_addr_width 4} {cmd_fifo_addr_width 4}}
+   proc spi_engine_create {args}
 
-**data_width** will set the width of the data bus / data line used by the SPI
-engine to connect to the DMA and which serves the purpose of sending ADC sample
-data to the DDR memory. The data_width value will also set the maximum word
-length for the SPI transfer. Valid values are are 8/16/24/32. The DMA valid
-values are 16/32/64/128[…]. Since the Pulsar_ADC devices are all single SDI/SDO
-and some of them require 18bit transfers, this value will be rounded to 32bit.
+**args[0] - name** is mandatory for all Xilinx projects.
 
-**async_spi_clk** will chose the reference clock for the SPI Engine. Setting
-this parameter to 0 will configure the hierarchy to use the axi clock (100MHz)
-as the reference clock. Setting it to 1 will allow for an external reference
-clock (spi_clk). Because some devices need 80MHz SCLK, a 160MHz reference clock
-is required which implies an external reference.
+**args[1] - data_width** will set the width of the data bus / data line used by
+the SPI engine to connect to the DMA and which serves the purpose of sending
+ADC sample data to the DDR memory. The data_width value will also set the
+maximum word length for the SPI transfer. Valid values are are 8/16/24/32. The
+DMA valid values are 16/32/64/128[…]. Since the Pulsar_ADC devices are all
+single SDI/SDO and some of them require 18bit transfers, this value will be
+rounded to 32bit.
 
-**num_cs** selects the number of CS lines.
+**args[2] - async_spi_clk** will chose the reference clock for the SPI Engine.
+Setting this parameter to 0 will configure the hierarchy to use the axi clock
+(100MHz) as the reference clock. Setting it to 1 will allow for an external
+reference clock (spi_clk). Because some devices need 80MHz SCLK, a 160MHz
+reference clock is required which implies an external reference.
 
-**num_sdi** selects the number of SDI lines.
+**args[3] - offload_en** enables the offload mode of the SPI Engine. This is
+useful for situation where only FIFO mode are needed. By default, offload mode
+is enabled.
+
+**args[4] - num_cs** selects the number of CS lines.
+
+**args[5] - num_sdi** selects the number of SDI lines.
+
+**args[6] - num_sdo** selects the number of SDO lines.
+
+**args[7] - sdi_delay** The latch of the SDI line can be delayed with 1, 2 or
+3 SPI core clock cycle. Needed for designs with high SCLK rate (>50MHz).
+
+**args[8] - echo_sclk** enables the usage of external echo_sclk.
+
+**args[9] - sdo_streaming** Enables the s_axis_sdo interface. This allows for
+sourcing the SDO data stream from a DMA or other similar sources, useful for
+DACs.
 
-**sdi_delay** The latch of the SDI line can be delayed with 1, 2 or 3 SPI core
-clock cycle. Needed for designs with high SCLK rate (>50MHz).
 
 Configuration tcl code and result below:
 
@@ -107,12 +124,13 @@ Configuration tcl code and result below:
 
    set data_width    32
    set async_spi_clk 1
+   set offload_en    1
    set num_cs        1
    set num_sdi       1
    set sdi_delay     1
    set hier_spi_engine spi_pulsar_adc
 
-   spi_engine_create $hier_spi_engine $data_width $async_spi_clk $num_cs $num_sdi $sdi_delay
+   spi_engine_create $hier_spi_engine $data_width $async_spi_clk $offload_en $num_cs $num_sdi $sdi_delay
 
 .. image:: tutorial/pulsar_hdl_1.svg
    :align: center

docs/user_guide/ip_cores/use_adi_ips.rst

@@ -154,9 +154,9 @@ Vivado
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The SPI Engine is a special module too, since it consists of more than one IP.
-In order to use it into your own project, you will have to add all of its components.
-For this example, the code shown here is from the ad4630_fmc project:
-:git-hdl:`projects/ad4630_fmc/common/ad463x_bd.tcl`
+In order to use it into your own project, you will have to add all of its
+components. For this example, the code shown here is from the ad4630_fmc
+project: :git-hdl:`projects/ad4630_fmc/common/ad463x_bd.tcl`
 
 Let's start with sourcing the spi_engine.tcl script inside your ``<project>_db.tcl``.
 
@@ -167,22 +167,61 @@ Let's start with sourcing the spi_engine.tcl script inside your ``<project>_db.t
 The SPI engine has 4 modules: execution, interconnect, regmap and offload.
 
 All of the modules are instantiated inside the ``spi_engine_create`` function.
-This function requires 13 parameters. The default values for them are as follow,
-but feel free to configure it as you want:
+Offload_en variable define whether offload and interconnect are necessary or
+not for the project. This function requires 15 parameters for Xilinx projects,
+and 18 parameters for Quartus projects. The default values (Xilinx) for them are as
+follows, but feel free to configure it as you want:
 
 .. code:: tcl
 
-   {{name "spi_engine"} {data_width 32} {async_spi_clk 1} {num_cs 1} {num_sdi 1} {num_sdo 1} {sdi_delay 0} {echo_sclk 0} {cmd_mem_addr_width 4} {data_mem_addr_width 4} {sdi_fifo_addr_width 5} {sdo_fifo_addr_width 5} {sync_fifo_addr_width 4} {cmd_fifo_addr_width 4}}
+   {{name "spi_engine"} {data_width 32} {async_spi_clk 1} {offload_en 1} {num_cs 1} {num_sdi 1} {num_sdo 1} {sdi_delay 0} {echo_sclk 0} {sdo_streaming 0} {cmd_mem_addr_width 4} {data_mem_addr_width 4} {sdi_fifo_addr_width 5} {sdo_fifo_addr_width 5} {sync_fifo_addr_width 4} {cmd_fifo_addr_width 4}}
 
-An example of instantiation, using the default values for ``cmd_mem_addr_width``, ``data_mem_addr_width``, ``sdi_fifo_addr_width``, ``sdo_fifo_addr_width``, ``sync_fifo_addr_width`` and ``cmd_fifo_addr_width``:
+Name is a mandatory input. An example of instantiation (Xilinx project), using
+the default values for ``sdo_streaming``, ``cmd_mem_addr_width``,
+``data_mem_addr_width``, ``sdi_fifo_addr_width``, ``sdo_fifo_addr_width``,
+``sync_fifo_addr_width`` and ``cmd_fifo_addr_width``:
 
 .. code:: tcl
 
-   #                 name         data_width async_spi_clk num_csn num_sdi     sdi_delay  echo_sclk
-   spi_engine_create "spi_ad463x" 32         1             1       $NUM_OF_SDI 0          1
+   #                 name         data_width async_spi_clk offload_en num_csn num_sdi     sdi_delay  echo_sclk
+   spi_engine_create "spi_ad463x" 32         1             1          1       $NUM_OF_SDI 0          1
    ad_ip_parameter spi_ad463x/execution CONFIG.DEFAULT_SPI_CFG 1   ;
 
    ad_ip_parameter spi_ad463x/axi_regmap CONFIG.CFG_INFO_0 $NUM_OF_SDI
    ad_ip_parameter spi_ad463x/axi_regmap CONFIG.CFG_INFO_1 $CAPTURE_ZONE
    ad_ip_parameter spi_ad463x/axi_regmap CONFIG.CFG_INFO_2 $CLK_MODE
    ad_ip_parameter spi_ad463x/axi_regmap CONFIG.CFG_INFO_3 $DDR_EN
+
+Parameters and default values for Quartus projects:
+
+.. code:: tcl
+
+   {{name "spi_engine"} {axi_clk sys_clk.clk} {axi_reset sys_clk.clk_reset} {spi_clk spi_clk_pll.outclk0} {data_width 32} {async_spi_clk 1} {offload_en 1} {num_cs 1} {num_sdi 1} {num_sdo 1} {sdi_delay 0} {echo_sclk 0} {sdo_streaming 0} {cmd_mem_addr_width 4} {data_mem_addr_width 4} {sdi_fifo_addr_width 5} {sdo_fifo_addr_width 5} {sync_fifo_addr_width 4} {cmd_fifo_addr_width 4}}
+
+Name, axi_clk, axi_reset, and spi_clk are mandatory inputs. An example of
+instantiation (Quartus project), using the default values for
+``sdo_streaming``, ``cmd_mem_addr_width``, ``data_mem_addr_width``,
+``sdi_fifo_addr_width``, ``sdo_fifo_addr_width``, ``sync_fifo_addr_width``,
+and ``cmd_fifo_addr_width``:
+
+.. code:: tcl
+
+   source $ad_hdl_dir/library/spi_engine/scripts/spi_engine.tcl
+
+   set spi_engine_hier spi_ad57xx
+
+   set data_width     32
+   set async_spi_clk  1
+   set offload_en     1
+   set num_cs         1
+   set num_sdi        1
+   set num_sdo        1
+   set sdi_delay      0
+   set echo_sclk      0
+   set sdo_streaming  1
+
+   set axi_clk sys_clk.clk
+   set axi_reset sys_clk.clk_reset
+   set spi_clk spi_clk_pll.outclk0
+
+   spi_engine_create $spi_engine_hier $axi_clk $axi_reset $spi_clk $data_width $async_spi_clk $offload_en $num_cs $num_sdi $num_sdo $sdi_delay $echo_sclk $sdo_streaming

library/spi_engine/axi_spi_engine/axi_spi_engine.v

@@ -43,7 +43,7 @@ module axi_spi_engine #(
   parameter SDI_FIFO_ADDRESS_WIDTH = 5,
   parameter MM_IF_TYPE = 0,
   parameter ASYNC_SPI_CLK = 0,
-  parameter NUM_OFFLOAD = 0,
+  parameter OFFLOAD_EN = 1,
   parameter OFFLOAD0_CMD_MEM_ADDRESS_WIDTH = 4,
   parameter OFFLOAD0_SDO_MEM_ADDRESS_WIDTH = 4,
   parameter ID = 0,

library/spi_engine/axi_spi_engine/axi_spi_engine_hw.tcl

@@ -28,7 +28,7 @@ ad_ip_parameter SDO_FIFO_ADDRESS_WIDTH INTEGER 5
 ad_ip_parameter SDI_FIFO_ADDRESS_WIDTH INTEGER 5
 ad_ip_parameter MM_IF_TYPE INTEGER 1
 ad_ip_parameter ASYNC_SPI_CLK INTEGER 0
-ad_ip_parameter NUM_OFFLOAD INTEGER 1
+ad_ip_parameter OFFLOAD_EN INTEGER 1
 ad_ip_parameter OFFLOAD0_CMD_MEM_ADDRESS_WIDTH INTEGER 4
 ad_ip_parameter OFFLOAD0_SDO_MEM_ADDRESS_WIDTH INTEGER 4
 ad_ip_parameter ID INTEGER 0
@@ -43,6 +43,7 @@ proc p_elaboration {} {
 
   set num_of_sdi [get_parameter_value NUM_OF_SDI]
   set data_width [get_parameter_value DATA_WIDTH]
+  set offload_en [get_parameter_value OFFLOAD_EN]
 
   # interrupt
 
@@ -152,31 +153,32 @@ proc p_elaboration {} {
 
   # Offload interfaces
 
-  add_interface offload0_cmd conduit end
-  add_interface_port offload0_cmd offload0_cmd_wr_en    wre   output  1
-  add_interface_port offload0_cmd offload0_cmd_wr_data  data  output  16
+  if {$offload_en == 1} {
+    add_interface offload0_cmd conduit end
+    add_interface_port offload0_cmd offload0_cmd_wr_en    wre   output  1
+    add_interface_port offload0_cmd offload0_cmd_wr_data  data  output  16
 
-  set_interface_property offload0_cmd associatedClock if_spi_clk
-  set_interface_property offload0_cmd associatedReset none
+    set_interface_property offload0_cmd associatedClock if_spi_clk
+    set_interface_property offload0_cmd associatedReset none
 
-  add_interface offload0_sdo conduit end
-  add_interface_port offload0_sdo offload0_sdo_wr_en    wre   output  1
-  add_interface_port offload0_sdo offload0_sdo_wr_data  data  output  $data_width
+    add_interface offload0_sdo conduit end
+    add_interface_port offload0_sdo offload0_sdo_wr_en    wre   output  1
+    add_interface_port offload0_sdo offload0_sdo_wr_data  data  output  $data_width
 
-  set_interface_property offload0_sdo associatedClock if_spi_clk
-  set_interface_property offload0_sdo associatedReset none
+    set_interface_property offload0_sdo associatedClock if_spi_clk
+    set_interface_property offload0_sdo associatedReset none
 
-  ad_interface signal  offload0_mem_reset  output  1   reset
-  ad_interface signal  offload0_enable     output  1   enable
-  ad_interface signal  offload0_enabled    input   1   enabled
+    ad_interface signal  offload0_mem_reset  output  1   reset
+    ad_interface signal  offload0_enable     output  1   enable
+    ad_interface signal  offload0_enabled    input   1   enabled
 
-  add_interface offload_sync axi4stream end
-  add_interface_port offload_sync offload_sync_valid  tvalid input   1
-  add_interface_port offload_sync offload_sync_ready  tready output  1
-  add_interface_port offload_sync offload_sync_data   tdata  input   8
-
-  set_interface_property offload_sync associatedClock if_spi_clk
-  set_interface_property offload_sync associatedReset if_spi_resetn
+    add_interface offload_sync axi4stream end
+    add_interface_port offload_sync offload_sync_valid  tvalid input   1
+    add_interface_port offload_sync offload_sync_ready  tready output  1
+    add_interface_port offload_sync offload_sync_data   tdata  input   8
 
+    set_interface_property offload_sync associatedClock if_spi_clk
+    set_interface_property offload_sync associatedReset if_spi_resetn
+  }
 }
 

library/spi_engine/axi_spi_engine/axi_spi_engine_ip.tcl

@@ -70,7 +70,7 @@ foreach port {"up_clk" "up_rstn" "up_wreq" "up_waddr" "up_wdata" "up_rreq" "up_r
   set_property DRIVER_VALUE "0" [ipx::get_ports $port]
 }
 adi_set_bus_dependency "spi_engine_offload_ctrl0" "spi_engine_offload_ctrl0" \
-	"(spirit:decode(id('MODELPARAM_VALUE.NUM_OFFLOAD')) > 0)"
+	"(spirit:decode(id('MODELPARAM_VALUE.OFFLOAD_EN')) == 1)"
 
 adi_set_bus_dependency "s_axi" "s_axi" \
       "(spirit:decode(id('MODELPARAM_VALUE.MM_IF_TYPE')) = 0)"
@@ -162,13 +162,12 @@ set_property -dict [list \
  ] \
  [ipx::get_hdl_parameters ASYNC_SPI_CLK -of_objects $cc]
 
-## NUM_OFFLOAD
+## OFFLOAD_EN
 set_property -dict [list \
-  "value_validation_type" "range_long" \
-  "value_validation_range_minimum" "0" \
-  "value_validation_range_maximum" "8" \
+  "value_format" "bool" \
+  "value" "true" \
  ] \
- [ipx::get_user_parameters NUM_OFFLOAD -of_objects $cc]
+ [ipx::get_user_parameters OFFLOAD_EN -of_objects $cc]
 
 ## OFFLOAD0_CMD_MEM_ADDRESS_WIDTH
 set_property -dict [list \
@@ -277,25 +276,25 @@ set_property -dict [list \
 set offload_group [ipgui::add_group -name "Offload module configuration" -component $cc \
     -parent $page0 -display_name "Offload module configuration" ]
 
-ipgui::add_param -name "NUM_OFFLOAD" -component $cc -parent $offload_group
+ipgui::add_param -name "OFFLOAD_EN" -component $cc -parent $offload_group
 set_property -dict [list \
-  "display_name" "Number of offloads" \
-  "tooltip" "\[NUM_OFFLOAD\] Number of offloads" \
-] [ipgui::get_guiparamspec -name "NUM_OFFLOAD" -component $cc]
+  "display_name" "Offload interface enable" \
+  "tooltip" "\[OFFLOAD_EN\] Enable the offload module interface" \
+] [ipgui::get_guiparamspec -name "OFFLOAD_EN" -component $cc]
 
 ipgui::add_param -name "OFFLOAD0_CMD_MEM_ADDRESS_WIDTH" -component $cc -parent $offload_group
 set_property -dict [list \
   "display_name" "Offload command FIFO address width" \
   "tooltip" "\[OFFLOAD0_CMD_MEM_ADDRESS_WIDTH\] Define the depth of the FIFO" \
 ] [ipgui::get_guiparamspec -name "OFFLOAD0_CMD_MEM_ADDRESS_WIDTH" -component $cc]
-set_property enablement_tcl_expr {$NUM_OFFLOAD > 0} [ipx::get_user_parameters OFFLOAD0_CMD_MEM_ADDRESS_WIDTH -of_objects $cc]
+set_property enablement_tcl_expr {$OFFLOAD_EN == 1} [ipx::get_user_parameters OFFLOAD0_CMD_MEM_ADDRESS_WIDTH -of_objects $cc]
 
 ipgui::add_param -name "OFFLOAD0_SDO_MEM_ADDRESS_WIDTH" -component $cc -parent $offload_group
 set_property -dict [list \
   "display_name" "Offload MOSI FIFO address width" \
   "tooltip" "\[OFFLOAD0_SDO_MEM_ADDRESS_WIDTH\] Define the depth of the FIFO" \
 ] [ipgui::get_guiparamspec -name "OFFLOAD0_SDO_MEM_ADDRESS_WIDTH" -component $cc]
-set_property enablement_tcl_expr {$NUM_OFFLOAD > 0} [ipx::get_user_parameters OFFLOAD0_SDO_MEM_ADDRESS_WIDTH -of_objects $cc]
+set_property enablement_tcl_expr {$OFFLOAD_EN == 1} [ipx::get_user_parameters OFFLOAD0_SDO_MEM_ADDRESS_WIDTH -of_objects $cc]
 
 ## Create and save the XGUI file
 ipx::create_xgui_files $cc

library/spi_engine/axi_spi_engine/axi_spi_engine_ltt.tcl

@@ -194,14 +194,14 @@ set ip [ipl::set_parameter -ip $ip \
     -group2 Config]
 
 set ip [ipl::set_parameter -ip $ip \
-    -id NUM_OFFLOAD \
+    -id OFFLOAD_EN \
     -type param \
     -value_type int \
     -conn_mod axi_spi_engine \
-    -title {Number of offloads} \
-    -default 0 \
+    -title {Offload interface enable} \
+    -default 1 \
     -output_formatter nostr \
-    -value_range {(0, 8)} \
+    -options {[('True', 1), ('False', 0)]} \
     -group1 {Offload module configuration} \
     -group2 Config]
 set ip [ipl::set_parameter -ip $ip \
@@ -212,7 +212,7 @@ set ip [ipl::set_parameter -ip $ip \
     -title {Offload command FIFO address width} \
     -default 4 \
     -output_formatter nostr \
-    -editable {(NUM_OFFLOAD > 0)} \
+    -editable {(OFFLOAD_EN == 1)} \
     -value_range {(1, 16)} \
     -group1 {Offload module configuration} \
     -group2 Config]
@@ -224,7 +224,7 @@ set ip [ipl::set_parameter -ip $ip \
     -title {Offload MOSI FIFO address width} \
     -default 4 \
     -output_formatter nostr \
-    -editable {(NUM_OFFLOAD > 0)} \
+    -editable {(OFFLOAD_EN == 0)} \
     -value_range {(1, 16)} \
     -group1 {Offload module configuration} \
     -group2 Config]