FireSim

API reference for chia.firesim. These pages are generated from the docstrings in the source, so they stay in sync with the code.

The FireSim API is still under development and may change in future releases.

Config

FireSim-specific configuration dataclasses and YAML parsers.

class chia.firesim.config.FireSimBuildConfig(name: str, platform: str, target_project: str, target_project_makefrag: str | None, design: str, target_config: str, platform_config: str, fpga_frequency: float, build_strategy: str, bit_builder_recipe: str, deploy_quintuplet: str | None = None, post_build_hook: str | None = None, metasim_customruntimeconfig: str | None = None, build_id: str | None = None, build_group: str | None = None, incremental_base_build_id: str | None = None, market: str = 'ondemand', enable_pr: bool = False, pr_module_name: str | None = None, pr_base_build_id: str | None = None, pr_partition_cell: str | None = None)

Bases: object

A single bitstream build recipe, parsed from config_build_recipes.yaml.

Mirrors one stanza of a FireSim config_build_recipes.yaml (the recipe name is the YAML key; the remaining fields come from that entry). Drives an FPGA bitstream build for a given target design + FPGA platform.

name

Recipe name (the YAML key); used as the build’s base name (e.g. "midasexamples_gcd").

Type:

str

platform

FireSim platform (e.g. "f1", "f2"); from the recipe’s PLATFORM.

Type:

str

target_project

Chipyard target project (TARGET_PROJECT, e.g. "firesim", or "midasexamples" for MIDAS example designs).

Type:

str

target_project_makefrag

Optional makefrag override for the target project (TARGET_PROJECT_MAKEFRAG, e.g. "../../../generators/firechip/chip/src/main/makefrag/firesim"); None to use the default.

Type:

str | None

design

Top-level design/harness module to build (DESIGN, e.g. "FireSim", or "GCD" for the MIDAS example).

Type:

str

target_config

Chipyard target Scala config (TARGET_CONFIG) selecting the SoC configuration (e.g. "FireSimMegaBoomChiaBigCacheConfig", "FireSimRocketConfig").

Type:

str

platform_config

FireSim platform config (PLATFORM_CONFIG) selecting host-side simulation options (e.g. "DefaultF2Config").

Type:

str

fpga_frequency

Target FPGA clock frequency in MHz (from platform_config_args.fpga_frequency, e.g. 20).

Type:

float

build_strategy

Vivado build strategy (from platform_config_args.build_strategy, e.g. "TIMING").

Type:

str

bit_builder_recipe

Path to the FireSim bit-builder recipe YAML (bit_builder_recipe) selecting the platform’s build flow (e.g. "bit-builder-recipes/f2.yaml").

Type:

str

deploy_quintuplet

Optional override for the FireSim deploy quintuplet (PLATFORM-TARGET_PROJECT-DESIGN-TARGET_CONFIG-PLATFORM_CONFIG, e.g. "f2-firesim-FireSim-FireSimMegaBoomChiaBigCacheConfig-DefaultF2Config"); None to let FireSim derive it.

Type:

str | None

post_build_hook

Optional path to a script run after the build completes.

Type:

str | None

metasim_customruntimeconfig

Optional custom runtime config for metasim (software-simulation) builds.

Type:

str | None

build_id

User-specified build ID (e.g. "megaboom-baseline"). If omitted, an auto-generated {name}-{timestamp}-{short_uuid} is used.

Type:

str | None

build_group

Optional subdirectory under builds/ for organizing builds (e.g. builds/{build_group}/{build_id}/). If omitted, builds are stored flat under builds/{build_id}/.

Type:

str | None

incremental_base_build_id

build_id of a previous build whose DCPs to use as Vivado incremental synthesis/implementation references (~50% faster); None for a full build.

Type:

str | None

market

AWS instance market for the build host ("ondemand" or "spot").

Type:

str

enable_pr

Whether to enable partial reconfiguration (PR) for this build.

Type:

bool

pr_module_name

Reconfigurable module name when enable_pr is set.

Type:

str | None

pr_base_build_id

build_id of the PR base build (its presence triggers the reconfigurable-module flow).

Type:

str | None

pr_partition_cell

PR partition cell; auto-discovered if omitted.

Type:

str | None

