Welcome to FireSim’s documentation (version “1.15.0”)!

New to FireSim? Jump to the FireSim Basics page for more info.

Getting Started:

• FireSim Basics
  • Three common use cases:
    • Single-Node Simulation In Parallel Using On-Premise FPGAs
    • Single-Node Simulation In Parallel Using Cloud FPGAs
    • Datacenter/Cluster Simulation
  • Other Use Cases
  • Background/Terminology
  • Using FireSim/The FireSim Workflow

AWS EC2 F1 Tutorial:

• 1. Initial Setup/Installation
  • 1.1. First-time AWS User Setup
    • 1.1.1. Creating an AWS Account
    • 1.1.2. AWS Credit at Berkeley
    • 1.1.3. Requesting Limit Increases
  • 1.2. Configuring Required Infrastructure in Your AWS Account
    • 1.2.1. Select a region
    • 1.2.2. Key Setup
    • 1.2.3. Check your EC2 Instance Limits
    • 1.2.4. Start a t2.nano instance to run the remaining configuration commands
    • 1.2.5. Run scripts from the t2.nano
    • 1.2.6. Terminate the t2.nano
    • 1.2.7. Subscribe to the AWS FPGA Developer AMI
  • 1.3. Setting up your Manager Instance
    • 1.3.1. Launching a “Manager Instance”
    • 1.3.2. Setting up the FireSim Repo
    • 1.3.3. Completing Setup Using the Manager
• 2. Running FireSim Simulations
  • 2.1. Running a Single Node Simulation
    • 2.1.1. Building target software
    • 2.1.2. Setting up the manager configuration
    • 2.1.3. Launching a Simulation!
  • 2.2. Running a Cluster Simulation
    • 2.2.1. Returning to a clean configuration
    • 2.2.2. Building target software
    • 2.2.3. Setting up the manager configuration
    • 2.2.4. Launching a Simulation!
• 3. Building Your Own Hardware Designs (FireSim FPGA Images)
  • 3.1. Amazon S3 Setup
  • 3.2. Build Recipes
  • 3.3. Running a 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 --platform {f1,vitis}
    • 3.2. firesim buildafi
    • 3.3. firesim buildbitstream
    • 3.4. firesim builddriver
    • 3.5. firesim tar2afi
    • 3.6. firesim shareagfi
    • 3.7. firesim launchrunfarm
    • 3.8. firesim terminaterunfarm
    • 3.9. firesim infrasetup
    • 3.10. firesim boot
    • 3.11. firesim kill
    • 3.12. firesim runworkload
    • 3.13. firesim runcheck
  • 4. Manager Configuration Files
    • 4.1. config_runtime.yaml
    • 4.2. config_build.yaml
    • 4.3. config_build_recipes.yaml
    • 4.4. config_hwdb.yaml
    • 4.5. Run Farm Recipes (run-farm-recipes/*)
    • 4.6. Build Farm Recipes (build-farm-recipes/*)
    • 4.7. Bit Builder Recipes (bit-builder-recipes/*)
  • 5. Manager Environment Variables
    • 5.1. FIRESIM_RUNFARM_PREFIX
  • 6. Manager Network Topology Definitions (user_topology.py)
    • 6.1. user_topology.py contents:
  • 7. AGFI Metadata/Tagging
• Workloads
  • Defining Custom Workloads
    • Uniform Workload JSON
    • Non-uniform Workload JSON (explicit job per simulated node)
  • FireMarshal
  • SPEC 2017
  • Running Fedora on FireSim
  • ISCA 2018 Experiments
    • Prerequisites
    • Building Benchmark Binaries/Rootfses
    • Figure 5: Ping Latency vs. Configured Link Latency
    • Figure 6: Network Bandwidth Saturation
    • Figure 7: Memcached QoS / Thread Imbalance
    • Figure 8: Simulation Rate vs. Scale
    • Figure 9: Simulation Rate vs. Link Latency
    • Running all experiments at once
  • GAP Benchmark Suite
  • [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
  • 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
    • Scala Tests
    • Running Metasimulations through Make
    • 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
    • Interpreting the Trace Result
    • 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
  • Dromajo Co-simulation with BOOM designs
    • Building a Design with Dromajo
    • Running a FireSim Simulation
    • Troubleshooting Dromajo 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
• 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!
• 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
• 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?
• (Experimental) Using On Premise FPGAs
  • Setup
  • Bitstream Build
  • Running A Simulation

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 Walkthrough
  • UART Bridge (Host-MMIO)
    • Target Side
    • Host-Side BridgeModule
    • Host-Side Driver
    • Registering the 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
• 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

Miscellaneous:

• External Tutorial Setup

Indices and tables

• Index

• Module Index

• Search Page