Logo

Getting Started:

  • FireSim Basics
    • Common FireSim usage models
      • 1. Single-Node Simulations Using One or More On-Premises FPGAs
      • 2. Single-Node Simulations Using Cloud FPGAs
      • 3. Datacenter/Cluster Simulations on On-Premises or Cloud FPGAs
    • Other Use Cases
      • Non-Chipyard-based target simulation
    • Choose your platform to get started
  • Background/Terminology

Initial Setup:

  • AWS EC2 F2 System Setup
    • First-time AWS User Setup
      • Creating an AWS Account
      • Requesting Limit Increases
    • Configuring Required Infrastructure in Your AWS Account
      • Select a region
      • Key Setup
      • Double Check your EC2 Instance Limits
      • Start a t2.nano instance to run the remaining configuration commands
      • Run scripts from the t2.nano
      • Terminate the t2.nano
      • Subscribe to the AWS FPGA Developer AMI
    • Setting up your Manager Instance
      • Launching a “Manager Instance”
        • Access your instance
        • Key Setup, Part 2
  • Local FPGA System Setup
    • sudo Setup
    • Non-sudo Setup

Chipyard-based Starter Tutorials:

  • AWS EC2 F2 Getting Started Guide
    • Setting up the FireSim Repo
    • Completing Setup Using the Manager
    • Running FireSim Simulations
      • Running a Single Node Simulation
        • Building target software
        • Setting up the manager configuration
        • Launching a Simulation!
      • Running a Cluster Simulation
        • Building target software
        • Setting up the manager configuration
        • Launching a Simulation!
    • Building Your Own Hardware Designs (FireSim Amazon FPGA Images)
      • Amazon S3 Setup
      • Build Recipes
      • Build Farm Instance Types
      • Running a Build
  • Xilinx Alveo U200 XDMA-based Getting Started Guide
    • FPGA Setup
    • FireSim Repo Setup
      • Setting up the FireSim Repo
      • Initializing FireSim Config Files
      • Configuring the FireSim manager to understand your Run Farm Machine setup
    • Running a Single Node Simulation
      • Building target software
    • Setting up the manager configuration
    • Building and Deploying simulation infrastructure to the Run Farm Machines
    • Running the simulation
    • Building Your Own Hardware Designs
    • System Setup
      • 1. Install Vivado for Builds
      • 2. Verify Build Farm Machine environment
    • Configuring a Build in the Manager
    • Running the Build
  • Xilinx Alveo U250 XDMA-based Getting Started Guide
    • FPGA Setup
    • FireSim Repo Setup
      • Setting up the FireSim Repo
      • Initializing FireSim Config Files
      • Configuring the FireSim manager to understand your Run Farm Machine setup
    • Running a Single Node Simulation
      • Building target software
    • Setting up the manager configuration
    • Building and Deploying simulation infrastructure to the Run Farm Machines
    • Running the simulation
    • Building Your Own Hardware Designs
    • System Setup
      • 1. Install Vivado for Builds
      • 2. Verify Build Farm Machine environment
    • Configuring a Build in the Manager
    • Running the Build
  • Xilinx Alveo U280 XDMA-based Getting Started Guide
    • FPGA Setup
    • FireSim Repo Setup
      • Setting up the FireSim Repo
      • Initializing FireSim Config Files
      • Configuring the FireSim manager to understand your Run Farm Machine setup
    • Running a Single Node Simulation
      • Building target software
    • Setting up the manager configuration
    • Building and Deploying simulation infrastructure to the Run Farm Machines
    • Running the simulation
    • Building Your Own Hardware Designs
    • System Setup
      • 1. Install Vivado for Builds
      • 2. Verify Build Farm Machine environment
    • Configuring a Build in the Manager
    • Running the Build
  • Xilinx VCU118 XDMA-based Getting Started Guide
    • FPGA Setup
    • FireSim Repo Setup
      • Setting up the FireSim Repo
      • Initializing FireSim Config Files
      • Configuring the FireSim manager to understand your Run Farm Machine setup
    • Running a Single Node Simulation
      • Building target software
    • Setting up the manager configuration
    • Building and Deploying simulation infrastructure to the Run Farm Machines
    • Running the simulation
    • Building Your Own Hardware Designs
    • System Setup
      • 1. Install Vivado for Builds
      • 2. Verify Build Farm Machine environment
    • Configuring a Build in the Manager
    • Running the Build
  • RHS Research Nitefury II XDMA-based Getting Started Guide
    • FPGA Setup
    • FireSim Repo Setup
      • Setting up the FireSim Repo
      • Initializing FireSim Config Files
      • Configuring the FireSim manager to understand your Run Farm Machine setup
    • Running a Single Node Simulation
      • Building target software
    • Setting up the manager configuration
    • Building and Deploying simulation infrastructure to the Run Farm Machines
    • Running the simulation
    • Building Your Own Hardware Designs
    • System Setup
      • 1. Install Vivado for Builds
      • 2. Verify Build Farm Machine environment
    • Configuring a Build in the Manager
    • Running the Build
  • (Experimental) Xilinx Alveo U250 Vitis-based Getting Started Guide
    • Initial Setup/Installation
      • FPGA and Tool Setup
        • Requirements and Installations
        • Setup Validation
      • Setting up your On-Premises Machine
        • Setting up the FireSim Repo
        • Completing Setup Using the Manager
    • Running a Single Node Simulation
      • Building target software
    • Setting up the manager configuration
    • Building and Deploying simulation infrastructure to the Run Farm Machines
    • Running the simulation
    • Building Your Own Hardware Designs
    • Configuring a Build in the Manager
    • Running the Build