class chia.firesim.config.FireSimRunConfig(hw_config_name: str, build_ref: str | None = None, agfi: str | None = None, workload_name: str = '', num_sims: int = 1, instance_type: str = 'f2.12xlarge', plusarg_passthrough: str = '', terminate_on_completion: bool = True, driver_tarball_path: str | None = None, ami_id: str | None = None, market: str = 'ondemand', bootbinary_path: str | None = None, rootfs_path: str | None = None, result_id: str | None = None, driver_s3_path: str | None = None, bootbinary_s3_path: str | None = None, rootfs_s3_path: str | None = None)

Bases: object

Runtime configuration for an FPGA simulation run.

Describes a single FireSim run: which bitstream (AGFI) and simulation driver to deploy, which workload to run, and on what instances. The build artifacts (agfi, driver_s3_path) are typically auto-derived from build_ref via resolve_build().

hw_config_name

Name of the hardware-database (hwdb) entry / hardware config to run (the config_hwdb.yaml key, e.g. "firesim_megaboom_chia_bigcache").

Type:

str

build_ref

Build reference — path under builds/ on S3 identifying a build, of the form "{recipe}/{build_id}". Examples: "FireSimRocket-20260409-a1b2c3d4" (flat) or "experiments/FireSimRocket-20260409-a1b2c3d4" (grouped). When set, agfi and driver_s3_path are auto-derived via resolve_build().

Type:

str | None

agfi

AWS Global FPGA Image ID (e.g. "agfi-01234abcde") to program onto the FPGA; auto-derived from build_ref if unset.

Type:

str | None

workload_name

Name of the workload to run (e.g. "spec17-intrate.json").

Type:

str

num_sims

Number of parallel simulation slots to launch.

Type:

int

instance_type

AWS instance type for the run host (e.g. "f2.12xlarge").

Type:

str

plusarg_passthrough

Extra +plusarg flags passed through to the simulator.

Type:

str

terminate_on_completion

Whether to terminate the run instance when the run finishes.

Type:

bool

driver_tarball_path

Local path to the simulation driver tarball (legacy/fallback; prefer driver_s3_path).

Type:

str | None

ami_id

Optional AMI ID for the run instance.

Type:

str | None

market

AWS instance market for the run host ("ondemand" or "spot").

Type:

str

bootbinary_path

Local path to the boot binary (legacy/fallback; prefer bootbinary_s3_path).

Type:

str | None

rootfs_path

Local path to the root filesystem image (legacy/fallback; prefer rootfs_s3_path).

Type:

str | None

result_id

Optional subdirectory under results/ for organizing run results (e.g. results/{result_id}/{suite_name}/). If omitted, results are stored under results/{suite_name}/{timestamp}/.

Type:

str | None

driver_s3_path

S3 URI of the simulation driver tarball (preferred — any worker node can use it), e.g. "s3://firesim-chia-builds/builds/design/driver-bundle.tar.gz"; auto-derived from build_ref when resolve_build() is called.

Type:

str | None

bootbinary_s3_path

S3 URI of the boot binary (preferred over the local path).

Type:

str | None

rootfs_s3_path

S3 URI of the root filesystem image (preferred over the local path).

Type:

str | None

resolve_build(s3_bucket: str) → FireSimRunConfig

Populate agfi and driver_s3_path from build_ref if not already set.

Fetches build-info.json from S3 for the referenced build and uses it to fill in agfi and driver_s3_path. Explicit values for either field take precedence (they are not overwritten). A no-op if build_ref is unset or both derived fields are already populated.

Parameters:

s3_bucket – S3 bucket name holding the build’s build-info.json.

Returns:

self, with agfi and driver_s3_path populated from the build referenced by build_ref where they were previously unset. Returned for chaining.

class chia.firesim.config.FireSimConfig(chipyard_path: str, deploy_path: str, build_recipes_file: str = 'config_build_recipes.yaml')

Bases: object

Top-level FireSim configuration, parsed from the Chia cluster YAML.

chipyard_path

Filesystem path to the Chipyard checkout on the host.

Type:

str

deploy_path

Filesystem path to the FireSim deploy directory (sim/firesim workspace where builds/runs are launched).

Type:

str

build_recipes_file

Filename of the FireSim build-recipes YAML to load (defaults to "config_build_recipes.yaml").

Type:

str

