Merge pull request #1397 from firesim/update-vitis-docs

Update Vitis docs | Bump FPGA platform to 2022.1

deploy/bit-builder-recipes/vitis.yaml

@@ -15,4 +15,4 @@
 bit_builder_type: VitisBitBuilder
 args:
     # REQUIRED: vitis fpga platform
-    device: xilinx_u250_gen3x16_xdma_3_1_202020_1
+    device: xilinx_u250_gen3x16_xdma_4_1_202210_1

docs/Advanced-Usage/Vitis.rst

@@ -10,9 +10,19 @@ Setup
 
 First, install and setup Vitis/Vivado/XRT to use the U250.
 
-* Install Vitis/Vivado 2021.1 (refer to the Xilinx website for the installers)
-* **Important** Build and install XRT manually based off the following commit: https://github.com/Xilinx/XRT/commit/63269b8d4aa04099459c68b283f8512748fb39d6
-* Install the U250 board package
+* Install Vitis/Vivado 2021 or higher (refer to the Xilinx website for the installers)
+* Install XRT depending on the version of Vitis/Vivado (**IMPORTANT**)
+    * Vitis/Vivado 2021.x: build and install XRT manually based off the following commit: https://github.com/Xilinx/XRT/commit/63269b8d4aa04099459c68b283f8512748fb39d6
+    * Vitis/Vivado 2022.x: install XRT normally (refer to the Xilinx website for the installer)
+* Install the U250 board package corresponding to the Vitis/Vivado/XRT version (refer to the Xilinx website for the installers)
+
+Verify that the U250 FPGA can be used for emulations.
+Ensure that you can run the XRT specific command without errors: ``xbutil validate --device <CARD_BDF_INSTALLED> --verbose``
+
+.. Warning:: Anytime the host computer is rebooted you may need to re-run parts of the setup process (i.e. reflash the shell).
+     Before continuing to FireSim simulations after a host computer reboot, ensure that the previously mentioned ``xbutil`` command is successful.
+
+.. Note:: The rest of this documentation assumes you are using Vitis/Vivado/XRT 2022.1
 
 Next, setup the FireSim repository.
 
@@ -37,13 +47,17 @@ Bitstream Build
         PLATFORM_CONFIG: BaseVitisConfig
         deploy_triplet: null
         platform_config_args:
-            fpga_frequency: null
-            build_strategy: null
+            fpga_frequency: 140
+            build_strategy: TIMING
         post_build_hook: null
         metasim_customruntimeconfig: null
         bit_builder_recipe: bit-builder-recipes/vitis.yaml
 
-2. Modify the ``config_build.yaml`` to the following (leaving other sections intact). Note that you
+2. If necessary, you can change the FPGA to build for (otherwise known as the "platform" or "device")
+   by modifying the ``device`` in ``deploy/bit-builder-recipes``. By default this is set to
+   ``xilinx_u250_gen3x16_xdma_4_1_202210_1`` (corresponding to the 2022.1 FPGA installation files).
+
+3. Modify the ``config_build.yaml`` to the following (leaving other sections intact). Note that you
    should modify ``default_build_dir`` appropriately. This sets up running builds locally using the
    externally provisioned build farm.
 
@@ -57,9 +71,9 @@ Bitstream Build
     builds_to_run:
         - firesim_rocket_singlecore_no_nic
 
-3. Run ``firesim buildbitstream``
+4. Run ``firesim buildbitstream``
 
-4. If successful, you should see a ``firesim_rocket_singlecore_no_nic`` HWDB entry in ``deploy/build-hwdb-entries/``.
+5. If successful, you should see a ``firesim_rocket_singlecore_no_nic`` HWDB entry in ``deploy/build-hwdb-entries/``.
    It should look something like this:
 
 ::
@@ -70,14 +84,15 @@ Bitstream Build
         custom_runtime_config: null
 
 .. Note:: If for some reason the ``buildbitstream`` failed, you can download a pre-built ``xclbin`` here:
-   https://people.eecs.berkeley.edu/~abe.gonzalez/firesim_rocket_singlecore_no_nic.xclbin.
+   https://firesim-ci-vitis-xclbins.s3.us-west-2.amazonaws.com/firesim_rocket_singlecore_no_nic_9e1a21.xclbin
 
 Running A Simulation
 --------------------
 
 1. Modify the ``config_runtime.yaml`` to the following (leaving other sections intact). Note that you
    should modify ``default_simulation_dir`` appropriately. This sets up running simulations locally using the
-   externally provisioned run farm.
+   externally provisioned run farm. This also assumes that the host machine only has access to one FPGA (change
+   the ``run_farm_host_specs`` to target a machine with multiple FPGAs).
 
 ::