docs/projects/fmcomms2: Update fir_filter.rst

Signed-off-by: BCapota <[email protected]>

Author: BCapota

docs/projects/fmcomms2/fir_filter.rst

@@ -6,7 +6,7 @@ Integrate FIR filters into the FMCOMMS2 HDL design
 Overview
 -------------------------------------------------------------------------------
 
-This wiki page describes how to add a custom processing module into the
+This page describes how to add a custom processing module into the
 :git-hdl:`FMCOMMS2 <projects/fmcomms2>`'s TX and/or RX data path.
 
 In this example, the custom modules are going to be some digital FIR filters, to
@@ -16,7 +16,7 @@ decimate and interpolate the incoming and outcoming data stream.
 
    This example was built using the hdl_2023_r2 release branch, using Vivado and
    Vitis 2023.2. Sources from older examples can be found under the tag
-   `eg_fmcomms2_fir_filter`_ using Vivado 16.2 and 16.4 versions, andstatus
+   `eg_fmcomms2_fir_filter`_ using Vivado 16.2 and 16.4 versions, and status
    **are not supported by us anymore**.
 
 Assuming we want to transmit a sinewave with the :adi:`AD9361` ADI Integrated RF
@@ -27,11 +27,12 @@ add some interpolation filters for transmitting.
 
 A similar problem is encountered on the ADC side when receiving a low-frequency
 signal. This can be solved with the use of decimation filters. In our example,
-these filters were already implemented in :git-hdl:`util_fir_int
-<library/util_fir_int>` and :git-hdl:`util_fir_dec <library/util_fir_dec>` HDL
-IP core, which are wrappers for the FIR Compiler Xilinx IP. The wrappers are
-used to manage the data rates entering the filter and to facilitate the
-configuration of the filter parameters for a specific application (TX/RX).
+these filters were already implemented in
+:git-hdl:`util_fir_int <library/util_fir_int>` and
+:git-hdl:`util_fir_dec <library/util_fir_dec>` HDL IP cores, which are wrappers
+for the FIR Compiler Xilinx IP. The wrappers are used to manage the data rates
+entering the filter and to facilitate the configuration of the filter
+parameters for a specific application (TX/RX).
 
 Choosing filter parameters and coefficients
 -------------------------------------------------------------------------------
@@ -103,13 +104,15 @@ Adding the filters in the data path
 -------------------------------------------------------------------------------
 
 In the original :git-hdl:`fmcomms2 <projects/fmcomms2>` design, the data comes
-from the :git-hdl:`DMA <library/axi_dmac>`, goes to the :git-hdl:`util_upack2
-<library/util_pack/util_upack2>` core which transmits the individual channel
-data to a :git-hdl:`dac_fifo <library/util_rfifo>` core, from which the
-:git-hdl:`axi_ad9361 <library/axi_ad9361>` core reads the data and transmits it
-to the :adi:`AD9361` chip. The util_upack2 core is used to split the 64-bit data
-containing 2 RF channels, each one having I/Q data. dac_fifo is used for
-clock-domain crossing between the system clock and the AD9361 clock.
+from the :git-hdl:`DMA <library/axi_dmac>`, goes to the
+:git-hdl:`util_upack2 <library/util_pack/util_upack2>` core which transmits
+the individual channel data to a :git-hdl:`dac_fifo <library/util_rfifo>` core,
+from which the :git-hdl:`axi_ad9361 <library/axi_ad9361>` core reads the data
+and transmits it to the :adi:`AD9361` chip.
+
+The util_upack2 core is used to split the 64-bit data containing 2 RF channels,
+each one having I/Q data. dac_fifo is used for clock-domain crossing between
+the system clock and the AD9361 clock.
 
 The data processing is done at lower clock frequencies. This is the reason for
 placing the interpolation filters in front of the dac_fifo module.
@@ -145,7 +148,7 @@ Understanding FMCOMMS2 clock routing
 Adding FIR filters in FMCOMMS2 design and building the HDL
 -------------------------------------------------------------------------------
 
-The design is obtain by simply sourcing the base FMCOMMS2 block design.
+The design is obtained by simply sourcing the base FMCOMMS2 block design.
 
 .. code-block:: tcl
 
@@ -167,9 +170,11 @@ can add the FIR filter modules in the reference design. With the following
 commands, all the unwanted connections will be removed and new ones will be
 created.
 
