Add MCS documentation + MCS generation to all U250 builds

deploy/buildtools/bitbuilder.py

@@ -665,6 +665,7 @@ class XilinxAlveoBitBuilder(BitBuilder):
         hwdb_entry_name = self.build_config.name
         local_cl_dir = f"{local_results_dir}/{fpga_build_postfix}"
         bit_path = f"{local_cl_dir}/vivado_proj/firesim.bit"
+        mcs_path = f"{local_cl_dir}/vivado_proj/firesim.mcs"
         tar_staging_path = f"{local_cl_dir}/{self.build_config.PLATFORM}"
         tar_name = "firesim.tar.gz"
 
@@ -672,8 +673,9 @@ class XilinxAlveoBitBuilder(BitBuilder):
         local(f"rm -rf {tar_staging_path}")
         local(f"mkdir -p {tar_staging_path}")
 
-        # store bitfile
+        # store bitfile/mcs
         local(f"cp {bit_path} {tar_staging_path}")
+        local(f"cp {mcs_path} {tar_staging_path}")
 
         # store metadata string
         local(f"""echo '{self.get_metadata_string()}' >> {tar_staging_path}/metadata""")
@@ -770,4 +772,3 @@ class XilinxVCU118BitBuilder(XilinxAlveoBitBuilder):
         rootLogger.debug(rsync_cap.stderr)
 
         return f"{dest_alveo_dir}/{fpga_build_postfix}"
-

docs/Getting-Started-Guides/On-Premises-FPGA-Tutorial/FPGA-Setup/Xilinx-Alveo-Template-Part2.rst

@@ -9,10 +9,10 @@ FPGA Setup
 
 .. Warning:: Power-users can skip this setup and just create the database file listed below by hand if you want to target specific fpgas.
 
-We need to flash the |fpga_name| FPGA(s) with a dummy XDMA-enabled design and determine the PCI-e ID (or BDF) associated with the serial number of the FPGA.
-First, we need to flash the FPGA's with the dummy XDMA-enabled design so that the PCI-e subsystem can be initially configured.
-Afterwards, we will generate the mapping from FPGA serial number to BDF.
-We provide a a set of scripts to do this.
+We need to flash the |fpga_name| FPGA(s) SPI flash with a dummy XDMA-enabled design and determine the PCI-e ID (or BDF) associated with the serial number of the FPGA.
+First, we need to flash the FPGA's SPI flash with the dummy XDMA-enabled design so that the PCI-e subsystem can be initially configured.
+Afterwards, we will generate the mapping from FPGA serial numbers to BDFs.
+We provide a set of scripts to do this.
 
 First lets obtain the sample bitstream, let's find the URL to download the file to the machine with the FPGA.
 Below find the HWDB entry called |hwdb_entry_name|.
@@ -24,25 +24,25 @@ Below find the HWDB entry called |hwdb_entry_name|.
 
 Look for the ``bitstream_tar: <URL>`` line within |hwdb_entry_name| and keep note of the URL.
 We will replace the ``BITSTREAM_TAR`` bash variable below with that URL.
-
-Next, lets flash all FPGAs in the system with the dummy bitstream.
+Next, lets unpack the ``tar`` archive and obtain the ``mcs`` file used to program the FPGA SPI flash.
 
 .. code-block:: bash
    :substitutions:
 
-   # enter the firesim directory checked out
-   cd firesim
+   # unpack the file in any area
+   cd ~
 
-   cd platforms/|platform_name|/scripts
-
-   vivado -mode tcl -source get_serial_dev_for_fpgas.tcl
-   # get the UID/serial number's from this script
-
-   BITSTREAM_TAR=<# replace me!>
+   BITSTREAM_TAR=<URL FROM BEFORE>
    tar xvf $BITSTREAM_TAR
