Spade 0.5.0

Welcome back to a new Spade release! This time we're releasing version 0.5.0 of Spade and Swim. We skipped the previous release window, so this one contains a bit more stuff than usual.

Language reference🔗

We have started work on a language reference. The progress is slow but ongoing. You can check out the language reference chapter in the Spade book.

Verilator simulation🔗

Spade has supported cocotb testbenches written in Python for a while now. New in this version is the ability to write tests with Verilator in C++! Here's a short example:

// top=cxx::top::add

#include <cassert>
#define TOP add

#include <verilator_util.hpp>

TEST_CASE(it_works, {
    dut->eval();
    ctx->timeInc(1);
    dut->eval();

    s.i->a = "5";
    s.i->b = "10";

    ctx->timeInc(1);
    dut->eval();

    ASSERT_EQ(s.o, "15")

    return 0;
})

MAIN

For more details on how to write testbenches, see the newly added Verilator documentation in the Spade book.

oss-cad-suite🔗

One unfortunate reality with open source FPGAs is the need for multiple different programs to synthesize, place-and-route and programming that are not always distributed as distribution packages. To alleviate this, the Yosys organization releases a packed binary software distribution called oss-cad-suite containing open source software for doing digital design. Swim has learned about oss-cad-suite, so now you can run swim install-tools which will install the latest version and use it when running Swim.

$ swim synth
...
[INFO] Synthesizing
Error:
   0: Failed to run yosys
   1: No such file or directory (os error 2)

Backtrace omitted. Run with RUST_BACKTRACE=1 environment variable to display it.
Run with RUST_BACKTRACE=full to include source snippets.
$ swim install-tools
[INFO] Requesting list of releases
[INFO] Downloading oss-cad-suite-linux-x64-20231117.tgz from
https://github.com/YosysHQ/oss-cad-suite-build/releases/download/2023-11-17/oss-cad-suite-linux-x64-20231117.tgz
$ swim synth
[INFO] Synthesizing
...
[INFO] Synthesized .../build/hardware.json
$ :-)

tomldoc🔗

Swim projects are configured using a file called swim.toml, much like how Cargo projects are configured using a file called Cargo.toml. The format of this file (which fields and sections are available) changes pretty often, and crucially, often enough to make it difficult to keep external documentation up to date. After a critical hit double nerd snipe, Frans wrote a tool to generate mdbook-documentation for configuration files from doc-comments in structs. That's a lot of technical words, so it's probably best to judy look at the finished swim.toml-documentation to understand what it is about. This whole page is generated from the Swim source code, which means that it should always be up to date with how the swim.toml is supposed to look.

Various bug fixes🔗

As usual, there are also additional bugfixes. Check out the Swim changelog and Spade changelog for more information!

This version's featured bug-fix is spade!235 where it turned out Vivado parses \new as the keyword new, even though it is written as an escaped identifier with the leading \. Thanks, Vivado!