The Spade Hardware Description Language

# List of optimization passes to apply in the Spade compiler. The passes are applied
# in the order specified here. Additional passes specified on individual modules with
# #[optimize(...)] are applied before global passes.
optimizations = ["…", …]
# List of commands to run before anything else.
preprocessing = ["…", …] # Optional
# Map of libraries to include in the build.
# 
# Example:
# ```toml
# [libraries]
# protocols = {git = https://gitlab.com/TheZoq2/spade_protocols.git}
# spade_v = {path = "deps/spade-v"}
# ```
libraries = {key: <Library>, …} # Optional
# Plugins to load. Specifies the location as a library, as well
# as arguments to the plugin
# 
# Example:
# ```toml
# [plugins.loader_generator]
# path = "../plugins/loader_generator/"
# args.asm_file = "asm/blinky.asm"
# args.template_file = "../templates/program_loader.spade"
# args.target_file = "src/programs/blinky_loader.spade"
# 
# [plugins.flamegraph]
# git = "https://gitlab.com/TheZoq2/yosys_flamegraph"
# ```
# 
# Plugins contain a `swim_plugin.toml` which describes their behaviour.
# See [crate::plugin::config::PluginConfig] for details
plugins = {key: <Plugin>, …} # Optional

# Library package and metadata
[package]
<Package>

# Where to find the Spade compiler. See [Library] for details
[compiler]
<Library>

# Verilog to import in both simulation and synthesis.
[verilog] # Optional
<ImportVerilog>

[simulation]
<Simulation>

[synthesis] # Optional
<Synthesis>

# Preset board configuration which can be used instead of synthesis, pnr, packing and upload
[board] # Optional
<Board>

[pnr] # Optional
<Pnr>

[packing] # Optional
<PackingTool>

[upload] # Optional
<UploadTool>

[log_output]
<LogOutputLevel>

args = {key: "…", …}

[lib]
<Library>

tool = "icesprog"

tool = "iceprog"

tool = "tinyprog"

tool = "openocd"
config_file = "path/to/file"

tool = "fujprog"

tool = "openFPGALoader"
board = "…"

tool = "custom"
commands = ["…", …]

tool = "icepack"

tool = "ecppack"
idcode = "…" # Optional

tool = "gowin_pack"
device = "…"

tool = "gmpack"

architecture = "ice40"

[device_args]
<Ice40Args>
# If set, inputs and outputs of the top module do not need a corresponding field
# in the pin file. This is helpful for benchmarking when pin mapping is irreleveant, but
# when running in hardware, it is recommended to leave this off in order to get a warning
# when pins aren't set in the pin file.
allow_unconstrained = true|false
# Continue to the upload step even if the timing isn't met.
# This is helpful when you suspect that the place-and-route tool is conservative
# with its timing requirements, but gives no guarantees about correctness.
allow_timing_fail = true|false
# Pass additional arguments to nextpnr
# This is helpful when you want to use arguments that swim does not have explicit support for.
extra_args = ["…", …]
# The path to a file which maps inputs and outputs of your top module to physical pins.
# On ECP5 chips, this is a `pcf` file, and on iCE40, it is an `lpf` file.
pin_file = "path/to/file"

architecture = "ecp5"

[device_args]
<Ecp5Args>
# If set, inputs and outputs of the top module do not need a corresponding field
# in the pin file. This is helpful for benchmarking when pin mapping is irreleveant, but
# when running in hardware, it is recommended to leave this off in order to get a warning
# when pins aren't set in the pin file.
allow_unconstrained = true|false
# Continue to the upload step even if the timing isn't met.
# This is helpful when you suspect that the place-and-route tool is conservative
# with its timing requirements, but gives no guarantees about correctness.
allow_timing_fail = true|false
# Pass additional arguments to nextpnr
# This is helpful when you want to use arguments that swim does not have explicit support for.
extra_args = ["…", …]
# The path to a file which maps inputs and outputs of your top module to physical pins.
# On ECP5 chips, this is a `pcf` file, and on iCE40, it is an `lpf` file.
pin_file = "path/to/file"

architecture = "gowin"

