Targets¶
FireSim generates SoC models by transforming RTL emitted by a Chisel generator, such as the Rocket SoC generator. Subject to conditions outlined in Restrictions on Target RTL, if it can be generated by Chisel, it can be simulated in FireSim.
Restrictions on Target RTL¶
Current limitations in Golden Gate place the following restrictions on the (FIR)RTL that can be transformed and thus used in FireSim:
- The RTL must not contain multiple clock domains.
- Black boxes must be “clock-gateable” by replacing its input clock with a gated equivalent.
- Asynchronous reset must only be implemented using Rocket Chip’s black box async reset. These are replaced with synchronously reset registers using a FIRRTL transformation.
Including Verilog IP¶
FireSim now supports target designs that incorporate Verilog IP using the standard BlackBox
interface from Chisel. For an
example of how to add Verilog IP to a target system based on Rocket Chip, see the Incorporating
Verilog Blocks
section of the Chipyard documentation.
- For the transform to work, the Chisel Blackbox that wraps the Verilog IP must have a single clock input that can safely be clock-gated.
- The compiler that produces the decoupled simulator (“FAME Transform”) automatically recognizes such blackboxes inside the target design.
- The compiler automatically gates the clock to the Verilog IP to ensure that it deterministically advances in lockstep with the rest of the simulator.
- This allows any Verilog module with a single clock input to be instantiated anywhere in the target design using the standard Chisel Blackbox interface.
Provided Target Designs¶
Target Generator Organization¶
FireSim provides multiple projects, each for a different type of target. Each
project has its own chisel generator that invokes Golden Gate, its own driver
sources, and a makefrag that plugs into the Make-based build system that
resides in sim/
. These projects are:
- firesim (Default): rocket chip-based targets. These include targets with either BOOM or rocket pipelines, and should be your starting point if you’re building an SoC with the Rocket Chip generator.
- midasexamples: the Golden Gate example designs, a set of simple chisel circuits like GCD, that demonstrate how to use Golden Gate. These are useful test cases for bringing up new Golden Gate features.
- fasedtests: designs to do integration testing of FASED memory-system timing models.
Projects have the following directory structure:
sim/
├-Makefile # Top-level makefile for projects where FireSim is the top-level repo
├-Makefrag # Target-agnostic makefrag, with recipes to generate drivers and RTL simulators
├-src/main/scala/{target-project}/
│ └─Makefrag # Defines target-specific make variables and recipes.
├-src/main/cc/{target-project}/
│ ├─{driver-csrcs}.cc # The target's simulation driver, and sofware-model sources
│ └─{driver-headers}.h
└-src/main/makefrag/{target-project}/
├─Generator.scala # Contains the main class that generates target RTL and calls Golden Gate
└─{other-scala-sources}.scala
Specifying A Target Instance¶
To generate a specific instance of a target, the build system leverages four Make variables:
TARGET_PROJECT
: this points the Makefile (sim/Makefile) at the right target-specific Makefrag, which defines the generation and MIDAS-level software-simulation recipes. The makefrag for the default target project is defined atsim/src/main/makefrag/firesim
.DESIGN
: the name of the top-level Chisel module to generate (a Scala class name). These are defined in FireChip Chipyard generator.TARGET_CONFIG
: specifies aConfig
instance that is consumed by the target design’s generator. For the default firesim target project, predefined configs are described in in the FireChip Chipyard generator.PLATFORM_CONFIG
: specifies aConfig
instance that is consumed by Golden Gate and specifies compiler-level and host-land parameters, such as whether to enable assertion synthesis, or multi-ported RAM optimizations. Common platform configs are described infiresim-lib/sim/src/main/scala/configs/CompilerConfigs.scala
).
TARGET_CONFIG
and PLATFORM_CONFIG
are strings that are used to construct a
Config
instance (derives from RocketChip’s parameterization system, Config
, see
freechips.rocketchip.config). These strings are of the form
“{…_}{<Class Name>_}<Class Name>”. Only the final, base class name is
compulsory: class names that are prepended with “_” are used to create a
compound Config instance.
// Specify by setting TARGET_CONFIG=Base
class Base extends Config((site, here, up) => {...})
class Override1 extends Config((site, here, up) => {...})
class Override2 extends Config((site, here, up) => {...})
// Specify by setting TARGET_CONFIG=Compound
class Compound extends Config(new Override2 ++ new Override1 ++ new Base)
// OR by setting TARGET_CONFIG=Override2_Override1_Base
// Can specify undefined classes this way. ex: TARGET_CONFIG=Override2_Base
With this scheme, you don’t need to define a Config class for every instance you wish to generate. We use this scheme to specify FPGA frequencies (eg. “BaseF1Config_F90MHz”) in manager build recipes, but it’s also very useful for doing sweeping over a parameterization space.
Note that the precedence of Configs decreases from left to right in a string. Appending a config to an existing one will only have an effect if it
sets a field not already set in higher precendence Configs. For example, “BaseF1Config_F90MHz” is equivalent to
“BaseF1Config_F90MHz_F80MHz” as DesiredHostFrequency
resolves to 90 MHz,
but “F90MHz_BaseF1Config” is distinct from “F80MHz_F90MHz_BaseF1Config” in
that DesiredHostFrequency
resolves to 90 and 80 MHz respectively.
How a particular Config resolves it’s Field
s can be unintuitive for complex
compound Config
s. One precise way to check a config is doing what you
expect is to open the scala REPL, instantiate an instance of the desired
Config
, and inspect its fields.
$ make sbt # Launch into SBT's shell with extra FireSim arguments
sbt:firechip> console # Launch the REPL
scala> val inst = (new firesim.firesim.FireSimRocketChipConfig).toInstance # Make an instance
inst: freechips.rocketchip.config.Config = FireSimRocketChipConfig
scala> import freechips.rocketchip.subsystem._ # Get some important Fields
import freechips.rocketchip.subsystem.RocketTilesKey
scala> inst(RocketTilesKey).size # Query number of cores
res2: Int = 1
scala> inst(RocketTilesKey).head.dcache.get.nWays # Query L1 D$ associativity
res3: Int = 4
Rocket Chip Generator-based SoCs (firesim project)¶
Using the Make variables listed above, we give examples of generating different targets using the default Rocket Chip-based target project.
Rocket-based SoCs¶
Three design classes use Rocket scalar in-order pipelines.
Single core, Rocket pipeline (default)
make DESIGN=FireSim TARGET_CONFIG=FireSimRocketChipConfig
Single-core, Rocket pipeline, no network interface
make DESIGN=FireSimNoNIC TARGET_CONFIG=FireSimRocketChipConfig
Quad-core, Rocket pipeline
make DESIGN=FireSim TARGET_CONFIG=FireSimRocketChipQuadCoreConfig
BOOM-based SoCs¶
The BOOM (Berkeley Out-of-Order Machine) superscalar out-of-order pipelines can also be used with the same design classes that the Rocket pipelines use. Only the TARGET_CONFIG needs to be changed, as shown below:
Single-core BOOM
make DESIGN=FireSim TARGET_CONFIG=FireSimBoomConfig
Single-core BOOM, no network interface
make DESIGN=FireSimNoNIC TARGET_CONFIG=FireSimBoomConfig
Generating A Different FASED Memory-Timing Model Instance¶
Golden Gate’s memory-timing model generator, FASED, can elaborate a space of
different DRAM model instances: we give some typical ones here. These targets
use the Makefile-defined defaults of DESIGN=FireSim PLATFORM_CONFIG=BaseF1Config
.
Quad-rank DDR3 first-ready, first-come first-served memory access scheduler
- ::
- make TARGET_CONFIG=DDR3FRFCFS_FireSimRocketChipConfig
As above, but with a 4 MiB (maximum simulatable capacity) last-level-cache model
make TARGET_CONFIG=DDR3FRFCFSLLC4MB_FireSimRocketChipConfig
FASED timing-model configurations are passed to the FASED Bridges
in your Target’s FIRRTL, and so must be prepended to TARGET_CONFIG
.
Midas Examples (midasexamples project)¶
This project can generate a handful of toy target-designs (set with the make
variable DESIGN
). Each of these designs has their own chisel source file and serves to demostrate
the features of Golden Gate.
Some notable examples are:
GCD
: the “Hello World!” of hardware.WireInterconnect
: demonstrates how combinational paths can be modeled with Golden Gate.PrintfModule
: demonstrates synthesizable printfsAssertModule
: demonstrates synthesizable assertions
To generate a target, set the make variable
TARGET_PROJECT=midasexamples
. so that the right project makefrag is
sourced.
FASED Tests (fasedtests project)¶
This project generates target designs capable of driving considerably more bandwidth to an AXI4-memory slave than current FireSim targets. These are used to do integration and stress testing of FASED instances.
Examples¶
Generate a synthesizable AXI4Fuzzer (based off of Rocket Chip’s TL fuzzer), driving a DDR3 FR-FCFS-based FASED instance.
make TARGET_PROJECT=fasedtests DESIGN=AXI4Fuzzer TARGET_CONFIG=FRFCFSConfig
As above, now configured to drive 10 million transactions through the instance.
make TARGET_PROJECT=fasedtests DESIGN=AXI4Fuzzer TARGET_CONFIG=NT10e7_FRFCFSConfig