Advanced Docs:

  • Manager Usage (the firesim command)
    • 1. Overview
      • 1.1. “Inputs” to the Manager
      • 1.2. Logging
    • 2. Manager Command Line Arguments
      • 2.1. --runtimeconfigfile FILENAME
      • 2.2. --buildconfigfile FILENAME
      • 2.3. --buildrecipesconfigfile FILENAME
      • 2.4. --hwdbconfigfile FILENAME
      • 2.5. --overrideconfigdata SECTION PARAMETER VALUE
      • 2.6. --launchtime TIMESTAMP
      • 2.7. TASK
    • 3. Manager Tasks
      • 3.1. firesim managerinit
      • 3.2. firesim buildbitstream
      • 3.3. firesim builddriver
      • 3.4. firesim tar2afi
      • 3.5. firesim shareagfi
      • 3.6. firesim launchrunfarm
      • 3.7. firesim terminaterunfarm
      • 3.8. firesim infrasetup
      • 3.9. firesim boot
      • 3.10. firesim kill
      • 3.11. firesim runworkload
      • 3.12. firesim runcheck
      • 3.13. firesim enumeratefpgas
    • 4. Manager URI Paths
      • 4.1. URI Support
    • 5. Manager Configuration Files
      • 5.1. config_runtime.yaml
        • 5.1.1. run_farm
        • 5.1.2. metasimulation
        • 5.1.3. target_config
        • 5.1.4. tracing
        • 5.1.5. autocounter
        • 5.1.6. workload
        • 5.1.7. host_debug
      • 5.2. config_build.yaml
        • 5.2.1. build_farm
        • 5.2.2. builds_to_run
        • 5.2.3. agfis_to_share
        • 5.2.4. share_with_accounts
      • 5.3. config_build_recipes.yaml
        • 5.3.1. Build definition sections, e.g. awesome_firesim_config
      • 5.4. config_hwdb.yaml
        • 5.4.1. The name: firesim_boom_singlecore_nic_l2_llc4mb_ddr3
        • 5.4.2. Add more hardware config sections, like NAME_GOES_HERE_2
      • 5.5. Run Farm Recipes (run-farm-recipes/*)
        • 5.5.1. run_farm_type
        • 5.5.2. args
        • 5.5.3. aws_ec2.yaml run farm recipe
        • 5.5.4. externally_provisioned.yaml run farm recipe
      • 5.6. Build Farm Recipes (build-farm-recipes/*)
        • 5.6.1. build_farm_type
        • 5.6.2. args
        • 5.6.3. aws_ec2.yaml build farm recipe
        • 5.6.4. externally_provisioned.yaml build farm recipe
      • 5.7. Bit Builder Recipes (bit-builder-recipes/*)
        • 5.7.1. bit_builder_type
        • 5.7.2. args
        • 5.7.3. f1.yaml bit builder recipe
        • 5.7.4. vitis.yaml bit builder recipe
        • 5.7.5. xilinx_alveo_u200.yaml bit builder recipe
        • 5.7.6. xilinx_alveo_u250.yaml bit builder recipe
        • 5.7.7. xilinx_alveo_u280.yaml bit builder recipe
        • 5.7.8. xilinx_vcu118.yaml bit builder recipe
        • 5.7.9. rhsresearch_nitefury_ii.yaml bit builder recipe
    • 6. Manager Environment Variables
      • 6.1. FIRESIM_RUNFARM_PREFIX
      • 6.2. FIRESIM_BUILDFARM_PREFIX
    • 7. Manager Network Topology Definitions (user_topology.py)
      • 7.1. user_topology.py contents:
    • 8. AGFI Metadata/Tagging
  • Workloads
    • FireMarshal
    • [DEPRECATED] Defining Custom Workloads
      • Uniform Workload JSON
      • Non-uniform Workload JSON (explicit job per simulated node)
  • Targets
    • Restrictions on Target RTL
      • Including Verilog IP
      • Multiple Clock Domains
        • The Base Clock
        • Limitations:
    • Target-Side FPGA Constraints
      • RAM Inference Hints
    • Provided Target Designs
      • Target Generator Organization
      • Specifying A Target Instance
    • Rocket Chip Generator-based SoCs (firesim project)
      • Rocket-based SoCs
      • BOOM-based SoCs
      • Generating A Different FASED Memory-Timing Model Instance
    • Midas Examples (midasexamples project)
      • Examples
    • FASED Tests (fasedtests project)
      • Examples
  • Debugging in Software
    • Debugging & Testing with Metasimulation
      • Supported Host Simulators
      • Running Metasimulations using the FireSim Manager
      • Understanding a Metasimulation Waveform
        • Module Hierarchy
        • Clock Edges and Event Timing
        • Finding The Source Of Simulation Stalls
      • Scala Tests
      • Running Metasimulations through Make
        • Examples
      • Metasimulation vs. Target simulation performance
  • Debugging and Profiling on the FPGA
    • Capturing RISC-V Instruction Traces with TracerV
      • Building a Design with TracerV
      • Enabling Tracing at Runtime
      • Selecting a Trace Output Format
      • Setting a TracerV Trigger
        • No trigger
        • Target cycle trigger
        • Program Counter (PC) value trigger
        • Instruction value trigger
      • Interpreting the Trace Result
        • Human readable output
        • Binary output
        • Flame Graph output
      • Caveats
    • Assertion Synthesis: Catching RTL Assertions on the FPGA
      • Enabling Assertion Synthesis
      • Runtime Behavior
      • Related Publications
    • Printf Synthesis: Capturing RTL printf Calls when Running on the FPGA
      • Enabling Printf Synthesis
      • Runtime Arguments
      • Related Publications
    • AutoILA: Simple Integrated Logic Analyzer (ILA) Insertion
      • Enabling AutoILA
      • Annotating Signals
      • Setting a ILA Depth
      • Using the ILA at Runtime
    • AutoCounter: Profiling with Out-of-Band Performance Counter Collection
      • Chisel Interface
      • Enabling AutoCounter in Golden Gate
      • Rocket Chip Cover Functions
      • AutoCounter Runtime Parameters
      • AutoCounter CSV Output Format
      • Using TracerV Trigger with AutoCounter
      • AutoCounter using Synthesizable Printfs
      • Reset & Timing Considerations
    • TracerV + Flame Graphs: Profiling Software with Out-of-Band Flame Graph Generation
      • What are Flame Graphs?
      • Prerequisites
      • Enabling Flame Graph generation in config_runtime.yaml
      • Producing DWARF information to supply to the TracerV driver
      • Modifying your workload description
      • Running a simulation
      • Caveats
    • Spike Co-simulation with BOOM designs
      • Building a Design with Cospike
      • Troubleshooting Cospike Simulations with Meta-Simulations
    • Debugging a Hanging Simulator
      • Case 1: Target hang.
      • Case 2: Simulator hang due to FPGA-side token starvation.
      • Case 3: Simulator hang due to driver-side deadlock.
      • Simulator Heartbeat PlusArgs
    • PlusArg Synthesis: Runtime Modification of RTL
      • Enabling PlusArg Synthesis
      • Runtime Arguments
  • Non-Source Dependency Management
    • Updating a Package Version
    • Multiple Environments
    • Adding a New Dependency
    • Building From Source
    • Running Conda with sudo
    • Running things from your Conda environment with sudo
    • Additional Resources
  • Supernode - Multiple Simulated SoCs Per FPGA
    • Introduction
    • Building Supernode Designs
    • Running Supernode Simulations
    • Work in Progress!
  • FireAxe - Partitioning onto Multiple FPGAs
    • FireAxe Overview
    • Partition Modes
      • Exact-Mode
      • Fast-Mode
      • NoC-Partition-Mode
    • Supported Platforms
      • EC2 F1
      • Local FPGAs w/ QSFP Cables
    • Running Fast Mode Simulations
      • 1. Building Partitioned Sims: Setting up FireAxe Target configs
      • 2. Building Partitioned Sims: config_build_recipes.yaml
      • 3. Running Partitioned Simulations: user_topology.py
      • 4. Running Partitioned Simulations: config_runtime.yaml
    • Running Exact Mode Simulations
      • 1. Building Partitioned Sims: Setting up FireAxe Target configs
      • 2. Building Partitioned Sims: config_build_recipes.yaml
      • 3. Running Partitioned Simulations: user_topology.py
      • 4. Running Partitioned Simulations: config_runtime.yaml
    • Running NoC Partition Mode Simulations
      • 1. Building Partitioned Sims: Setting up FireAxe Target configs
      • 2. Building Partitioned Sims: config_build_recipes.yaml
      • 3. Running Partitioned Simulations: user_topology.py
      • 4. Running Partitioned Simulations: config_runtime.yaml
    • Miscellaneous Tips
      • Running FireAxe Metasims
  • Miscellaneous Tips
    • Add the fsimcluster column to your AWS management console
    • FPGA Dev AMI Remote Desktop Setup
    • Experimental Support for SSHing into simulated nodes and accessing the internet from within simulations
    • Navigating the FireSim Codebase
    • Using FireSim CI
    • How to view AWS build logs when AGFI build fails
  • Adding support for a new FPGA
    • Adding a new FireSim platform
    • Adding other collateral (Scala, C++, Make, etc)
    • Manager build modifications
    • Manager run modifications
  • Using FireSim without Chipyard
    • Simple Counter Example Project
      • Top-Level Harness
      • C++ Driver Top
      • Make fragments
      • Running meta-simulations and more
    • Chipyard Example
      • Top-Level Harness
      • C++ Driver Top
      • Make fragments
  • FireSim Asked Questions
    • I just bumped the FireSim repository to a newer commit and simulations aren’t running. What is going on?
    • Is there a good way to keep track of what AGFI corresponds to what FireSim commit?
    • Help, My Simulation Hangs!
    • Should My Simulator Produce Different Results Across Runs?
    • Is there a way to compress workload results when copying back to the manager instance?

Compiler (Golden Gate) Docs:

  • Overview & Philosophy
    • Golden Gate vs FPGA Prototyping
    • Why Use Golden Gate & FireSim
    • Why Not Golden Gate
    • How is Host-Decoupling Implemented?
  • Target Abstraction & Host Decoupling
    • The Target as a Dataflow Graph
    • Model Implementations
    • Expressing the Target Graph
    • Latency-Insensitive Bounded Dataflow Networks
  • Target-to-Host Bridges
    • Terminology
    • Target Side
      • Type Parameters:
      • Abstract Members:
    • What Happens Next?
    • Host Side
    • Compile-Time (Parameterization) vs Runtime Configuration
    • Target-Side vs Host-Side Parameterization
  • Bridge Deep Dive
    • UART Bridge (Host-MMIO)
      • Target Side
      • Host-Side BridgeModule
      • Host-Side Driver
      • Build-System Modifications
  • Simulation Triggers
    • Quick-Start Guide
      • Level-Sensitive Trigger Source
      • Distributed, Edge-Sensitive Trigger Source
    • Chisel API
      • Trigger Sources
      • Trigger Sinks
    • Trigger Timing
    • Limitations & Pitfalls
  • Optimizing FPGA Resource Utilization
    • Multi-Ported Memory Optimization
    • Multi-Threading of Repeated Instances
  • Output Files
    • Core Files
    • FPGA Build Files
    • Metasimulation Files

Developer Docs:

  • Compiler & Driver Development
    • Integration Tests
      • Key Files & Locations
      • Defining a New Test
    • Synthesizable Unit Tests
      • Key Files & Locations
      • Defining a New Test
    • Scala Unit Testing
      • Key Files & Locations
      • Defining A New Test
    • C/C++ guidelines
    • Scala guidelines
  • Complete FPGA Metasimulation
    • Usage
  • Visual Studio Code Integration
    • General Setup
    • Workspace Locations
    • Scala Development
      • How To Use (Remote Manager)
      • Limitations
      • Other Notes
  • Managing the Conda Lock File
    • Updating Conda Requirements
    • Caveats of the Conda Lock File and CI
  • Manager Development

Miscellaneous:

  • External Tutorial Setup
FireSim
  • Workloads
  • View page source

Workloads

This section describes workload definitions in FireSim.

Workloads:

  • FireMarshal
  • [DEPRECATED] Defining Custom Workloads
    • Uniform Workload JSON
    • Non-uniform Workload JSON (explicit job per simulated node)
Previous Next

© Copyright 2018-2026 Sagar Karandikar, David Biancolin, Abraham Gonzalez, Howard Mao, Donggyu Kim, Alon Amid, and Berkeley Architecture Research.

Built with Sphinx using a theme provided by Read the Docs.