-All the TCL commands from this page are available in the `fir_filter.tcl` script
+All the TCL commands from this page are available in the `fir_filter.tcl`_ script
 located in `hdl/docs/projects/fmcomms2`.
 
+.. _fir_filter.tcl: https://analogdevicesinc.github.io/hdl/docs/projects/fmcomms2
+
 .. code-block:: tcl
 
    # delete reference design connections
@@ -187,10 +192,14 @@ We will disconnect/connect the Rx path in a similar manner.
    delete_bd_objs [get_bd_nets util_ad9361_adc_fifo_dout_enable_*]
    delete_bd_objs [get_bd_nets util_ad9361_adc_fifo_dout_data_*]
 
-Adding interpolation filters.
+Add the two required IP cores to the Makefile:
 
-Add the two required IP cores to the Makefile: **LIB_DEPS += util_fir_int** and
-**LIB_DEPS += util_fir_dec**.
+.. code-block::
+
+   LIB_DEPS += util_fir_int
+   LIB_DEPS += util_fir_dec
+
+Adding interpolation filters.
 
 .. code-block:: tcl
 
@@ -239,11 +248,11 @@ Data Rate) is presented in the diagram below:
 
 At this point, we have two options:
 
-#. Delete the upack_core and split the data into some simple slices
-#. Keep upack_core and the possibility to use half of the DMA bandwidth when
+#. Delete the util_ad9361_dac_upack and split the data into some simple slices
+#. Keep util_ad9361_dac_upack and the possibility to use half of the DMA bandwidth when
    one channel is not enabled.
 
-For this example, the upack_core was kept. The core's proprieties remain
+For this example, the util_ad9361_dac_upack was kept. The core's proprieties remain
 unchanged, and a concatenate module was added, in order to merge the data coming
 out from the unpack module, then feed it into the interpolation filter.
 
@@ -320,15 +329,6 @@ Connecting the FIR interpolation filters on the Tx side
 In this example, the TX data flow is controlled by the interpolation filter when
 interpolation is activated and by the axi_ad9361_core when interpolation is not
 active. In the reference design, the data flow is controlled by the ad9631_core.
-
-..
-   We must connect the upack_core's dma_xfer_in port to VCC so that the UPACK may
-   transmit the valid and enable signals from one entity to another.
-
-   .. code-block:: tcl
-
-      ad_connect util_ad9361_dac_upack/dma_xfer_in VCC
-
 At this moment, the Interpolation filters are completely integrated into the
 design and the data path should look like the one in the figure below.
 
@@ -379,7 +379,8 @@ Generating the programing files
 
    - If you did your changes in **GUI**, you can click on **"Generate Bitstream"**.
      After the bitstream generation is complete, click on **Files -> Export ->
-     Export Hardware**, then select **Include Bitstream** option.
+     Export Hardware**, then select **Include Bitstream** option, and the
+     folder to be saved, should be the **.sdk** folder.
    - If you did your changes directly in the **Tcl files**, you can use
      ``make`` to generate the bitstream and .xsa file.
    - Now, if your system is based on a **Zynq architecture**, you will have to
@@ -404,7 +405,7 @@ TX to RX for each channel with a SMA to SMA cable.
    :alt: FMCOMMS2_TXRX_LOOPBACK
 
 When first booting up the design, none of the filters will be active. For the
-beginning make sure you have the same **LO frequency for RX and TX**, as in the
+beginning, make sure you have the same **LO frequency for RX and TX**, as in the
 picture below.
 
 Configure the Transmit/DDS mode to *DAC Buffer Output*, and chose one of the
@@ -432,7 +433,7 @@ one of the two channels will be enabled.
    :align: center
    :alt: FMCOMMS2_FIR_SETUP_ACTIVATE_DMA_DATA_WAVEFORM
 
-To better understand what is happening with the data inside the FPGA, 3 ILAs
+To better understand what is happening with the data inside the FPGA, 3 ILA
 (Integrated Logic Analyzer) modules were added in the HDL design.
 
 The 1st ILA was connected to the control signals between the ad9361_core and the
@@ -550,10 +551,9 @@ All filters active characteristic
    :align: center
    :alt: FMCOMMS_FIR_TX_RX_ACTIVE_WAVEFORM
 
