Building Your Own Hardware Designs

This section will guide you through building a Xilinx VCU118 FPGA bitstream to run FireSim simulations.

System Setup

Here, we’ll do some final one-time setup for your Build Farm Machines so that we can build bitstreams for FireSim simulations automatically.

These steps assume that you have already followed the earlier setup steps required to run simulations.

As noted earlier, it is highly recommended that you use Ubuntu 20.04 LTS as the host operating system for all machine types in an on-premises setup, as this is the OS recommended by Xilinx.

Also recall that we make a distinction between the Manager Machine, the Build Farm Machine(s), and the Run Farm Machine(s). In a simple setup, these can all be a single machine, in which case you should run the Build Farm Machine setup steps below on your single machine.

1. Install Vivado for Builds

Machines: Build Farm Machines.

Running builds for Xilinx VCU118 in FireSim requires Vivado 2023.1. Other versions are unlikely to work out-of-the-box.

On each Build Farm machine, do the following:

  1. Install Vivado 2023.1 from the Xilinx Downloads Website. By default, Vivado will be installed to /tools/Xilinx/Vivado/2023.1. We recommend keeping this default. If you change it to something else, you will need to adjust the path in the rest of the setup steps.

  2. Add the following to ~/.bashrc so that vivado is available when ssh-ing into the machine:

source /tools/Xilinx/Vivado/2023.1/settings64.sh

  1. No special board support package is required for the VCU118. Move on to the next step.

If you have multiple Build Farm Machines, you should repeat this process for each.

2. Verify Build Farm Machine environment

Machines: Manager Machine and Run Farm Machines

Finally, let’s ensure that Vivado 2023.1 is properly sourced in your shell setup (i.e. .bashrc) so that any shell on your Build Farm Machines can use the corresponding programs. The environment variables should be visible to any non-interactive shells that are spawned.

You can check this by running the following on the Manager Machine, replacing BUILD_FARM_IP with localhost if your Build Farm machine and Manager machine are the same machine, or replacing it with the Build Farm machine’s IP address if they are different machines.

ssh BUILD_FARM_IP printenv

Ensure that the output of the command shows that the Vivado 2023.1 tools are present in the printed environment variables (i.e., PATH and XILINX_VIVADO).

If you have multiple Build Farm machines, you should repeat this process for each Build Farm machine, replacing BUILD_FARM_IP with a different Build Farm Machine’s IP address.

Configuring a Build in the Manager

In the deploy/config_build.yaml file, you will notice that the builds_to_run section currently contains several lines, which indicates to the build system that you want to run all of these “build recipes” in parallel, with the parameters for each “build recipe” listed in the relevant section of the deploy/config_build_recipes.yaml file (or in the case of building a Chipyard target SoC in :cy-gh-file-ref:`sims/firesim-staging/sample_config_build_recipes.yaml`).

In this guide, we’ll build the default FireSim design for the Xilinx VCU118, which is specified by the xilinx_vcu118_firesim_rocket_singlecore_4GB_no_nic section in :cy-gh-file-ref:`sims/firesim-staging/sample_config_build_recipes.yaml`. This was the same configuration used to build the pre-built bitstream that you used to run simulations in the guide to running a simulation.

Looking at the xilinx_vcu118_firesim_rocket_singlecore_4GB_no_nic section in :cy-gh-file-ref:`sims/firesim-staging/sample_config_build_recipes.yaml`, there are a few notable items:

  • TARGET_CONFIG specifies that this configuration is a simple singlecore RISC-V Rocket with a single DRAM channel.

  • TARGET_PROJECT_MAKEFRAG specifies to the FireSim Make system how to build the TARGET_CONFIG.

  • bit_builder_recipe points to bit-builder-recipes/xilinx_vcu118.yaml, which is found in the :gh-file-ref:`deploy` directory and tells the FireSim build system how to build bitstreams for this FPGA.

Having looked at this entry, let’s now set up the build in deploy/config_build.yaml. First, we’ll set up the build_farm mapping, which specifies the Build Farm Machines that are available to build FPGA bitstreams.

  • base_recipe will map to build-farm-recipes/externally_provisioned.yaml. This indicates to the FireSim manager that the machines used to run builds are existing machines that have been set up by the user, instead of cloud instances that are automatically provisioned.

  • default_build_dir is the directory in which builds will run out of on your Build Farm Machines. Change the default null to a path where you would like temporary build data to be stored on your Build Farm Machines.

  • build_farm_hosts is a section that contains a list of IP addresses or hostnames of machines in your Build Farm. By default, localhost is specified. If you are using a separate Build Farm Machine, you should replace this with the IP address or hostname of the Build Farm Machine on which you would like to run the build.

Having configured our Build Farm, let’s specify the design we’d like to build. To do this, edit the builds_to_run section in deploy/config_build.yaml so that it looks like the following:

builds_to_run:
    - xilinx_vcu118_firesim_rocket_singlecore_4GB_no_nic

In essence, you should delete or comment out all the other items in the builds_to_run section besides xilinx_vcu118_firesim_rocket_singlecore_4GB_no_nic.

Running the Build

Now, we can run a build like so (while also pointing to Chipyard’s recipes provided):

firesim buildbitstream -r -r ${CY_DIR}/sims/firesim-staging/sample_config_build_recipes.yaml

This will run through the entire build process, taking the Chisel (or Verilog) RTL and producing a bitstream that runs on the Xilinx VCU118 FPGA. This whole process will usually take a few hours. When the build completes, you will see a directory in deploy/results-build/, named after your build parameter settings, that contains all of the outputs of the Xilinx Vivado build process. Additionally, the manager will print out a path to a log file that describes everything that happened, in-detail, during this run (this is a good file to send us if you encounter problems).

The manager will also print an entry that can be added to config_hwdb.yaml so that the bitstream can be used to run simulations. This entry will contain a bitstream_tar key whose value is the path to the final generated bitstream file. You can share generated bitstreams with others by sharing the file listed in bitstream_tar and the config_hwdb.yaml entry for it.

Now that you know how to generate your own FPGA image, you can modify the target-design to add your own features, then build a FireSim-compatible FPGA image automatically!

This is the end of the Getting Started Guide. To learn more advanced FireSim features, you can choose a link under the “Advanced Docs” section to the left.