chia.firesim.config.load_build_recipes(yaml_path: str) → dict[str, FireSimBuildConfig]

Parse a config_build_recipes.yaml file into FireSimBuildConfig objects.

Parameters:

yaml_path – Path to config_build_recipes.yaml.

Returns:

Dict mapping recipe name to FireSimBuildConfig. Empty if the YAML is empty.

Raises:

FileNotFoundError – If yaml_path does not exist.

chia.firesim.config.load_hwdb(yaml_path: str) → dict[str, dict[str, Any]]

Parse config_hwdb.yaml into a dict of hw config name -> properties.

Parameters:

yaml_path – Path to config_hwdb.yaml.

Returns:

Dict mapping hw config name to its hwdb properties (agfi, etc.); empty if the YAML does not parse to a mapping.

Raises:

FileNotFoundError – If yaml_path does not exist.

chia.firesim.config.fetch_build_info(s3_bucket: str, build_ref: str) → dict

Fetch build-info.json from S3 for a build reference.

Parameters:

• s3_bucket – S3 bucket name.

• build_ref – Path under builds/ identifying a build. Examples: “FireSimRocket-20260409-a1b2c3d4” (flat), “prefetcher-experiments/FireSimRocket-20260409-a1b2c3d4” (grouped), or “latest” / “mygroup/latest” for the most recent build.

Returns:

agfi, driver_s3_path, build_id, etc.

Return type:

Parsed build-info dict with keys

Raises:

FileNotFoundError – If build-info.json does not exist at the expected path.

Chia Functions

@ChiaFunction wrappers for FireSim build and run operations.

These functions can be scheduled onto the firesim_manager node, or called directly for standalone use.

chia.firesim.chia_functions.firesim_build_bitstream(build_recipe_name: str, aws_config_dict: dict, s3_bucket: str, source_overlay_dir: str | None = None, docker_image: str = 'chia-chisel-build', instance_type: str = 'z1d.2xlarge', build_recipes_file: str | None = None, build_config_dict: dict | None = None, results_dir: str | None = None, local_log_dir: str | None = None) → BitstreamBuildResult

Build an FPGA bitstream using an ephemeral EC2 build host.

All build steps run on the EC2 instance — the head node does NOT need a chipyard installation. Chisel elaboration + driver build happen inside a Docker container (chia-chisel-build); Vivado runs natively on the host.

Parameters:

• build_recipe_name – Name of the build recipe (used for tagging/logging).

• aws_config_dict – Dict representation of AWSConfig fields.

• s3_bucket – S3 bucket for AFI tarball storage.

• source_overlay_dir – Local dir with modified Chisel sources to overlay onto the container’s chipyard. If None, uses the Docker image as-is.

• docker_image – Docker image for Chisel elaboration.

• instance_type – EC2 instance type for the build host.

• build_recipes_file – Path to build recipes YAML (to look up recipe by name). Mutually exclusive with build_config_dict.

• build_config_dict – Dict representation of FireSimBuildConfig fields. If provided, used directly instead of looking up from recipes file.

• results_dir – Local directory to store build results. Optional.

• local_log_dir – Local directory to mirror the build host’s logs into. Optional; if None, logs are not copied back to the head node.

Returns:

BitstreamBuildResult with the AGFI/AFI (or raw bitstream path), the hwdb_entry and build_ref needed to launch runs, and the build log. On a recipe-resolution error (missing recipe, or neither build_config_dict nor build_recipes_file given) returns early with success=False and the reason in build_log.

chia.firesim.chia_functions.firesim_run_workload(run_config_dict: dict, aws_config_dict: dict, sim_timeout: int = 14400, results_dir: str | None = None, name: str = '', instance_prefix: str | None = None, terminate_on_failure: bool = True, local_log_dir: str | None = None, log_prefix: str = 'firesim-run') → FireSimRunResult

Run an FPGA simulation workload using ephemeral F2 EC2 instances.

Parameters:

• run_config_dict – Dict representation of FireSimRunConfig fields. If it carries a build_ref, the AGFI and driver S3 path are auto-derived from it via resolve_build against the AWS config’s S3 bucket (falling back to "firesim-chia-builds").

• aws_config_dict – Dict representation of AWSConfig fields.

• sim_timeout – Maximum simulation runtime in seconds (default 14400 = 4h).