-Download
+Older sources
 -------------------------------------------------------------------------------
 
-- :dokuwiki:`boot.zip <_media/resources/fpga/docs/hdl/boot.zip>`
 - Sources from older examples can be found under the tag
   `eg_fmcomms2_fir_filter`_ using Vivado 16.2 and 16.4 versions, and
   **are not supported by us anymore**.
@@ -571,110 +571,3 @@ References
 .. _eg_fmcomms2_fir_filter: https://github.com/analogdevicesinc/hdl/releases/tag/eg_fmcomms2_fir_filter
 .. _MATLAB: https://www.mathworks.com/products/matlab.html
 .. _AXI AD9361: https://analogdevicesinc.github.io/hdl/library/axi_ad9361/index.html#register-map
-
-.. code-block:: tcl
-
-    # delete reference design connections
-    delete_bd_objs [get_bd_nets axi_ad9361_dac_fifo_din_valid_0]
-    delete_bd_objs [get_bd_nets axi_ad9361_dac_fifo_din_enable_*]
-    delete_bd_objs [get_bd_nets util_ad9361_dac_upack_fifo_rd_data_*]
-    delete_bd_objs [get_bd_nets util_ad9361_dac_upack_fifo_rd_underflow]
-    delete_bd_objs [get_bd_nets util_ad9361_dac_upack_fifo_rd_valid]
-
-    delete_bd_objs [get_bd_nets util_ad9361_adc_fifo_dout_valid_0]
-    delete_bd_objs [get_bd_nets util_ad9361_adc_fifo_dout_enable_*]
-    delete_bd_objs [get_bd_nets util_ad9361_adc_fifo_dout_data_*]
-
-    set util_fir_int_0 [create_bd_cell -type ip -vlnv analog.com:user:util_fir_int:1.0 util_fir_int_0]
-    set util_fir_int_1 [create_bd_cell -type ip -vlnv analog.com:user:util_fir_int:1.0 util_fir_int_1]
-
-    set interp_slice [create_bd_cell -type inline_hdl -vlnv xilinx.com:inline_hdl:ilslice:1.0 interp_slice]
-
-    set fir_decimator_0 [create_bd_cell -type ip -vlnv analog.com:user:util_fir_dec:1.0 fir_decimator_0]
-    set fir_decimator_1 [create_bd_cell -type ip -vlnv analog.com:user:util_fir_dec:1.0 fir_decimator_1]
-
-    set decim_slice [create_bd_cell -type inline_hdl -vlnv xilinx.com:inline_hdl:ilslice:1.0 decim_slice]
-
-    set concat_0 [create_bd_cell -type inline_hdl -vlnv xilinx.com:inline_hdl:ilconcat:1.0 concat_0]
-    set_property -dict [list CONFIG.IN1_WIDTH.VALUE_SRC USER CONFIG.IN0_WIDTH.VALUE_SRC USER] $concat_0
-    set_property -dict [list CONFIG.IN0_WIDTH {16} CONFIG.IN1_WIDTH {16}] $concat_0
-    set concat_1 [create_bd_cell -type inline_hdl -vlnv xilinx.com:inline_hdl:ilconcat:1.0 concat_1]
-    set_property -dict [list CONFIG.IN1_WIDTH.VALUE_SRC USER CONFIG.IN0_WIDTH.VALUE_SRC USER] $concat_1
-    set_property -dict [list CONFIG.IN0_WIDTH {16} CONFIG.IN1_WIDTH {16}] $concat_1
-    set pack0_slice_0 [create_bd_cell -type inline_hdl -vlnv xilinx.com:inline_hdl:ilslice:1.0 pack0_slice_0]
-    set_property -dict [list CONFIG.DIN_FROM {15}] $pack0_slice_0
-    set_property -dict [list CONFIG.DIN_TO {0}] $pack0_slice_0
-    set_property -dict [list CONFIG.DOUT_WIDTH {16}] $pack0_slice_0
-    set pack0_slice_1 [create_bd_cell -type inline_hdl -vlnv xilinx.com:inline_hdl:ilslice:1.0 pack0_slice_1]
-    set_property -dict [list CONFIG.DIN_FROM {31}] $pack0_slice_1
-    set_property -dict [list CONFIG.DIN_TO {16}] $pack0_slice_1
-    set_property -dict [list CONFIG.DOUT_WIDTH {16}] $pack0_slice_1
-    set pack1_slice_0 [create_bd_cell -type inline_hdl -vlnv xilinx.com:inline_hdl:ilslice:1.0 pack1_slice_0]
-    set_property -dict [list CONFIG.DIN_FROM {15}] $pack1_slice_0
-    set_property -dict [list CONFIG.DIN_TO {0}] $pack1_slice_0
-    set_property -dict [list CONFIG.DOUT_WIDTH {16}] $pack1_slice_0
-    set pack1_slice_1 [create_bd_cell -type inline_hdl -vlnv xilinx.com:inline_hdl:ilslice:1.0 pack1_slice_1]
-    set_property -dict [list CONFIG.DIN_FROM {31}] $pack1_slice_1
-    set_property -dict [list CONFIG.DIN_TO {16}] $pack1_slice_1
-    set_property -dict [list CONFIG.DOUT_WIDTH {16}] $pack1_slice_1
-
-    # fir interpolator 0
-    connect_bd_net [get_bd_pins util_ad9361_divclk/clk_out] [get_bd_pins util_fir_int_0/aclk]
-    connect_bd_net [get_bd_pins util_ad9361_dac_upack/enable_0] [get_bd_pins axi_ad9361_dac_fifo/din_enable_0]
-    connect_bd_net [get_bd_pins util_ad9361_dac_upack/enable_1] [get_bd_pins axi_ad9361_dac_fifo/din_enable_1]
-    connect_bd_net [get_bd_pins util_ad9361_dac_upack/fifo_rd_en] [get_bd_pins util_fir_int_0/s_axis_data_tready]
-    connect_bd_net [get_bd_pins util_ad9361_dac_upack/fifo_rd_en] [get_bd_pins util_fir_int_0/s_axis_data_tvalid]
-    connect_bd_net [get_bd_pins axi_ad9361_dac_fifo/din_data_0] [get_bd_pins util_fir_int_0/channel_0]
-    connect_bd_net [get_bd_pins axi_ad9361_dac_fifo/din_data_1] [get_bd_pins util_fir_int_0/channel_1]
-    connect_bd_net [get_bd_pins axi_ad9361_dac_fifo/din_valid_0] [get_bd_pins util_fir_int_0/dac_read]
-    connect_bd_net [get_bd_pins concat_0/In0] [get_bd_pins util_ad9361_dac_upack/fifo_rd_data_0]
-    connect_bd_net [get_bd_pins concat_0/In1] [get_bd_pins util_ad9361_dac_upack/fifo_rd_data_1]
-    connect_bd_net [get_bd_pins concat_0/dout] [get_bd_pins util_fir_int_0/s_axis_data_tdata]
-
-    # fir interpolator 1
-    connect_bd_net [get_bd_pins util_ad9361_divclk/clk_out] [get_bd_pins util_fir_int_1/aclk]
-    connect_bd_net [get_bd_pins util_ad9361_dac_upack/enable_2] [get_bd_pins axi_ad9361_dac_fifo/din_enable_2]
-    connect_bd_net [get_bd_pins util_ad9361_dac_upack/enable_3] [get_bd_pins axi_ad9361_dac_fifo/din_enable_3]
-    connect_bd_net [get_bd_pins util_ad9361_dac_upack/fifo_rd_en] [get_bd_pins util_fir_int_1/s_axis_data_tvalid]
-    connect_bd_net [get_bd_pins axi_ad9361_dac_fifo/din_data_2] [get_bd_pins util_fir_int_1/channel_0]
-    connect_bd_net [get_bd_pins axi_ad9361_dac_fifo/din_data_3] [get_bd_pins util_fir_int_0/channel_1]
-    connect_bd_net [get_bd_pins axi_ad9361_dac_fifo/din_valid_2] [get_bd_pins util_fir_int_1/dac_read]
-    connect_bd_net [get_bd_pins concat_1/In0] [get_bd_pins util_ad9361_dac_upack/fifo_rd_data_2]
-    connect_bd_net [get_bd_pins concat_1/In1] [get_bd_pins util_ad9361_dac_upack/fifo_rd_data_3]
-    connect_bd_net [get_bd_pins concat_1/dout] [get_bd_pins util_fir_int_1/s_axis_data_tdata]
-
-    # gpio controlled
-    connect_bd_net [get_bd_pins axi_ad9361/up_dac_gpio_out] [get_bd_pins interp_slice/Din]
-    connect_bd_net [get_bd_pins util_fir_int_0/interpolate] [get_bd_pins interp_slice/Dout]
-    connect_bd_net [get_bd_pins util_fir_int_1/interpolate] [get_bd_pins interp_slice/Dout]
-
-
-    # fir decimator 0
-    connect_bd_net [get_bd_pins util_ad9361_divclk/clk_out] [get_bd_pins fir_decimator_0/aclk]
-    connect_bd_net [get_bd_pins util_ad9361_adc_fifo/dout_data_0] [get_bd_pins fir_decimator_0/channel_0]
-    connect_bd_net [get_bd_pins util_ad9361_adc_fifo/dout_data_1] [get_bd_pins fir_decimator_0/channel_1]
-    connect_bd_net [get_bd_pins util_ad9361_adc_fifo/dout_valid_0] [get_bd_pins fir_decimator_0/s_axis_data_tvalid]
-    connect_bd_net [get_bd_pins util_ad9361_adc_pack/enable_0 ] [get_bd_pins util_ad9361_adc_fifo/dout_enable_0]
-    connect_bd_net [get_bd_pins util_ad9361_adc_pack/enable_1 ] [get_bd_pins util_ad9361_adc_fifo/dout_enable_1]
-    connect_bd_net [get_bd_pins pack0_slice_0/Din] [get_bd_pins fir_decimator_0/m_axis_data_tdata]
-    connect_bd_net [get_bd_pins pack0_slice_1/Din] [get_bd_pins fir_decimator_0/m_axis_data_tdata]
-    connect_bd_net [get_bd_pins util_ad9361_adc_pack/fifo_wr_data_0] [get_bd_pins pack0_slice_0/Dout]
-    connect_bd_net [get_bd_pins util_ad9361_adc_pack/fifo_wr_data_1] [get_bd_pins pack0_slice_1/Dout]
-
-    # fir decimator 1
-    connect_bd_net [get_bd_pins util_ad9361_divclk/clk_out] [get_bd_pins fir_decimator_1/aclk]
-    connect_bd_net [get_bd_pins util_ad9361_adc_fifo/dout_data_2] [get_bd_pins fir_decimator_1/channel_0]
-    connect_bd_net [get_bd_pins util_ad9361_adc_fifo/dout_data_3] [get_bd_pins fir_decimator_1/channel_1]
-    connect_bd_net [get_bd_pins util_ad9361_adc_fifo/dout_valid_2] [get_bd_pins fir_decimator_1/s_axis_data_tvalid]
-    connect_bd_net [get_bd_pins util_ad9361_adc_pack/fifo_wr_en] [get_bd_pins fir_decimator_1/m_axis_data_tvalid]
-    connect_bd_net [get_bd_pins util_ad9361_adc_pack/enable_2 ] [get_bd_pins util_ad9361_adc_fifo/dout_enable_2]
-    connect_bd_net [get_bd_pins util_ad9361_adc_pack/enable_3 ] [get_bd_pins util_ad9361_adc_fifo/dout_enable_3]
-    connect_bd_net [get_bd_pins pack1_slice_0/Din] [get_bd_pins fir_decimator_1/m_axis_data_tdata]
-    connect_bd_net [get_bd_pins pack1_slice_1/Din] [get_bd_pins fir_decimator_1/m_axis_data_tdata]
-    connect_bd_net [get_bd_pins util_ad9361_adc_pack/fifo_wr_data_2] [get_bd_pins pack1_slice_0/Dout]
-    connect_bd_net [get_bd_pins util_ad9361_adc_pack/fifo_wr_data_3] [get_bd_pins pack1_slice_1/Dout]
-
-    #gpio controlled
-    connect_bd_net [get_bd_pins axi_ad9361/up_dac_gpio_out] [get_bd_pins decim_slice/Din]
-    connect_bd_net [get_bd_pins fir_decimator_0/decimate] [get_bd_pins decim_slice/Dout]
-    connect_bd_net [get_bd_pins fir_decimator_1/decimate] [get_bd_pins decim_slice/Din]