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)[source]

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)[source]

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[source]

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')[source]

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][source]

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]][source]

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[source]

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[source]

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[source]

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)[source]

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)[source]

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