• results_dir – Local directory to store results. Optional.

• name – Name of the simulation instance. Optional.

• instance_prefix – Optional prefix applied to the launched EC2 instance name(s); None uses the runner’s default naming.

• terminate_on_failure – If False, leave instances running when the simulation raises — for post-mortem SSH debugging.

• local_log_dir – Local directory to mirror the run’s logs into. Optional.

• log_prefix – Filename/tag prefix for emitted log files (default "firesim-run").

Returns:

FireSimRunResult with per-slot uartlogs, rootfs/sim outputs, the overall success status, and the wall-clock duration.

State Def

Result dataclasses for FireSim build and run operations.

class chia.firesim.state_def.BitstreamBuildResult(recipe_name: str, agfi: str | None, afi: str | None, success: bool, build_log: str, hwdb_entry: str, driver_s3_path: str | None = None, build_id: str = '', build_ref: str = '', bitstream_path: str | None = None)

Bases: object

Result of a firesim_build_bitstream() FPGA bitstream build.

recipe_name

Name of the build recipe this result is for.

Type:

str

agfi

AWS Global FPGA Image ID produced by the build (e.g. "agfi-..."); None on failure or for non-AGFI platforms (see bitstream_path).

Type:

str | None

afi

AWS FPGA Image ID (the un-globalized "afi-..." handle); None when not produced.

Type:

str | None

success

True iff the build completed and a usable image was produced.

Type:

bool

build_log

Captured build log (also carries the failure reason on early recipe-resolution errors).

Type:

str

hwdb_entry

The hardware-database YAML stanza for this bitstream, ready to paste/feed into a FireSim run config.

Type:

str

driver_s3_path

S3 URI of the uploaded simulation driver tarball; None if not uploaded.

Type:

str | None

build_id

Unique identifier assigned to this build.

Type:

str

build_ref

"{recipe_name}/{build_id}" — the handle to pass as a run config’s build_ref to auto-resolve the AGFI + driver for a run.

Type:

str

bitstream_path

S3 URI of a raw .bit artifact, for platforms that don’t produce an AGFI (e.g. corigine_xb10); None for AGFI-producing platforms (f2/f1).

Type:

str | None

class chia.firesim.state_def.FireSimRunResult(workload_name: str, success: bool, uartlogs: dict[str, str]=<factory>, rootfs_outputs: dict[str, dict[str, str]]=<factory>, sim_outputs: dict[str, dict[str, str]]=<factory>, duration_seconds: float = 0.0)

Bases: object

Result of a firesim_run_workload() FPGA simulation run.

workload_name

Name of the workload that was run.

Type:

str

success

True iff the simulation completed successfully.

Type:

bool

uartlogs

Per-slot UART console output, mapping slot_name -> captured uartlog text.

Type:

dict[str, str]

rootfs_outputs

Per-slot files copied back from each simulation’s rootfs, mapping slot_name -> {relative_filepath -> file_content}.

Type:

dict[str, dict[str, str]]

sim_outputs

Per-slot host-side simulation artifacts (memory_stats, autocounters, etc.), mapping slot_name -> {relative_filepath -> file_content}.

Type:

dict[str, dict[str, str]]

duration_seconds

Wall-clock duration of the run, in seconds.

Type:

float

class chia.firesim.state_def.SimJobResult(benchmark_name: str, success: bool, uartlog: str = '', outputs: dict[str, bytes]=<factory>, duration_seconds: float = 0.0, log: str = '', node_id: str = '', ip: str = '')

Bases: object

Result of running one single-job workload on one FPGA.

success is true only if infrasetup and runworkload both exited 0, which means FireSim ran the job, not that the benchmark passed (see uartlog); log holds the manager output tail, which carries the reason on failure. outputs maps each file of the run’s results directory to its bytes. node_id and ip name the machine that ran it: its Ray node and its public IP.

class chia.firesim.state_def.BuildRecipe(name: str, design: str = 'FireSim', target_config: str = 'FireSimRocketConfig', platform_config: str = 'BaseF2Config', platform: str = 'f2', target_project: str = 'firesim', fpga_frequency: int = 75, build_strategy: str = 'TIMING', java_heap_size: str = '16G')

Bases: object

What to build: the FireSim quintuplet plus the Vivado knobs.

Mirrors one stanza of config_build_recipes.yaml.