-   ./fpga-util.py --serial $SERIAL_NO |platform_name|/*.bit
 
-Next, **warm reboot** the computer.
+   ls |platform_name|
+
+You should see a ``mcs`` file use to program the SPI flash of the FPGA.
+Next, lets flash the SPI flash modules of each |fpga_name| in the system with the dummy bitstream.
+Open Xilinx Vivado (or Vivado Lab), connect to each FPGA and program the SPI flash.
+You can refer to https://www.fpgadeveloper.com/how-to-program-configuration-flash-with-vivado-hardware-manager/ for examples on how to do this for various boards.
+
+Next, **cold reboot** the computer.
 This will reconfigure your PCI-E settings such that FireSim can detect the XDMA-enabled bitstream.
 After the machine is rebooted, you may need to re-insert the XDMA kernel module.
 Then verify that you can see the XDMA module with:
@@ -62,9 +62,11 @@ For example, we should see ``Serial controller`` for BDF's that were flashed.
    04:00.0 Serial controller: Xilinx Corporation Device 903f (rev ff)
    83:00.0 Serial controller: Xilinx Corporation Device 903f (rev ff)
 
+If you don't see similar output, you might need to **warm reboot** your machine until you see the output.
+
 .. Warning:: Anytime the host computer is rebooted you may need to re-run parts of the setup process (i.e. re-insert XDMA kernel module).
      Before continuing to FireSim simulations after a host computer reboot, ensure that ``cat /proc/devices | grep xdma`` command is successful.
-     Also ensure that you see ``Serial controller`` for the BDF of the FPGA you would like to use in ``lspci | grep -i xilinx`` (otherwise, re-run this setup).
+     Also ensure that you see ``Serial controller`` for the BDF of the FPGA you would like to use in ``lspci | grep -i xilinx``.
 
 Next, let's generate the mapping from FPGA serial numbers to the BDF.
 Re-enter the FireSim repository and run the following commands to re-setup the repo after reboot.

docs/Getting-Started-Guides/On-Premises-FPGA-Tutorial/FPGA-Setup/Xilinx-Alveo-Template.rst

@@ -49,7 +49,7 @@ Verify that you can see the XDMA module with:
 
 .. code-block:: bash
 
-   lsmod | grep -wq xdma
+   lsmod | grep -i xdma
 
 .. warning:: After the machine is rebooted, you may need to re-insert the XDMA kernel module.
 

platforms/xilinx_alveo_u250/cl_firesim/scripts/implementation_2022.2.tcl

@@ -71,5 +71,6 @@ if {$WNS >= 0 && $WHS >= 0} {
   }
 }
 
-
 file copy -force ${root_dir}/vivado_proj/firesim.runs/${impl_run}/design_1_wrapper.bit ${root_dir}/vivado_proj/firesim.bit
+
+write_cfgmem -format mcs -interface SPIx1 -size 1024 -loadbit "up 0x01002000 ${root_dir}/vivado_proj/firesim.bit" -verbose  ${root_dir}/vivado_proj/firesim.mcs

platforms/xilinx_alveo_u250/cl_firesim/scripts/implementation_easy.tcl

@@ -28,3 +28,5 @@ if {[get_property PROGRESS ${impl_run}] != "100%"} {
 }
 
 file copy -force ${root_dir}/vivado_proj/firesim.runs/${impl_run}/design_1_wrapper.bit ${root_dir}/vivado_proj/firesim.bit
+
+write_cfgmem -format mcs -interface SPIx1 -size 1024 -loadbit "up 0x01002000 ${root_dir}/vivado_proj/firesim.bit" -verbose  ${root_dir}/vivado_proj/firesim.mcs

platforms/xilinx_alveo_u250/cl_firesim/scripts/implementation_idr_2022.2.tcl

@@ -71,5 +71,6 @@ if {$WNS >= 0 && $WHS >= 0} {
   }
 }
 
-
 file copy -force ${root_dir}/vivado_proj/firesim.runs/${impl_run}/design_1_wrapper.bit ${root_dir}/vivado_proj/firesim.bit
+
+write_cfgmem -format mcs -interface SPIx1 -size 1024 -loadbit "up 0x01002000 ${root_dir}/vivado_proj/firesim.bit" -verbose  ${root_dir}/vivado_proj/firesim.mcs

platforms/xilinx_alveo_u250/cl_firesim/scripts/implementation_ml_2021.1.tcl

@@ -116,3 +116,5 @@ if {[get_property PROGRESS [get_runs ${impl_run}]] != "100%"} {
 }
 
 file copy -force ${root_dir}/vivado_proj/firesim.runs/${impl_run}/design_1_wrapper.bit ${root_dir}/vivado_proj/firesim.bit
+
+write_cfgmem -format mcs -interface SPIx1 -size 1024 -loadbit "up 0x01002000 ${root_dir}/vivado_proj/firesim.bit" -verbose  ${root_dir}/vivado_proj/firesim.mcs