PitonConfig

PitonConfig, in chia_openpiton/state_def.py, describes one OpenPiton configuration and names the model directory its build lives in. It is a frozen dataclass: assigning to a field raises dataclasses.FrozenInstanceError. configure() returns a PitonConfig with the checkout’s revisions filled in. Code can also construct one directly, as MACE’s loop does for each task.

Fields

Field	Type	Default	Meaning
sys	str	"manycore"	sims -sys= value. "manycore" is the full-chip mesh; any other name selects a registered OpenPiton unit-test environment, piton/tools/src/sims/<sys>.config
core	PitonCore	"ariane"	"ariane", "sparc", "pico", or "generic" (the Generic Tile)
x_tiles	int	1	Mesh width
y_tiles	int	1	Mesh height
network_config	NetworkConfig	"2dmesh_config"	"2dmesh_config" or "xbar_config"; OpenPiton builds the crossbar only with y_tiles=1
config_rtl	tuple[str, ...]	("MINIMAL_MONITORING",)	RTL define names
caches	dict[str, tuple[int, int]]	A copy of DEFAULT_CACHES	Cache name to (size_bytes, associativity); a cache the mapping leaves out keeps its default
extra_flags	tuple[str, ...]	()	Further sims flags, appended verbatim
source_rev	str	""	Checkout commit, set by configure()
ariane_rev	str	""	Ariane submodule commit, set by configure()
verilator_version	str	""	verilator --version text, set by configure()
diff	str	""	Unstaged diff under piton/verif/env/manycore, set by configure()
source_edits	str	""	Hash of the edits a caller applied with apply_edits() for this build
generic_core	str	""	For core="generic", <name>@<digest> of the core descriptor applied to the checkout; only that core takes it

Constants

DEFAULT_CACHES = {
    "l1i": (16384, 4),
    "l1d": (8192, 4),
    "l15": (8192, 4),
    "l2": (65536, 4),
}
MAX_TILES_PER_AXIS = 256
COVERAGE_LINE_FLAG = "-vlt_build_args=--coverage-line"
ARIANE_WAY_RULE = "On Ariane, neither the L1D nor the L1I may have more ways than the L1.5."

DEFAULT_CACHES mirrors piton/tools/src/sims/manycore.config. Each cache name fills the <name> in -config_<name>_size and -config_<name>_associativity. MAX_TILES_PER_AXIS matches the limit sims enforces with DIE. x_tiles can be at most 256. Adding COVERAGE_LINE_FLAG to extra_flags turns on Verilator line coverage (see Code Coverage).

Validation

__post_init__ raises ValueError on an invalid configuration:

Condition	Example message
Unknown core	core must be one of ariane, sparc, pico, generic, got 'mips'
Tile count not an int, or a bool	x_tiles must be an int, got True
Tile count outside 1 to 256	x_tiles must be 1..256, got 0
Unknown network	network_config must be '2dmesh_config' or 'xbar_config', got '2d_mesh'
Unknown cache name	unknown cache 'l3'; valid: ['l15', 'l1d', 'l1i', 'l2']
Size or associativity not positive	cache l2 size/associativity must be positive, got (0, 4)

__post_init__ does not check sys. After validation it fills in each cache a caches mapping leaves out from DEFAULT_CACHES, and stores every geometry as a tuple.

Derived values

Member	Value
num_tiles	x_tiles * y_tiles
key	SHA-256 hex digest of the configuration’s identity
build_id	"mace_" followed by the first 12 hex digits of key
finish_mask	"1" * num_tiles, one digit per tile
sims_flags()	The sims arguments the configuration implies, in a stable order
way_violations()	One line per L1 that has more ways than the L1.5, such as l1d has 8 ways, more than the L1.5's 4; empty for a configuration that keeps ARIANE_WAY_RULE, another core, or a unit-test sys

Ariane’s way rule

Ariane’s L1.5 adapter, core/cache_subsystem/wt_l15_adapter.sv in the Ariane submodule, asserts ARIANE_WAY_RULE, but inside `ifndef VERILATOR. A Verilator build of a configuration that breaks the rule therefore compiles and runs. build() refuses such a configuration instead, and a co-design search rejects one before building it.

key and build_id

key hashes a JSON object, serialized with sorted keys, that holds sys, core, x_tiles, y_tiles, network_config, config_rtl (sorted), caches (sorted by name), extra_flags (in order), source_rev, ariane_rev, verilator_version, and diff, plus source_edits and generic_core when they are set, so a key recorded before those fields existed stays the same. build() passes build_id to sims as -build_id. sims writes every model to rel-0.1 by default, so without a per-configuration ID two configurations overwrite each other’s model.

caches always holds all four caches, so a mapping that names only some of them and the same mapping with the defaults written out share a key and a model directory. Earlier versions hashed a partial mapping as given. A model they built from one sits under a build ID that nothing computes now, so that configuration builds once more.

Beyond the configuration fields, the key covers source_edits, which the caller sets, and what configure() records: the committed revision, the Ariane submodule commit, the Verilator version, and the unstaged diff under piton/verif/env/manycore. Edits anywhere else in the working tree leave the key unchanged. A directly constructed PitonConfig leaves those four fields empty, so its key depends on the configuration fields alone. The build cache covers the rest of the checkout: build() reuses a model only while the checkout’s source fingerprint matches the one recorded when the model was built.

sims_flags()

For sys="manycore", sims_flags() emits these flags in order:

Source	Flags
sys	-sys=manycore
x_tiles, y_tiles	-x_tiles=<x>, -y_tiles=<y>
network_config	-network_config=<value>
core="ariane"	-ariane
core="pico"	-pico, -rv32_target_triple=riscv64-unknown-elf
core="generic"	-generic, -rv32_target_triple=riscv64-unknown-elf; MACE adds the core descriptor’s -rv32_march, -rv32_mabi, and -rv32_image_base through extra_flags
core="sparc"	No flag
config_rtl	-config_rtl=<define> for each entry
caches	-config_<name>_size=<size> and -config_<name>_associativity=<assoc> for each cache, sorted by name
extra_flags	Each flag, verbatim

The default configuration produces:

-sys=manycore -x_tiles=1 -y_tiles=1 -network_config=2dmesh_config -ariane
-config_rtl=MINIMAL_MONITORING
-config_l15_size=8192 -config_l15_associativity=4
-config_l1d_size=8192 -config_l1d_associativity=4
-config_l1i_size=16384 -config_l1i_associativity=4
-config_l2_size=65536 -config_l2_associativity=4

-network_config is always explicit. Left unset, sims defaults to the string 2d_mesh, which pyhplib.py does not recognise. For pico, -rv32_target_triple makes piton/tools/bin/rv32_as use the installed riscv64-unknown-elf-gcc for rv32ima/ilp32 instead of a riscv32-unknown-elf toolchain (see PicoRV32). Every cache gets both flags, including one the caches mapping left out.

For any other sys, sims_flags() returns -sys=<sys> followed by extra_flags. The mesh, core, and cache fields still count toward key.

extra_flags carries anything else sims accepts. For example, -rv64_march=rv64imafdc_zicsr_zifencei lets OpenPiton’s diags assemble under binutils 2.38 and later.