classmethod from_yaml(path: str, name: str) → BuildRecipe

Recipe name of a FireSim config_build_recipes.yaml.

class chia.firesim.state_def.RunConfig(sections: dict = <factory>)

Bases: object

FireSim runtime settings: sections of config_runtime.yaml, {section: {key: value}}. The run farm, the workload and the hardware config are chia’s, and it writes them over these.

classmethod from_yaml(path: str) → RunConfig

The sections of a FireSim config_runtime.yaml.

class chia.firesim.state_def.EcadBuildResult(recipe_name: str, success: bool, bitstream: FSBitstream | None = None, log: str = '')

Bases: object

Result of an build_bitstream().

bitstream is the artifact to hand to a run, and is None unless the build succeeded; log carries the reason when it did not.

Bitstream

An FPGA bitstream paired with the driver built against it.

class chia.firesim.fs_bitstream.FSBitstream(quintuplet: str, agfi: str | None = None, bitstream_uri: str | None = None, bitstream_bytes: bytes | None = None, driver_uri: str | None = None, driver_bytes: bytes | None = None)

Bases: object

An FPGA image plus the simulation driver built against it.

The two always travel together: a driver built from different RTL than the bitstream fails in confusing ways. Either half is carried by value (*_bytes, straight out of a build) or by reference (*_uri, any fsspec URI). publish() turns value into reference so a fan-out over many FPGAs pulls from S3 instead of replicating bytes through Ray.

TODO: f2 names its image with an AGFI while the Alveo/xb10 platforms use a bitstream tar, and config_hwdb.yaml rejects an entry carrying both. This split may need to change once a non-f2 platform runs.

publish(bucket: str, prefix: str) → FSBitstream

Upload any by-value half to S3 and return a reference-only copy.

to_hwdb(name: str, deploy_dir: str) → dict[str, dict]

Render the config_hwdb.yaml stanza, writing out any bytes.

FireSim resolves a bare path relative to firesim/deploy and fetches URIs itself, so both cases end up as a plain string here.

Manager Node

Run a FireSim workload on the F2 FPGAs of a farm, one job per FPGA at a time.

FireSimManagerNode.run_workload() runs in the calling process: it sends each job to an FPGA as a FireSimManagerNode.run_job() task, and takes down the FPGAs with no job left through their farm. run_job runs in the FireSim container on an F2 instance (chia.firesim.specs.F2_SIM). The manager’s run farm is the instance itself (FireSim’s ExternallyProvisioned mode), and _MANAGER runs FireSim’s commands for it on the instance, with no ssh.

class chia.firesim.manager_node.FireSimManagerNode(timeout_seconds: int | None = None)

Bases: object

Runs firesim infrasetup and firesim runworkload on the local FPGA.

Parameters:

timeout_seconds – Wall-clock limit per manager step; None for no limit.

run_workload(farm: Farm, workload: FireMarshalArtifact, bitstream: FSBitstream, config: RunConfig | None = None, teardown: bool = True) → list[SimJobResult]

Run each job of workload on an FPGA of farm, one job at a time per FPGA, and return the results in the order they finish. Runs in the calling process.

With teardown and a farm that has its manager, an FPGA with no job left goes down at once, and at the end so does the whole farm.

run_job(job: FireMarshalArtifact, bitstream: FSBitstream, config: RunConfig | None = None) → SimJobResult

Run the single-job workload job with bitstream on this worker’s FPGA, and collect its results.

config holds the FireSim runtime settings (config_runtime.yaml). Infrasetup and runworkload are one task so both use the same FPGA. Each phase is reported on the FPGA status board.

Worker Specs

EC2 workers for FireSim, ready to hand to AWSManager.launch.

Each is a (NodeTypeConfig, AWSNodeConfig) pair — a cluster file’s node type and its aws_nodes: entry. KeyName and the ssh key are account values AWSManager fills in; an empty ImageId means the FPGA Developer AMI.

ECAD Build Node

Build an f2 bitstream with FireSim’s own build code.

class chia.firesim.bitstream_build_node.BitstreamBuildNode(timeout_seconds: int = 86400)

Bases: object

Applies a chipyard diff and runs firesim buildbitstream.

Parameters:

timeout_seconds – Wall-clock limit for the whole build, AGFI included.