[device_args]
<GowinArgs>
# If set, inputs and outputs of the top module do not need a corresponding field
# in the pin file. This is helpful for benchmarking when pin mapping is irreleveant, but
# when running in hardware, it is recommended to leave this off in order to get a warning
# when pins aren't set in the pin file.
allow_unconstrained = true|false
# Continue to the upload step even if the timing isn't met.
# This is helpful when you suspect that the place-and-route tool is conservative
# with its timing requirements, but gives no guarantees about correctness.
allow_timing_fail = true|false
# Pass additional arguments to nextpnr
# This is helpful when you want to use arguments that swim does not have explicit support for.
extra_args = ["…", …]
# The path to a file which maps inputs and outputs of your top module to physical pins.
# On ECP5 chips, this is a `pcf` file, and on iCE40, it is an `lpf` file.
pin_file = "path/to/file"

architecture = "gatemate"

[device_args]
<GatemateArgs>
# If set, inputs and outputs of the top module do not need a corresponding field
# in the pin file. This is helpful for benchmarking when pin mapping is irreleveant, but
# when running in hardware, it is recommended to leave this off in order to get a warning
# when pins aren't set in the pin file.
allow_unconstrained = true|false
# Continue to the upload step even if the timing isn't met.
# This is helpful when you suspect that the place-and-route tool is conservative
# with its timing requirements, but gives no guarantees about correctness.
allow_timing_fail = true|false
# Pass additional arguments to nextpnr
# This is helpful when you want to use arguments that swim does not have explicit support for.
extra_args = ["…", …]
# The path to a file which maps inputs and outputs of your top module to physical pins.
# On ECP5 chips, this is a `pcf` file, and on iCE40, it is an `lpf` file.
pin_file = "path/to/file"

[device]
<GatemateDevice>

[device]
<GowinDevice>

package = "…"

[device]
<Ecp5Device>

[speed_grade] # Optional
<Ecp5SpeedGrade>

package = "…"

[device]
<Ice40Device>

name = "Ecpix5"
pin_file = "path/to/file" # Optional
config_file = "path/to/file" # Optional

name = "GoBoard"
pcf = "path/to/file" # Optional

name = "tinyfpga-bx"
pcf = "path/to/file" # Optional

name = "Icestick"
pcf = "path/to/file" # Optional

# The name of the unit to use as a top module for the design. The name must
# be an absolute path to the unit, for example `proj::main::top`, unless the
# module is marked `#[no_mangle]` in which case the name is used.
# 
# Can also be set to the name of a module defined in verilog if a pure verilog top
# is desired.
top = "…"
# The yosys command to use for synthesis
command = "…"

# Extra verilog files only needed during the synthesis process.
[verilog] # Optional
<ImportVerilog>

# Directory containing all test benches
testbench_dir = "path/to/file"
# Extra dependencies to install to the test venv via pip
python_deps = ["…", …] # Optional
# The simulator to use as the cocotb backend. Currently verified to support verilator and
# icarus, but other simulators supported by cocotb may also work.
# 
# Defaults to 'icarus'
# 
# Requires a relatively recent version of verilator
simulator = "…"
# The C++ version to use when compiling verilator test benches. Anything that
# clang or gcc accepts in the -std= field works, but the verilator wrapper requires
# at least c++17.
# Defaults to c++17
cpp_version = "…" # Optional
# Extra arguments to pass to verilator when building C++ test benches. Supports substituting
# `#ROOT_DIR#` to get project-relative directories
verilator_args = ["…", …] # Optional

# Search paths for Verilog include directives.
include = ["path/to/file", …] # Optional
# Paths to Verilog files to import. Supports glob syntax.
sources = ["…", …] # Optional

compiler = {git = "https://gitlab.com/spade-lang/spade/"}

path = "compiler/"

git = "…"
commit = "…" # Optional
tag = "…" # Optional
branch = "…" # Optional

path = "path/to/file"

# The name of the library. Must be a valid Spade identifier
# Anything defined in this library will be under the `name` namespace
name = "…"
description = "…" # Optional
authors = ["…", …] # Optional
license-file = "path/to/file" # Optional
readme = "path/to/file" # Optional

[version] # Optional
<Version>

[license] # Optional
<SerdeSpdxExpression>