Project Configuration - The Spade Programming Language

Config

The main project configuration specified in swim.toml

Summary

# The name of the library. Must be a valid Spade identifier
# Anything defined in this library will be under the `name` namespace
name = "…"
# 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

# 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>

name String

The name of the library. Must be a valid Spade identifier Anything defined in this library will be under the name namespace

optimizations [String]

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.

compiler Library

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

preprocessing [String]

List of commands to run before anything else.

verilog ImportVerilog

Verilog to import in both simulation and synthesis.

simulation Simulation

synthesis Synthesis

board Board

Preset board configuration which can be used instead of synthesis, pnr, packing and upload

pnr Pnr

packing PackingTool

upload UploadTool

libraries Map[String => Library]

Map of libraries to include in the build.

Example:

[libraries]
protocols = {git = https://gitlab.com/TheZoq2/spade_protocols.git}
spade_v = {path = "deps/spade-v"}

plugins Map[String => Plugin]

Plugins to load. Specifies the location as a library, as well as arguments to the plugin

Example:

[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

log_output LogOutputLevel

LogOutputLevel

One of these strings:

"Full"
"Minimal"

Plugin

Summary

args = {key: "…", …}

[lib]
<Library>

lib Library

args Map[String => String]

UploadTool

One of the following:

icesprog

tool = "icesprog"

Fields

iceprog

tool = "iceprog"

Fields

tinyprog

tool = "tinyprog"

Fields

openocd

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

Fields

config_file FilePath

fujprog

tool = "fujprog"

Fields

openFPGALoader

tool = "openFPGALoader"
board = "…"

Fields

board String

custom

Instead of running a pre-defined set of commands to upload, run the specified list of commands in a shell. #packing_result# will be replaced by the packing output

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

Fields

commands [String]

PackingTool

One of the following:

icepack

tool = "icepack"

Fields

ecppack

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

Fields

idcode String

gowin_pack

tool = "gowin_pack"
device = "…"

Fields

device String

Pnr

One of the following:

ice40

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
# 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"

Fields

device_args Ice40Args

allow_unconstrained bool

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_timing_fail bool

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.

pin_file FilePath

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.

ecp5

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
# 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"

Fields

device_args Ecp5Args

allow_unconstrained bool

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_timing_fail bool

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.

pin_file FilePath

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.

gowin

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
# 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"

Fields

device_args GowinArgs

allow_unconstrained bool

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_timing_fail bool

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.

pin_file FilePath

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.

GowinArgs

Summary


[device]
<GowinDevice>

device GowinDevice

GowinDevice

One of these strings:

"GW1NR-UV9QN881C6/I5"
"GW1N-LV1QN48C6/I5"
"GW1NZ-LV1QN48C6/I5"
"GW1NSR-LV4CQN48PC7/I6"
"GW1NR-LV9QN88PC6/I5"
"GW2AR-LV18QN88C8/I7"
"GW2A-LV18PG256C8/I7"
"GW1N-UV4LQ144C6/I5"
"GW1NS-UX2CQN48C5/I4"
"GW1NR-LV9LQ144PC6/I5"

Lv18QNFamily

One of these strings:

"GW2A-18C"
"GW2AR-18C"
"GW2ANR-18C"
"String" Specify a raw string for the family instead of the swim-provided families. Used if swim doesn't support the configuration you want.

Lv9QN88PC6Family

One of these strings:

"GW1N-9C"
"String" Specify a raw string for the family instead of the swim-provided families. Used if swim doesn't support the configuration you want.

Lv1qn48c6I5Family

One of these strings:

"GW1NZ-1"
"String" Specify a raw string for the family instead of the swim-provided families. Used if swim doesn't support the configuration you want.

Ecp5Args

Summary

package = "…"

[device]
<Ecp5Device>

package String

device Ecp5Device

Ecp5Device

One of these strings:

"LFE5U-12F"
"LFE5U-25F"
"LFE5U-45F"
"LFE5U-85F"
"LFE5UM-25F"
"LFE5UM-45F"
"LFE5UM-85F"
"LFE5UM5G-25F"
"LFE5UM5G-45F"
"LFE5UM5G-85F"

Ice40Args

Summary

package = "…"

[device]
<Ice40Device>

package String

device Ice40Device

Ice40Device

One of these strings:

"iCE40LP384"
"iCE40LP1K"
"iCE40LP4K"
"iCE40LP8K"
"iCE40HX1K"
"iCE40HX4K"
"iCE40HX8K"
"iCE40UP3K"
"iCE40UP5K"
"iCE5LP1K"
"iCE5LP2K"
"iCE5LP4K"

Board

One of the following:

Ecpix5

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

Fields

pin_file FilePath

config_file FilePath

GoBoard

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

Fields

pcf FilePath

tinyfpga-bx

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

Fields

pcf FilePath

Icestick

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

Fields

pcf FilePath

Synthesis

Summary

# 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>

top String

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.

command String

The yosys command to use for synthesis

verilog ImportVerilog

Extra verilog files only needed during the synthesis process.

Simulation

Summary

# 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

testbench_dir FilePath

Directory containing all test benches

python_deps [String]

Extra dependencies to install to the test venv via pip

simulator String

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

cpp_version String

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

verilator_args [String]

Extra arguments to pass to verilator when building C++ test benches. Supports substituting #ROOT_DIR# to get project-relative directories

ImportVerilog

Summary

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

include [FilePath]

Search paths for Verilog include directives.

sources [String]

Paths to Verilog files to import. Supports glob syntax.

Library

Location of a library or external code. Either a link to a git repository, or a path relative to the root of the project.

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

path = "compiler/"

One of the following:

Git

Downloaded from git and managed by swim


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

Fields

git String

commit String

tag String

branch String

Path

A library at the specified path. The path is relative to swim.toml


path = "path/to/file"

Fields

The Spade Programming Language

name String

optimizations [String]

compiler Library

preprocessing [String]

verilog ImportVerilog

simulation Simulation

synthesis Synthesis

board Board

pnr Pnr

packing PackingTool

upload UploadTool

libraries Map[String => Library]

plugins Map[String => Plugin]

log_output LogOutputLevel

lib Library

args Map[String => String]

config_file FilePath

board String

commands [String]

idcode String

device String

device_args Ice40Args

allow_unconstrained bool

allow_timing_fail bool

pin_file FilePath

device_args Ecp5Args

allow_unconstrained bool

allow_timing_fail bool

pin_file FilePath

device_args GowinArgs

allow_unconstrained bool

allow_timing_fail bool

pin_file FilePath

device GowinDevice

package String

device Ecp5Device

package String

device Ice40Device

pin_file FilePath

config_file FilePath

pcf FilePath

pcf FilePath

pcf FilePath

top String

command String

verilog ImportVerilog

testbench_dir FilePath

python_deps [String]

simulator String

cpp_version String

verilator_args [String]

include [FilePath]

sources [String]

git String

commit String

tag String

branch String

path FilePath