The Spade Blog

Spade 0.17.0

2026-03-05T00:00:00+00:00

Associated changelog</a>Swim changelog</a>Git</a>DOI</a></div>

Today we release Spade v0.17.0, a release with 22 individual changelog entries making lots of big and small improvements to the language!</p>

Operator Overloading</h2>

You can now overload many of the operators in Spade allowing you to build better abstractions. For example, you can now define a Vec2</code> struct like this</p>

struct</span> Vec2</span><T> {    x: T,    y: T,}</code></pre>
And then implement the WrappingAdd</code> trait to allow using +.</code> on the new type. By constraining the T</code> generic to any type that also implements WrappingAdd</code>, you can use this Vector struct on any “addable” inner type, including integers, fixed point numbers, complex number, and anything else</p>
impl</span><</span>T: WrappingAdd></span> WrappingAdd for</span> Vec2<</span>T></span> {    fn</span> wrapping_add(self</span>, other: Self) -</span>></span> Self {        Vec2(            self</span>.x +</span>. other.x            self</span>.y +</span>. other.y        )    }}</code></pre>
This initial version of operator overloading supports the following operators:</p>

Eq</code>: ==</code> and !=</code></li>
Ord</code>: <</code>, <=</code>, >=</code> and ></code></li>
Not</code>: !</code></li>
And</code>: &&</code></li>
Or</code>: ||</code></li>
Xor</code>: ^^</code></li>
BitNot</code>: ~</code></li>
BitAnd</code>: &</code></li>
BitOr</code>: |</code></li>
BitXor</code>: ^</code></li>
WrappingAdd</code>: +.</code></li>
WrappingSub</code>: -.</code></li>
WrappingMul</code>: *.</code></li>
WrappingUsub</code>: -.</code></li>
</ul>
This list will be expanded soon to support more operators, but doing so requires a few improvements to the type system.</p>
Wrapping Operators</h2>
What is that +.</code> operator in the previous example? It is a new family of wrapping operators that wrap around instead of growing their size. If you’ve used Spade you’ll be used to having to write trunc</code> a lot, which hurt readability. With wrapping operators, you can now write</p>
reg</span>(clk) value =</span> value +</span>. 1</span>;</code></pre>
instead of</p>
reg</span>(clk) value =</span> trunc(value +</span> 1</span>);</code></pre>
impl Trait</code> and return position type expressions</h2>
In the past, Spade has required adding some additional type parameters to generic functions just to be able to specify some additional types. What used to be</p>
fn</span> growing_op<</span>#uint</span> N, #uint</span> Out, Op></span>(x: int</span><</span>8</span>></span>, op: Op) -</span>></span> int</span><</span>Out></span>where</span> Out: {N +</span> 1</span>},      Op: Fn(int</span><</span>N></span>) -</span>></span> int</span><</span>Out></span>{    // ...</span>}</code></pre>
can now be written as</p>
fn</span> growing_op<</span>#uint</span> N></span>(x: int</span><</span>8</span>></span>, op: impl</span> Fn(int</span><</span>N></span>) -</span>></span> int</span><</span>{N+</span>1</span>}></span>) -</span>></span> int</span><</span>{N+</span>1</span>}></span> {    // ...</span>}</code></pre>
if let</code></h2>
When matching on an enum where you only want to unwrap one variant, a match</code> block becomes pretty verbose:</p>
let</span> unwrapped =</span> match</span> value {    Some</span>(val) =</span>></span> {        compute(val)    },    _ =</span>></span> 0</span>}</code></pre>
if let</code> allows writing this in a more readable way</p>
let</span> unwrapped =</span> if</span> let</span> Some</span>(val) =</span> value {    compute(val)} else</span> {    0</span>}</code></pre>
name @ pattern</code></h2>
Sometimes you may want to both look at the content of a pattern, and refer to the whole value at once. name @</code> syntax allows you to bind a sub-pattern to a name. For example, you can filter tuples to select only those whose elements have the same value like this:</p>
match</span> maybe_tuple {    Some</span>(tuple @ (left, right)) =</span>></span> if</span> left =</span>=</span> right {Some</span>(tuple)} else</span> {None</span>},    None</span> =</span>></span> None</span>}</code></pre>
Default Type Parameters</h2>
You can now specify default parameters for type expressions. This function</p>
fn</span> two_type_params<</span>#uint</span> N, #uint</span> M: 0</span>></span>()</code></pre>
can now be instantiated either as</p>
two_type_params::<</span>10</span>></span>()</code></pre>
or</p>
two_type_params::<</span>10</span>, 1</span>></span>()</code></pre>
verilog_attrs</code> on calls</h2>
When interacting with Verilog black boxes, it is sometimes necessary to add attributes to the instantiation. For example, when working with the ecp5 PLL block. You can now use #[verilog_attrs(...)]</code> on instantiations place Verilog attributes on the resulting Verilog instantiation.</p>
Type Aliases</h2>
You can now define type aliases like this:</p>
type i32 =</span> int</span><</span>32</span>></span>;</code></pre>
Super Traits</h2>
Super traits allow one trait to require another trait to also be implemented on a type. This is now supported in Spade as</p>
trait Eq: PartialEq {}</code></pre>
which says that for a type to implement the Eq</code> trait, PartialEq</code> has to be implemented first.</p>
#[inline]</code></h2>
You can now annotate units with #[inline]</code> to inline them instead of generating a Verilog instance. This can be useful when doing things like operator overloading where adding additional hierarchy would make debugging harder. It is also used internally in some cases by the compiler in order to avoid some performance issues during Verilog generation and subsequent reading by synthesis tools.</p>
Other changes</h2>


Added #[deprecated = "..."]</code> and #[deprecated(...)]</code> attributes that allow deprecating items.</p>
</li>

Added support for #bool</code> generic parameters and logical operations on them inside const generics</p>
</li>

Added inout<[T; N]>::read_write_items</code> to access inout</code> arrays element-wise</p>
</li>

Allow methods to be implemented on tuples</p>
</li>

Fixed incorrect behaviour when capturing a variable more than once in a lambda.</p>
</li>

Fixed warnings not being shown unless errors were produced too</p>
</li>

Reduce the chance of seeing Number<_> has no method <x></code> errors</p>
</li>

Fixed compiler panic when declaring variables inside pipelines using decl</code> syntax</p>
</li>

Automatically inline gen_if</code> temporary units</p>
</li>

Integer literals can now specify a type suffix with no size (e.g., 120u</code>, 33i</code>)</p>
</li>

gen if</code> expressions now can be written without an else</code> block</p>
</li>

Integer comparison operators <</code>, ></code>, <=</code> and >=</code> now can be used at the type level</p>
</li>

Start and end bounds on ..</code> range indexing are now optional, defaulting to 0</code> and the target array size</p>
</li>
</ul>


Spade 0.16.0
2026-01-22T00:00:00+00:00

Associated changelog</a>
Swim changelog</a>
Git</a>
DOI</a>
</div>
Today we are releasing Spade v0.16.0, a release packed with several improvements to several parts of the language.</p>
>10x Performance Improvement🔗</a></h1>
The compiler is now much faster than before. On one project the comile time went from "hours"  to 17 seconds, and on the project I used for benchmarking we see a 10x improvement in runtime.
While these projects are slight outliers, the compiler should be faster across the board.</p>
Our goal is for the compile time to be under one second for all projects, so if you encounter code that takes longer to compile, please get in touch so we can improve things further.</p>
Visibility markers🔗</a></h1>
Spade now supports visibility markers like pub</code> and pub(lib)</code>. Like public</code> and private</code> in most languages, this allows you as a library author to only expose parts of your library to the outside world.</p>
Import and Namespace System Improvements🔗</a></h1>
We have made several improvements to to the namespace system. You can now use</code> more than
one item in a single use statement</code>:</p>
use std::{array::{zip, interleave_arrays}, conv::transmute};
</code></pre>
You can also use self</code> and super</code> in namespaces to traverse the module tree</p>
Match Conditionals🔗</a></h1>
Match branches now support conditionals after the pattern, like so:</p>
impl Option<uint<8>> {
  fn inner_is_even(self) -> bool {
    match self {
      Some(val) if val & 1 == 1 => true,
      Some(_) => false,
      None => false
    }
  }
}
</code></pre>
Type Expressions in Traits🔗</a></h1>
For a long time, it has been impossible to write things like</p>
impl<T, #uint N> [T; N] {
  fn append(self, new: T) -> [T; {N + 1}] {
    self.concat([new])
  }
}
</code></pre>
instead, you had to introduce an additional type variable on the function. This restriction
has now been lifted and the above code now compiles!</p>
Syntax Changes🔗</a></h1>
We have made several changes to improve the Spade syntax. Most of these are simply warnings for now allowing you to gracefully migrate your projects</p>

The function traits that were previously written as Fn((Arg1, Arg2...), Out)</code> are now written as Fn(Arg1, Arg2..) -> Out</code></li>
Tuple indexing is now written as tuple.0</code> instead of tuple#1</code>, mimicking Rust</li>
</ul>
More Verilog Interoperability🔗</a></h1>
You can now annotate some things with #[verilog_attrs(..)]</code> which gets translated to (* ... *)</code> in the generated Verilog. This is useful for vendor primitives that need attributes for configuration.</p>
You can now also use r#ident</code> to write identifiers that conflict with Spade keywords, making it possible to interoperate with Verilog modules that, for example, use reset</code> as an input or output signal.</p>
Improved Self</code>🔗</a></h1>
Self</code> can now be used in more contexts in impl blocks. For example, you can now do</p>
enum Thing<T> {
  A,
  B{val: T}
}
impl Thing<uint<8>> {
  fn inner_eq(self, val: uint<8>) -> bool {
    match self {
      Self::A => false,
      Self::B(inner) => inner == val
    }
  }
}
</code></pre>
ASCII literals🔗</a></h1>
You can now write ascii char literals like b'a'</code> and b"This is a\nmulti line string"</code>. This is very useful when working with human readable strings, such as when sending things back and forth via UART, or when solving advent of code 😉 https://gitlab.com/TheZoq2/aoc2025</p>
Array Labels🔗</a></h1>
You can now add labels to arrays and refer to those labels later to get the corresponding indices. For example</p>
  Insn::Set(0, 0),
'loop_start
  Insn::Addi(0, 1),
  Insn::Branchi(0, Cond::Eq, 255, @loop_start.index)
</code></pre>
for more details on this, and how it can be used, see our previous blog post</a></p>
Thanks🔗</a></h1>
This release marks a small milestone for external contributions to Spade. Out of the 17 merge requests in the changelog, 12 of them are by José Miguel Sánchez García, making it the first release where Frans hasn't made the majority of the changes! Thanks José 🎉</p>


I Built a Processor for Advent of Code Day 8
2025-12-15T00:00:00+00:00
It may or may not have been a massive waste of time, but at least I had fun and get to showcase some fun things Spade can do! Especially the new labels that allow the Spade compiler to act as a rudimentary assembler.</p>
Advent of Code</a> is a yearly programming challenge where a new programming problem is unlocked every day starting on December 1. This year, a few of us are doing advent of code in hardware for Advent of FPGA</a> and of course this means I’m using Spade.</p>
I set myself the additional rule that as far as possible, everything</em> should be done in Spade, including input parsing, and until day 8 I had kept that streak up with only minor difficulties. However, day 8 this year was less suited to hardware solutions than previous problems, and honestly, after a week of solving similar problems I was starting to get a bit bored. For a while a thought had been brewing in the back of my mind that it is possible to build a simple CPU for a one-off instruction set using Spade’s enums</a>.</p>
So, armed with a problem being annoying to do in hardware, relatively simple in software, and this latest brainworm, I decided to try my hand at solving day 8 with a custom processor to maintain my 100% Spade streak.</p>
The Initial Processor</h2>
I had already prototyped</a> an enum-based processor for a guest lecture I gave in early november.</p>
That meant I could write the insturction set, processor like this:</p>
/// The definition of the instructions that the processor supports.</span>enum</span> Insn {    Nop,    Set{dest: uint</span><</span>4</span>></span>, value: uint</span><</span>16</span>></span>},    Add{dest: uint</span><</span>4</span>></span>, opa: uint</span><</span>4</span>></span>, opb: uint</span><</span>4</span>></span>},    Jump{target: int</span><</span>16</span>></span>},    Out{op: uint</span><</span>4</span>></span>}}</code></pre>
And then write a program for this processor like this</p>
/// The instruction memory containing the program to be executed. To fit in block-</span>ram this</span>/// has a single cycle read latency.</span>let</span> mem =</span> inst</span> std</span>::mem</span>::clocked_memory_init(clk, [], [    Insn</span>::Set$(dest: 0</span>, value: 0</span>),    Insn</span>::Set$(dest: 1</span>, value: 1</span>),    Insn</span>::Add$(dest: 0</span>, opa: 1</span>, opb: 0</span>),    Insn</span>::Out$(op: 0</span>),    Insn</span>::Jump$(target: 2</span>),    Insn</span>::Jump$(target: 0</span>)]);</code></pre>
The processor implementation is another hundred lines</a>, a bit too much for inlining in this blog post.</p>
Turning the Spade Compiler Into an Assembler</h2>
However, there was one annoying thing about this: All the jumps need hard-coded offsets and that makes writing any non-trivial program super annoying and error prone. After some brief discussion in the Spade Discord</a> we realized that we can solve that problem by adding labels to arrays. Just like an assembler, you can put a label before an array element, and then use that label to refer to its index later.</p>
Half an hour of implementation and another hour of syntax bike shedding later, Spade had support for this new feature</a> albeit with a placeholder syntax, meaning the previous example program can now be written as</p>
let</span> mem =</span> inst</span> std</span>::mem</span>::clocked_memory_init(clk, [], [    Insn</span>::Set$(dest: 0</span>, value: 0</span>),    Insn</span>::Set$(dest: 1</span>, value: 1</span>),  'loop    Insn</span>::Add$(dest: 0</span>, opa: 1</span>, opb: 0</span>),    Insn</span>::Out$(op: 0</span>),    Insn</span>::Jump$(target: @loop.index),]);</code></pre>
Fearlessly Extending the Processor</h2>
One of my favourite things about Spade is how it enables “fearless refactoring”. If you make a change, the compiler will yell at you to update all the places where the change may affect things. Take for example the instruction set above. It is clearly not enough for any real world tasks, so I had to add quite a few instructions to it.</p>
That means first extending the Insn</code> enum, for example with an Addi{dest: uint<4>, opa: uint<4>, value: uint<32>}</code> instruction</p>
Now the compiler will complain about all the places where this new instruction is not handled, for example, in the ALU:</p>
// Perform any computation the instruction requires</span>let</span> alu_out =</span> match</span> insn {    Insn</span>::Nop =</span>></span> std</span>::undef</span>::undef(),    Insn</span>::Set$(dest: _, value: _) =</span>></span> std</span>::undef</span>::undef(),    Insn</span>::Add$(opa: _, opb: _, dest: _) =</span>></span> trunc(reg_a +</span> reg_b),    Insn</span>::Jump(_) =</span>></span> std</span>::undef</span>::undef(),    Insn</span>::Out(_) =</span>></span> std</span>::undef</span>::undef(),};</code></pre>
Adding supprt for Addi</code> here is simple, I just had to add an additional branch</p>
    Insn</span>::Add$(opa: _, opb: _, value) =</span>></span> trunc(reg_a +</span> value),</code></pre>
And repeating for the other match</code> expressions in the processor I ended up with a slightly more powerful processor without putting too much thought into it!</p>
This is also very helpful when adjusting instructions. If I realized that the parameters to any instruction were not ideal, I could just change it in the definition, and the compiler would tell me where to update, both in the processor and also in the program</strong> thanks to the assembler just being the Spade compiler!</p>
All in all, this worked really well, while I of course had minor bugs from getting things wrong, I was able to build up my processor to quite a few instructions: which s which s</p>
enum</span> Insn {    Nop,    Set{dest: uint</span><</span>5</span>></span>, value: uint</span><</span>72</span>></span>},    Move{dest: uint</span><</span>5</span>></span>, source: uint</span><</span>5</span>></span>},    Add{dest: uint</span><</span>5</span>></span>, opa: uint</span><</span>5</span>></span>, opb: uint</span><</span>5</span>></span>},    Addi{dest: uint</span><</span>5</span>></span>, opa: uint</span><</span>5</span>></span>, value: uint</span><</span>72</span>></span>},    Mul{dest: uint</span><</span>5</span>></span>, opa: uint</span><</span>5</span>></span>, opb: uint</span><</span>5</span>></span>},    Div2{dest: uint</span><</span>5</span>></span>, opa: uint</span><</span>5</span>></span>},    Inc{dest: uint</span><</span>5</span>></span>},    Dec{dest: uint</span><</span>5</span>></span>},    ReadCoord{dest: uint</span><</span>5</span>></span>, source_addr: uint</span><</span>5</span>></span>},    SqDist3d{dest: uint</span><</span>5</span>></span>, opa: uint</span><</span>5</span>></span>, opb: uint</span><</span>5</span>></span>},    Jump{target: uint</span><</span>16</span>></span>},    JumpAndLink{target: uint</span><</span>16</span>></span>, dest: uint</span><</span>5</span>></span>},    JumpReg{target: uint</span><</span>5</span>></span>},    Branch{target: uint</span><</span>16</span>></span>, opa: uint</span><</span>5</span>></span>, cmp: Cmp, opb: uint</span><</span>5</span>></span>},    Out{op: uint</span><</span>5</span>></span>},    Outi{value: uint</span><</span>72</span>></span>},    GetNumCoords{dest: uint</span><</span>5</span>></span>},    WaitParsingDone,    ReadMem{dest: uint</span><</span>5</span>></span>, source: uint</span><</span>5</span>></span>},    ReadMemOffset{dest: uint</span><</span>5</span>></span>, offset: uint</span><</span>15</span>></span>, addr: uint</span><</span>5</span>></span>},    WriteMem{dest_addr: uint</span><</span>5</span>></span>, dest_value: uint</span><</span>5</span>></span>},    WriteMemOffset{dest_addr: uint</span><</span>5</span>></span>, offset: uint</span><</span>15</span>></span>, dest_value: uint</span><</span>5</span>></span>},    Halt,}</code></pre>
In addition, I was able to make late large scale changes when I realized I had failed to account for some things. For example, I doubled the number of registers in the processor, and increased the native word length from 48 to 72 bits without causing any existing code to fail!</p>
So Far, So Good</h2>
Until now, everything has gone well! Spade did what it was supposed to, the new labels meant writing “assembly” in Spade was pretty comfortable, and I didn’t run into any hard to track down bugs in the processor! However, as it turns out solving a second week advent of code problem in assembler comes with some difficulties. Word lengths had to be massive, my naive solution needed N^2 memory and did not end up fitting in block RAM for the ECP5 FPGA I was going to run this on, and I misread the problem description at least twice. In addition, many of these problems only appeared for larger inputs which meant 500k clock cycles of simulation just to reproduce issues. I also uncovered a bug in the Spade Surfer plugin which meant that the instruction decoding that had been extremely pleasant to work with initially broke for long simulations, making debugging quite pleasant.</p>
In the end, through painful debugging and comparing my results to the result of a friend’s python solution I eventually found all the bugs and earned that, sweet sweet silver star</em>.</p>
And the runtime was only around 3 minutes. Here at Spade inc we have gone past hardware accceleration and are fast at work on revolutionary hardware decceleration</em>!</p>
Conclusions</h2>
While this is probably not the best way to solve an advent of code problem, being able to define and program an ad-hoc processor like this is something I’m excited to have in the Spade toolbox, and I’m very pleased that the fearless refactoring that Spade provides extended to this technique.</p>
I believe this will come in handy for “management tasks” where the task is “programmatically complicated” but where preformance isn’t top priority.</p>
You can find all the source code for this project in my advent of code repo</a></p>


Spade 0.15.0
2025-11-20T00:00:00+00:00

Associated changelog</a>
Swim changelog</a>
Git</a>
DOI</a>
</div>
It is finally time for Spade v0.15.0 🎉. Like the previous release, this one is also delayed from our usual 6 week release schedule, but this time it also means that the release is unusually big!</p>
More powerful Lambda units🔗</a></h1>
In the last update, we introduced lambda</code> functions and some corresponding utilities in the standard library. In this update we're lifting two significant limitations on the lambda functions</p>
Captures🔗</a></h2>
Lambdas can now "capture" variables from their environment which allows you to do things like</p>
fn fir_filter(x: Option<uint<8>>, n: uint<8>) -> Option<uint<9>> {
  // Capture the `n` parameter in this scope and use it inside the lambda.
  x.map(fn |x| {x + n})
}
</code></pre>
Pipelines🔗</a></h2>
Lambdas can now be pipelines. The primary use case for this is transformations of data
that spans multiple clock cycles, where you want to preserve things like validity. For example:</p>
pipeline(3) pipelined_multiplier(val: Option<(int<18>, int<18>)>) -> Option<int<36>> {
  val
    .inst(_) pmap(pipeline(3) |(x, y)| {
      let result = x * y;
    reg * 3;
      result
    })
}
</code></pre>
New syntax🔗</a></h2>
The syntax for defining lambdas has been changed from fn (a, b) ...</code> to fn |a, b|</code> to more closely align with Rust.</p>
Pipeline methods🔗</a></h1>
Previously, methods were limited to entities and functions, but now you can
also implement pipeline methods. For example, you can now make the read mehtod
on memories a method, making it nicer to use in things like method chains.</p>
struct port MemoryReadPort<T> {
  addr: inv &uint<16>,
  data: &T
}

impl MemoryReadPort {
  pipeline(1) read(self, clk: clock, addr: uint<16>) {
    set self.addr = addr;
  reg;
    *self.data
  }
}

// Before
inst(1) read_memory(clk, read_port)
// Now
read_port
  .inst(1) read(clk)
</code></pre>
Inferred pipeline depth🔗</a></h1>
When instantiating pipelines, it is now possible to use inst(_)</code> to infer the depth of the instantiated pipeline.</p>
Transitive dependencies🔗</a></h1>
Until now, if multiple libraries depended on the same library in a project, values could not be passed between them despite ostensibly being of the same type. With this release, swim</code> now allows this allowing more complex projects to be built.</p>
Note that this comes with a minor caveat that only one version of each library will be used throughout the project.</p>
Standard library improvements🔗</a></h1>
The standard library has received several new additions in this release</p>

zip</code> on arrays joins two arrays together element by element ([a, b].zip([c, d])</code> becomes [(a, c), (b, d)]</code>)</li>
interleave</code> interleaves the elements of two arrays ([a, b].interleave([c, d])</code> becomes [a, c, b, d]</code>)</li>
pmap</code> on the Option</code> type behaves like map</code>, but with a pipeline instead of a function</li>
The memory ports in the standard library now have .read</code> and .write</code> methods instead of the now legacy read_read_port</code></li>
</ul>
Improvements to External Verilog🔗</a></h1>
The language now supports type level strings, for example</p>
fn tlstring<#str message>() {...}
</code></pre>
while they don't do anything in Spade, they are very useful when interfacing with external
Verilog modules which often take strings as configuration parameters, for example, PLLs https://gitlab.com/TheZoq2/spade-sdram/-/blob/959b1cb17357aea591e5a4870f316027e6bae423/hwtest_tangnano20k/src/pll.spade</a></p>
With this change, nearly every Verilog module is instantiatable from Spade, the only thing missing as far as we know is being able to add Verilog attributes to instances which is also used by some PLLs.</p>
Unsafe🔗</a></h1>
In the past, a few methods in the standard library were in an unsafe</code> namespace because they violate some guarantees that spade provide and assume to be true. In particular, Spade does not allow you to create a value of a type with a bit pattern that isn't valid for that specific type. In some cases, you know what you are doing and want to work around such a constraint, which is when you want to use an "unsafe" function.</p>
With 0.15, we're adding an unsafe</code> keyword which you can add as a label on a unit</code>, like the transmute</code> function in the standard library</p>
/// Reinterpret the bits of `t` as an `O`
unsafe fn transmute<T, O>(t: T) -> O {/* */}
</code></pre>
unsafe</code> functions can only be called in the newly introduced unsafe</code> blocks</p>
let reinterpreted: uint<16> = unsafe { transmute((uint<8>, uint<8>)) }
</code></pre>
which allows you to quickly find all instances of potentially dangerous code.</p>
As the language evolves in the future to provide more guarantees, such as clock domains, unsafe</code> functions will become more important.</p>
Improved inout</code> support🔗</a></h1>
The inout<T></code> type has also seen some improvements, including a new read_write_inout</code> for interacting with them inside Spade.</p>
Changes to set</code>🔗</a></h1>
The set</code> statement now requires the right hand side to be a wire. This allows the use set</code> on inv clock</code>. Existing code needs to be patched to replace set x = y;</code> with set x = &y;</code></p>
Structs and enums in const</code> scenarios🔗</a></h1>
You can now use structs and enums in places which expect compile time values, most importantly clocked_memory_init</code>.</p>
Automatic Surfer integration🔗</a></h1>
swim</code> will now download or compiler the Surfer integration plugin making the Spade integration seamless. If you have not used Surfer with Spade integration yet, make sure to install the latest Surfer and swim versions to take advantage of this.</p>
Mac support for install-tools</code>🔗</a></h1>
The swim</code> subcommand for installing the oss-cad-suite now works on Mac, making initial setup easier.</p>
Contributors🔗</a></h1>
This release contains contributions from Astrid Lauenstein, DasLixou, Ethan Uppal, José Miguel Sánchez García, and Oscar Gustafsson making it the release with the largest number of contributors to date, thanks everyone!</p>


Quickscope — A quick, but not dirty Integrated Logic Analyzer
2025-11-10T00:00:00+00:00
How long would it take you to write an integrated logic analyzer? With Spade,
I was able to do it in around 3 hours and less than 100 lines of code! In this
post I will describe how it works.</p>
Since the code is relatively short, we can put all of it here. Don't worry, we'll
walk through the whole thing together one piece at a time, but this gives a brief overview</p>
use ready_valid::Rv;

entity quickscope<T, #uint NumBytes, #uint SampleBuffer>(
    clk: clock,
    rst: bool,
    trigger: bool,
    data: T,
) -> Rv<uint<8>> {
    let empty = port;
    let full = port;

    reg(clk) triggered reset (rst: false) = {
        match (triggered, *empty#0, *full#0) {
            // We only trigger if the fifo is empty
            (false, true, false) => trigger,
            // If the fifo is full, we un-trigger, i.e. we stop feeding more samples
            // into the FIFO
            (true, _, true) => false,
            // In any other case, we keep the trigger state
            (_, _, _) => triggered
        }
    };
    let triggered_now = inst std::io::rising_edge(clk, trigger);

    let data_in = if triggered { Some(data) } else { None };

    Rv(&data_in, full#1)
        .inst fifo_buffer::<SampleBuffer>(clk, rst)
        .read_empty(empty#1)
        .data
        .inst map(fn (sample) {
            unsafe{ std::conv::transmute::<_, [uint<8>; NumBytes]>(sample) }
        })
        .inst into_element_stream(clk, rst)
        .inst map(fn (byte) { ready_valid::escape_byte::Escaped::Yes(byte) })
        // Emit end of packet header
        .inst append_lower_priority(
            inst emit_once(clk, rst, if triggered_now {Some([0xff, 0x01])} else {None})
                .inst into_element_stream(clk, rst)
                .inst map(fn (byte) {ready_valid::escape_byte::Escaped::No(byte)})
        )
        // Emit start of packet header
        .inst append_higher_priority(
            inst emit_once(clk, rst, if triggered_now {Some([0xff, 0x00, NumBytes])} else {None})
                .inst into_element_stream(clk, rst)
                .inst map(fn (byte) {ready_valid::escape_byte::Escaped::No(byte)})
        )
        .inst escape_bytes$(
            clk,
            rst,
            escapees: [0xff, 0xfe],
            escape_fn: fn (byte) {byte ^ 0x80},
            escape_prefix: 0xfe,
        )
}

impl<T, #uint N> Rv<[T; N]> {
    entity into_element_stream(self, clk: clock, rst: bool) -> Rv<T>{
        let Rv(data, ready) = self;
        let ds_ready = port;
        reg(clk) (array, num_left): ([T; N], uint<{uint_bits_to_fit(N)}>) reset(rst: (std::undef::undef(), 0)) =
            match (*data, num_left, *ds_ready#0) {
                (Some(data), 0, _) => (data, N),
                (_, _, false) => (array, num_left),
                (None, 0, _) => (array, num_left),
                (Some(data), 1, _) => (data, N),
                (_, _, _) => (array[1..N].concat([std::undef::undef()]), trunc(num_left-1))
            };

        set ready = &(num_left == 0 || num_left == 1 && *ds_ready#0);

        Rv(
            &match num_left {
                0 => None,
                _ => Some(array[0]),
            },
            ds_ready#1
        )
    }
}

entity emit_once<T>(clk: clock, rst: bool, value: Option<T>) -> Rv<T> {
    let ds_ready = port;
    reg(clk) to_emit reset(rst: None) = match (to_emit, *ds_ready#0, value) {
        (None, _, Some(new)) => Some(new),
        (None, _, None) => None,
        (Some(value), true, None) => None,
        (Some(value), true, Some(new)) => Some(new),
        (Some(value), false, _) => None
    };

    Rv(&to_emit, ds_ready#1)
}
</code></pre>
The source code for the whole project including the client is available at https://gitlab.com/TheZoq2/quickscope/</a>.</p>
External Interface and Use🔗</a></h2>
The first line: use ready_valid::Rv</code> is perhaps the most important line in the entire thing. It imports the Rv</code> type from a library called ready_valid</code>. As the name implies, this provides a type for ready/valid interfaces with a ton of functions for working with it. As we will see, this is what does most of the heavy lifting here.</p>
Next, we define the interface to the logic analyzer:</p>
entity quickscope<T, #uint NumBytes, #uint SampleBuffer>(
   clk: clock,
   rst: bool,
   trigger: bool,
   data: T,
) -> Rv<uint<8>> { 
</code></pre>
First, are a few generic parameters:</p>

T</code>: The type of the data samples we want to analyze. Since it is generic, we can give any Spade type we want and it will work.</li>
#uint NumBytes</code>: The number of bytes required to store the samples. (This is required because Spade currently does not have something like sizeof</code>, but the compiler ensures that the number is correct)</li>
#uint SampleBuffer</code>: The number of samples we want to fit in the sample FIFO</li>
</ul>
Next are the signals going into the analyzer:</p>

clk</code> and rst</code> should be self-explanatory</li>
trigger</code>: When this is true, the analyzer will trigger and send a batch of consecutive samples</li>
data</code>: The data we want to analyze</li>
</ul>
Finally, is the output of the entity is Rv<uint<8>></code>: An 8-bit integer wrapped in a
ready/valid interface. This means that the raw bytes that this outputs can be
handled by anything that can consume ready/valid bytes, for example a UART
device, a UDP streamer, or whatever you can dream up.</p>
In use, this means that we can use quickscope</code> by simply instantiating it with the data of interest, for example:</p>
inst quickscope::quickscope::<_, 11, {65536 / 8}>(
         clk,
         rst,
         // Trigger signal
         state.is_read(),
         // The data we want to analyze, here we're passing quite a large structure
         (
             state,
             DramPins$(
                 dq_out: (*pins.dq_out).map(fn (val) {trunc(val)}),
                 dq_in: (*dq_read).map(fn (val) {trunc(val)}),
                 a: *pins.a,
                 ba: *pins.ba,
                 n_we: *pins.n_we,
                 n_ras: *pins.n_ras,
                 n_cas: *pins.n_cas,
     
             ),
             value_expected_pairs.map(fn ((v, e)) {(trunc::<_, uint<10>>(v[0]), trunc::<_, uint<10>>(e[0]))}),
             is_ok,
             is_expected,
         )
     )
     // In principle, we can transmit the bytes with anything, but the client currently only works
     // with uart so let's use that
     .inst into_uart(
         clk,
         rst,
         protocols::uart::UartConfig$(bit_time: 234, parity: false, stop_bits: 2),
         uart_txp,
     );
</code></pre>
With this unit instantiated and uploaded to our FPGA, we can run quickscope /dev/ttyUSB0 115200</code> which will wait for a trigger, then write a .vcd</code> file with the resulting samples. Finally, we can open the .vcd</code> in surfer</code> which, since it has Spade integration, will show the traced signals as a hierarchical structure. Here is a simple example of how that looks:</p>
</p>
Overall Architecture🔗</a></h2>
The architecture of the scope is relatively straight forward: the primary piece is a FIFO where samples are stored before being exfiltrated via whatever byte consumer is used. When the scope triggers, this FIFO starts filling up until it reaches its maximum capacity. Since the samples are not single bytes, some logic is required to convert the samples into bytes and stream them out, all of which is orchestrated by ready-valid interfacing.</p>
There is one more thing that must be dealt with: we want to make sure that the client can see the start and end of triggers, and ensure that the data is contiguous, i.e. one batch of data comes from only a single sample. This is done by only allowing triggering when the FIFO is completely empty, and inserting headers for the start and end of data.</p>

The rest of the blog post will go through how this architecture is implemented, but you may want to go back to the big source code listing to see how much of it you can infer without any additional context.</p>
</blockquote>
Implementation🔗</a></h2>
The first part of the implementation deals with triggering:</p>
let empty = port;
let full = port;

reg(clk) triggered reset (rst: false) = {
    match (triggered, *empty#0, *full#0) {
       // We only trigger if the fifo is empty
       (false, true, false) => trigger,
       // If the fifo is full, we un-trigger, i.e. we stop feeding more samples
       // into the FIFO
       (true, _, true) => false,
       // In any other case, we keep the trigger state
       (_, _, _) => triggered
    }
};
</code></pre>
The first two lines define empty</code> and full</code> which we will connect to the sample FIFO later.
Next is the trigger logic which looks at the trigger</code>
signal and the state of the FIFOs in order to start pushing samples into the
FIFO. Once the analyzer is triggered, we leave it triggered until the FIFO is
full at which point we have</em> to stop, otherwise we will get gaps in our
samples. We're not quite done yet however, we prevent triggering again until
the FIFO is empty again, in order to ensure that each batch of samples is contiguous and separated with a header/footer.</p>
For now, let's skip the triggered_now</code> signal.</p>
let triggered_now = inst std::io::rising_edge(clk, trigger);
</code></pre>
Next, we use the triggered</code> signal in order to define a data_in</code> signal as
Some(data)</code> when triggered, and None</code> when not. Some</code> and None</code> are the
Spade way to write data with valid signals.</p>
let data_in = if triggered { Some(data) } else { None };
</code></pre>
Next, this data is wrapped in an Rv</code>, a ready/valid interface where we connect the ready signal to the full</code> signal we defined earlier. With this, we can push samples into a FIFO</p>
Rv(data_in, full#1)
    .inst fifo_buffer::<SampleBuffer>(clk, rst)
</code></pre>
On the read side of the FIFO, there are quite a few method instantiations:</p>
    .read_empty(empty#1)
    .data
    .inst map(fn (sample) {
       unsafe{ std::conv::transmute::<_, [uint<8>; NumBytes]>(sample) }
    })
    .inst into_element_stream(clk, rst)
</code></pre>
First, we connect the empty</code> signal we defined earlier to the empty signal of the FIFO. Next, we take the samples, which can have any type, and transform them into an array of bytes. Since arbitrary transformations of data is something one should be careful about, Spade requires this operation to be done inside an unsafe</code> block, indicating that extra care is required.
The final method in this block is the .into_element_stream</code> method. It transforms a ready/valid-interface of an array with N elements Rv<[T; N]</code> into one of single array elements, T</code>. Here, T</code> is uint<8></code>, i.e. a byte.</p>
While we could simply send these bytes straight off to the host, the hosts job becomes easier if it receives start and end headers, which is what the next piece of code does:</p>
.inst map(fn (byte) { ready_valid::escape_byte::Escaped::Yes(byte) })
// Emit end of packet header
.inst append_lower_priority(
    inst emit_once(clk, rst, if triggered_now {Some([0xff, 0x01])} else {None})
        .inst into_element_stream(clk, rst)
        .inst map(fn (byte) {ready_valid::escape_byte::Escaped::No(byte)})
)
// Emit start of packet header
.inst append_higher_priority(
    inst emit_once(clk, rst, if triggered_now {Some([0xff, 0x00, NumBytes])} else {None})
        .inst into_element_stream(clk, rst)
        .inst map(fn (byte) {ready_valid::escape_byte::Escaped::No(byte)})
)
.inst escape_bytes$(
    clk,
    rst,
    escapees: [0xff, 0xfe],
    escape_fn: fn (byte) {byte ^ 0x80},
    escape_prefix: 0xfe,
)
</code></pre>
To do this unambiguously we want to have a few values we can use for these control signals. The escape_bytes</code> method at the end of the chain allows us to do this. We pass it a list of escapees</code> which we do not want to see in the data stream. Next, we give it an escape_fn</code> which is used to transform any of the escapee</code> bytes when encountered, here we flip the most significant bit. Of course, now we have duplicate bytes, both 0xff</code> and 0x7f</code> will result in 0x7f</code>, so we insert an escape_prefix</code> before any escaped byte.</p>
Of course, we do not want to escape any headers, only data, so the first method in the chain marks the raw data as bytes to escape.</p>
This leaves two method calls, apped_lower_priority</code> and
append_higher_priority</code>, which as the names imply, put data into the stream
with different priorities. The emit_once</code> instances create Rv</code> streams with
some headers if the scope was triggered now</em>, and since these are headers they
are wrapped in Escaped::No</code>.
The effect of all this logic is that once triggered, all three streams will
have data. The highest priority stream containing the headers will emit its
bytes first, then the main data stream which has higher priority will emit its
data, and only once that is done will the lowest priority "footer" be emitted.</p>
Wait, is this HLS?🔗</a></h2>
A natural question that often arises when talking about Spade is "Wait, is this high level synthesis?", there sure are a lot of high level things going on here. The answer is no. While things like method chains on ready/valid interfaces allow a pretty high level description of the architecture, behind each method is some RTL level description that you have full control over. An example of this is the .into_element_stream</code> method which we used earlier. It transforms a ready/valid-interface of an array with N elements Rv<[T; N]</code> into one of single array elements, T</code>. Most methods used in the project are implemented in the ready_valid</code> library, but this one is defined in the quickscope project itself, in the</p>
impl<T, #uint N> Rv<[T; N]> {
    entity into_element_stream(self, clk: clock, rst: bool) -> Rv<T>{
</code></pre>
block. The details here are not super interesting to talk about, it is essentially an FSM that pulls one value from the upstream stream, then emits each element in turn, before pulling another element</p>
Rv</code> ecosystem🔗</a></h2>
This project clearly leans heavily on that Rv</code> library which you can find at https://gitlab.com/spade-lang/lib/ready_valid</a>. For this project, I ended up adding a few more features to that library, as well as moving a few utilities I wrote elsewhere into the "mainline" project. Being able to have a set of reusable components like this is a big enabler for projects like this, and requires support both from the build tool for dependency management, and from the language which must be able to write generic and re-usable libraries.</p>
The client🔗</a></h2>
The client is less interesting to discuss here, and even took longer to write than the hardware implementation. If you are curious, the source code is available at https://gitlab.com/TheZoq2/quickscope/-/tree/main/client?ref_type=heads</a></p>


Spade 0.14.0
2025-06-26T00:00:00+00:00

Associated changelog</a>
Swim changelog</a>
Git</a>
DOI</a>
</div>
After a brief hiatus while Frans finished his PhD thesis, we are finally
releasing Spade 0.14.0. This includes long awaited support for lambda
functions, standard library features to go along with that, and, a much more
usable LSP implementation that will no longer bail on the first error.</p>
Lambda functions🔗</a></h1>
Lambda functions are "anonymous" functions that are written in-line where they are used. Their primary use case is to specify transformation on data contained in "containers" like arrays and the Option</code> type.</p>
For example, to add one to the value inside an Option</code> type, you could write</p>
match value {
  Some(inner) => Some(inner + 1),
  None => None
}
</code></pre>
With lambda functions, you can now use the map</code> function instead</p>
value.map(fn (inner) {inner + 1})
</code></pre>
which is much more concise, and chainable. In addition, the map function can be implemented on many types including arrays and the ready valid Rv</code> type, allowing you to change the container without affecting the computation being performed.</p>
The definition of the map function on Option</code> looks like this</p>
impl<T> Option<T> {
  fn map<F, O>(self, f: F)
  where F: Fn((T), O)
  {
    match value {
      Some(inner) => Some(f.call((inner,))),
      None => None
    }
  }
}
</code></pre>
I.e. lambda functions are just values which implement the Fn</code> trait which has a .call</code> method.</p>
Standard library additions🔗</a></h1>
With lambda functions implemented, the standard library has gained a few new "combinator" functions that make use of this new functionality</p>

Option</code> and [T; N]</code> now have a map</code> function</li>
Option</code> now has an and_then</code> function</li>
[T; N]</code> now has zip</code> for joining two arrays pair-wise and concat</code> for concatenating them together.</li>
Option</code> now has unwrap_or</code>, unwrap_or_undef</code> for getting the inner value out of the option without a match block</li>
Option</code> now has sliding_window</code> for keeping around the last N</code> values.</li>
The new std::undef::undef</code> function allows you to create an undefined value (currently X</code> in the Verilog backend)</li>
</ul>
Language Server Protocol and Error Recovery🔗</a></h1>
The Spade language server has supported inline errors, go to definition and hover for quite a while, but the compiler has been to eager to error out on the first sign of trouble making the LSP relatively useless. With 0.14.0, this is now much improved allowing the LSP to keep up.</p>
In addition, the hover information has been improved. You can now see the types of variables and expressions when hovering over them, function signatures and documentation are shown for both functions and methods, and the inferred output type of methods is also shown on hover</p>
These mastodon posts have a few examples of this functionality:</p>

https://mastodon.social/@thezoq2/114649713513195455</li>
https://mastodon.social/@thezoq2/114647080504928422</li>
https://mastodon.social/@thezoq2/114647085989178649</li>
</ul>
Surfer WebAssembly plugin🔗</a></h1>
The integration with Surfer has long been in the source tree of surfer</code>, requiring you to match your Surfer version with your Spade version. On the latest surfer version, it can now load web assembly plugins, so the Spade integration has been moved out into that system.</p>
For now, this requires manual installation, by running install.bash</code> in the spade-surfer-plugin</code> directory, but automated install will be added to swim soon.</p>
Surfer name translation🔗</a></h1>
The Spade compiler produces anonymous names _e_...</code> for any intermediate signals it creates. As more and more functionality in Spade is written using more complex expressions like methods, this becomes hard to debug. With this update, Surfer can translate these names back to their source code location, allowing you to view signals not only for your named variables, but also intermediate expressions.</p>
Functions can now contain wires🔗</a></h1>
Previously, the language did not allow &</code> or inv &</code> in functions. This ended
up being too restrictive as it is entirely possible to write combinatorial
functions using them. This restriction is now lifted.</p>


Spade 0.13.0
2025-02-20T00:00:00+00:00

Associated changelog</a>
Swim changelog</a>
Git</a>
DOI</a>
</div>
Today we're releasing Spade 0.13, one of the biggest Spade releases yet! It
includes gen if</code> for compile time conditionals and recursion, lots of
namespacing fixes, improvements to handling external Verilog, and lots more.</p>
gen if</code>🔗</a></h1>
gen if</code> allows you to conditionally branch based on type parameters. The primary use
case for this is recursively iterating over arrays. For example, you can now write
a function that adds one to every element in an array like this</p>
fn add_one<#W, #N>(x: [int<W>; N]) -> [int<{W+1}>; N] {
  gen if N == 0 {
    []
  } else {
    [x[0] + 1] `concat_arrays` add_one(x[1:N])
  }
}
</code></pre>
While this is useful for some things in isolation, it is going to lay the
groundwork for more complex generic constructs in later releases, especially
once lambdas are implemented.</p>
Interacting with external Verilog🔗</a></h1>
This release changes the syntax of the old __builtin__</code> marker to extern</code> to make
it less hacky and more clear what it does. The #[no_mangle]</code> attribute has also
been given a all</code> parameter which blanket applies #[no_mangle]</code> to all parameters.</p>
What used to look like this:</p>
entity external_verilog(
  #[no_mangle] clk: clock,
  #[no_mangle] a: uint<8>,
  #[no_mangle] b: uint<8>,
  #[no_mangle] out: inv &uint<8>
) __builtin__
</code></pre>
now looks like this</p>
#[no_mangle(all)]
extern entity external_verilog(clk: clock, a: uint<8>, b: uint<8>, out: inv &uint<8>);
</code></pre>
Including external Verilog in Swim has also been improved, there is now a
[verilog]</code> and [synthesis.verilog]</code> section in swim.toml</code> which allows you
to both include specific Verilog files, and specify include directories.</p>
You can now also use where</code> clauses on extern units.</p>
Thanks to Ethan</a> for all these changes!</p>
Namespacing changes🔗</a></h1>
The namespacing system has seen several improvements in this release. The most user
facing change is that all modules now need a main.spade</code> at the root of the module,
and for other files to be included in the project, you need to add mod filename;</code> to
the corresponding main.spade</code>. For rust users, this will feel very familiar, what rust calls
main.rs</code>, lib.rs</code> and mod.rs</code> are all called main.spade</code>.</p>
The namespace of the main.spade</code> file has also changed, a main.spade</code> with</p>
fn a() {}
</code></pre>
in a project called project</code> would previously result in project::main::a</code>, now it
results in project::a;</code></p>
There have also been several bug fixes and improvements in the name resolution system including</p>

use</code> statements of undefined names now error on the use</code> instead of when using the use</code>d name.</li>
use</code> between namespaces now works as expected</li>
No more stack overflows or infinite recursion if use</code>-ing a single identifier</li>
</ul>
Thanks to DasLixou</a> for most of these fixes!</p>
Expressions are now statements🔗</a></h1>
If you wanted to call a unit with "side effects" previously, you would have had to write</p>
let _ = inst unit(some_port);
</code></pre>
now you can just write</p>
inst unit(some_port);
</code></pre>
Improved const generics🔗</a></h1>
You can use const generics in unit parameter and output types, which means you no longer
have to add "internal" type parameters and where</code> clauses. For example, you can now
write</p>
fn weird_operation<#uint N>(a: uint<N>, b: uint<{N+5}>) -> uint<{N/2}> {}
</code></pre>
Synchronous Resets🔗</a></h1>
Spade now uses synchronous resets for all registers instead of asynchronous.</p>
Other fixes🔗</a></h1>
There have also been numerous small fixes and improvements that don't fit in
this blog post, you can read them all in the
Changelog</a></p>
SPADETID!🔗</a></h1>
Frans has started regularly streaming Spade development on
https://www.twitch.tv/thezoq2/</a>. If you want
to be notified when this happens, you can join the
discord</a> and give yourself the SPADETID</code> role.</p>


Spade 0.12.0
2025-01-09T00:00:00+00:00

Associated changelog</a>
Swim changelog</a>
Git</a>
DOI</a>
</div>
Happy new year everyone! Today we're releasing Spade 0.12.0. All in all, this is quite a
boring release (in a good way) that mostly fixes a ton of bugs, but there are some new features too.</p>
Swim changes🔗</a></h1>
The build tool has seen quite a few nice improvements in this release</p>
Gowin support🔗</a></h2>
Gowin FPGAs are now supported by swim which makes using Spade on one as simple as</p>
swim init --board tangnano9k
</code></pre>
If you have one of these FPGAs lying around, now is a great time to try Spade!</p>
Less Chatty Swim Output🔗</a></h2>
Swim will now only print output from commands that fail or those that end up
running for more than a few seconds. This makes it easier to filter out the
unimportant parts of the log, and it looks a bit cleaner. You can see it in
action here: [https://asciinema.org/a/j9HRvwzAWnoFBVCt4Zj8wM2LE]</p>
Other Swim changes🔗</a></h2>
If you use swim install-tools</code> we now use a bleeding edge oss-cad-suite</code>
again. Beyond enabling the gowin support, this should give a nice improvement
in performance thanks to improvements in yosys and nextpnr that we've been
missing out on due to the pinned cad suite.</p>
Methods on Arrays and Wires🔗</a></h1>
You can now add methods to arrays and wires. This is of course useful in user
code, and also allows us to add some missing conversion functions to the
standard library.</p>
You can now use .to_int()</code> and .to_uint()</code> on arrays of bools ([bool; N]</code>),
where you previously had to use bits_to_int()</code> and bits_to_uint()</code></p>
Bug Squashing🔗</a></h2>
We've fixed quite a few bugs with this release. A lot of them related to
compiler panics or miscompilations when writing zero size types.</p>

Fix a few codegen bugs around enums with 1 variant and no members</li>
Fix codegen bug when matching on zero size literals</li>
Fix codegen bug when using zero size integers</li>
</ul>
Beyond fixing these specific cases, we've made the handling of zero size
types much more robust to errors since that has been a source of nasty bugs.</p>
We fixed another nasty codegen bug that has been around for a while when
indexing nested inverted wire structures</p>
We also fixed a few errors with patterns</p>

Report error when integer patterns are out of bounds</li>
Fix panic when pattern matching arrays of integers with more than 4 elements</li>
</ul>
Verilog annoyingly requires special handing for arrays of single bit values.
This was missing from the code generator for memories which prevented the
synthesis tool from inferring memories for clocked_memory<bool></code>. This has now
been fixed</p>
Nearly all of these bugs were reported by users, so thanks to everyone that
has been trying out the language and reporting issues!</p>
Parser tweaks🔗</a></h2>
Finally, we made some small but important tweaks to the parser</p>
You no longer need to have a new line at the end of a line comment at the end of a file</p>
The compiler no longer allows non-block expressions in if branches.</p>
And finally, we adjusted the precedence of the dereference (*</code>) and bitwise
operators to make more sense and require fewer parenthesis.</p>


Spade 0.11.0
2024-11-27T00:00:00+00:00

Associated changelog</a>
Swim changelog</a>
Git</a>
DOI</a>
</div>
Today we're releasing Spade 0.11.0, a release which makes working with ports</em> a lot easier, among other things.</p>
&mut is dead, long live inv &🔗</a></h1>
Until this release, Spade had values (T</code>), wires (&T</code>), mutable wires (&mut T)</code> and inverted ports (~T</code>). Importantly ~&T</code> and &mut T</code> were effectively
the same thing, but did not mix well together. Mutable wires also required the
user of ugly intrinsic functions like new_mut_wire()</code> and read_mut_wire</code> for
creation and reading, while (T, ~T)</code> pairs could be created just by let (x, x_inv) = port</code>.</p>
With 0.11, we're cleaning up this mess. First &mut T</code> is gone, and ~&T</code> has been
fixed to work in all places that previously expected &mut T</code>. Second, in order to
avoid operator soup, the syntax of inverted types has changed to inv &T</code>.</p>
This is obviously a breaking change, but the compiler should tell you what you
need to change. Just replacing all &mut T</code> with inv &T</code> should be enough.</p>

These changes also have fresh documentation at https://docs.spade-lang.org/wires.html</p>
</blockquote>
Testing of ports🔗</a></h1>
With wires and ports being cleaned up, we also refactored the cocotb testbench wrappers
to make testing ports easier. Previously, if you wanted to test a function like</p>
impl IpStream {
    entity into_ethernet(
        self,
        clk: clock,
        rst: bool,
        source_mac: MacAddr,
        dest_mac: MacAddr,
    ) -> EthernetStream {
        let HeaderPayloadStreamO$(headers, bytes) = self
            .inner
            .inst lower(clk, rst, EthStreamLowerer$(source_mac, dest_mac));
        EthernetStream$(header: headers, payload: bytes)
    }

    entity buffer_header(self, clk: clock, rst: bool) -> IpStream {
        IpStream(self.inner.inst buffer_header(clk, rst))
    }
}
</code></pre>
You had to write a wrapper to turn all ports with inverted wires into non-inverted wires,</p>
struct IpStreamOut {
    eth_byte: Option<uint<8>>,
    headers_ready: bool,
    payload_ready: bool,
}

entity ip_stream_th(
    clk: clock,
    rst: bool,
    ip_headers: Option<IpHeader>,
    payload: Option<uint<8>>
) -> IpStreamOut {
    let headers_ready = inst new_mut_wire();
    let bytes_ready = inst new_mut_wire();
    let s = IpStream(HeaderPayloadStreamO(
        Rv(&ip_headers, headers_ready),
        Rv(&payload, bytes_ready),
    ));
    let out = s
        .inst into_ethernet$(
            clk,
            rst,
            source_mac: MacAddr([1,2,3,4,5,6]),
            dest_mac: MacAddr([11,12,13,14,15,16])
        )
        .inst into_ethernet_bytes(clk, rst);

    IpStreamOut$(
        eth_byte: match out {
            Some(b) => Some(b.inner),
            None => None
        },
        headers_ready: inst read_mut_wire(headers_ready),
        payload_ready: inst read_mut_wire(bytes_ready)
    )
}
</code></pre>
With the updates to 0.11, this is no longer necessary, you can now set values on inverted
inputs, and read values on inverted outputs directly from testbenches.</p>
(In this case, you still need a small wrapper because we don't directly support testing methods, but it is much less tedious to write)</p>
entity into_ethernet_th(
    _self: IpStream,
    clk: clock,
    rst: bool,
    source_mac: MacAddr,
    dest_mac: MacAddr,
) -> EthernetStream {
  _self.into_ethernet$(clk, rst, source_mac, dest_mac)
}
</code></pre>
Support for parametric Verilog🔗</a></h1>
Ethan Uppal</a> has added support for mapping Spade generics
to Verilog parameters when instantiating external Verilog.</p>
As a simple example, this means we can now directly instantiate</p>
module add_constant #(parameter int N = 0, parameter int M = 0) (
    input[7:0] in, 
    output[7:0] out
);
    assign out = in + N + M;
endmodule
</code></pre>
as</p>
mod extern {
    #[no_mangle]
    entity add_constant<#uint N, #uint M>(
        #[no_mangle] in: int<8>,
        #[no_mangle] out: inv &int<8>
    ) __builtin__
}

entity harness(input: int<8>, named: bool) -> int<8> {
  let (out, out_inv) = port;
  let _ = inst extern::add_constant::$<N: 1, M: 2>(input, out_inv);
  out
}
</code></pre>
This brings new exciting possibilities such as interop with the Berkeley
HardFloat</a> library.</p>
Parser Recovery🔗</a></h1>
Spade has long been plagued by the parser bailing out on the first error. With
this release, this has been improved so it can now do recovery in a lot of
cases.</p>
entity main() {
    not valid syntax
}

struct X {
    bool
}

enum Y {
    Variant(a)
}
</code></pre>
would previously fail on the first line with no more diagnostics, but now keeps going:</p>
error: Unexpected `identifier`, expected `}`
  ┌─ testinput:2:9
  │
2 │     not valid syntax
  │         ^^^^^ expected `}`

error: Unexpected `}`, expected `:`
  ┌─ testinput:7:1
  │
7 │ }
  │ ^ expected `:`

error: Unexpected `(`, expected `{`, `,` or `}`
   ┌─ testinput:10:12
   │
10 │     Variant(a)
   │            ^  
</code></pre>
Finally reporting around semicolons are now better to avoid the "unexpected X
expected ;" in confusing places, and we're now resistant to the infamous greek semicolon prank :)</p>
</p>
Const generics in arrays🔗</a></h1>
You can now use const generics in range index expressions and array shorthand initialization. This makes it possible to define a generic "shift register" of array elements</p>
entity sreg<#uint ISize, #uint N>(
  clk: clock,
  rst: bool,
  next: Option<int<ISize>>
) -> [int<ISize>; N]  {
  reg(clk) val reset(rst: [0; N]) = match next {
    Some(x) => val[1:N] `concat_arrays` [x],
    None => val,
  };
  val
}
</code></pre>
Test bench chattyness reduction🔗</a></h1>
The output of test benches is now much cleaner</p>

There is no longer excessive indentation on messages</li>
When Spade stuff fails, you no longer get a generic python backtrace,
instead you get something much easier to parse quickly.</li>
</ul>
error: Expected type uint<8>, got bool
  ┌─ py:1:1
  │
1 │ true
  │ ^^^^ Expected uint<8>
  │
  ┌─ py:1:1
  │
1 │ o.a
  │ --- Type uint<8> inferred here
  │
  = note: Expected: uint<8>
               Got: bool



note: A Spade expression failed to compile
    ┌─ field_accesses.py:47
    │
 47 │ _ = s.o.a == "true"
    │ ^^^^^^^^^^^^^^^^^^^ When executing this
</code></pre>


Spade 0.10.0
2024-09-18T00:00:00+00:00

Associated changelog</a>
Swim changelog</a>
Git</a>
DOI</a>
</div>
After an extended summer break, it is time for us to release a new Spade
version! This release includes several new exciting features, most notably: trait bounds,
much improved support for methods, as well as pipelines with inferred depth.</p>
Traits🔗</a></h1>
You can now specify trait requirements on generic parameters, for example, you can now describe a UART driver that can send any type as long as it has a method to convert it into a byte</p>
trait AsByte {
  fn as_byte(self) -> uint<8>;
}

entity uart<T>(clk: clock, rst: bool, to_send: Option<T>)
  where T: AsByte
{ ... }
</code></pre>
This feature was contributed by Fabian Bleck, Alex Pichler and Rene Wimmer, as
part of their bachelor thesis at Johannes Kepler University. Thanks!</p>
Multiple non-overlaping methods on generic types🔗</a></h1>
It is now possible to have more than one method on a type, as long as the generic parameters
do not overlap. For example, the standard library now includes to_be_bytes</code> and to_le_bytes</code> for 16, 24 and 32 bit integers</p>
impl uint<16> {
    /// Converts `self` into an array of bytes in big-endian order. 0x1234
    /// becomes [0x12, 0x34].
    fn to_be_bytes(self) -> [uint<8>; 2] {
        [trunc(self >> 8), trunc(self)]
    }

    /// Converts `self` into an array of bytes in little-endian order. 0x1234
    /// becomes [0x34, 0x12].
    fn to_le_bytes(self) -> [uint<8>; 2] {
        std::conv::flip_array(self.to_be_bytes())
    }
}
</code></pre>
Turbofishes on method🔗</a></h1>
You can now also specify type parameters on methods using turbofishes. This is required if a method has type parameters that cannot be inferred, such as the size of a FIFO.</p>
stream
  .inst into_fifo::<1024>(...) // FIFO with 1024 elements
</code></pre>
Turbofish wildcards🔗</a></h1>
If you only want to specify some type parameter and infer the rest, you can now use wildcards (_</code>). These can be placed anywhere in a type, for example, if you want to specify that a type parameter is an unsigned integer of an inferred size, you can use</p>
inst method::<_, uint<_>>(...)
</code></pre>
Const generics in turbofishes🔗</a></h1>
The final change to the turbofishes and type specifications in this release allows using const generics inside the type specification.</p>
let x: uint<{10 + 12}> = ...;
</code></pre>
Pipelines with a type-inferred depth🔗</a></h1>
Generic parameters can now be used in pipeline depths, allowing pipelines whose
depth depends on the type of their inputs. For now, this is hard to make use of
in practice, but in the future it will open up more possibilities, and making
the change required a significant change in the compiler.</p>
An actual use case that is supported today is to define a pipeline which delays its inputs a configurable amount</p>
pipeline({N}) delay<#uint N>(clk: clock, t: T) -> T {
  reg * {N};
    t
}
</code></pre>
More type expressions🔗</a></h1>
You can now use -</code>, *</code> and uint_bits_to_fit</code> in const generics. The latter is extra exciting as you can now write a counter whose internal size will be inferred based on the maximum value</p>
entity blink<#uint Period>(clk: clock, rst: bool) -> bool {
  reg(clk) counter: uint<{uint_bits_to_fit(Period)}> =
    if counter == Period {
      0
    } else {
      trunc(counter + 1)
    };
  counter > Period/2
}
</code></pre>
Pattern matching on arrays🔗</a></h1>
Arrays can now be pattern-matched in match expressions, or unpacked in let bindings.</p>
let [x0, x1] = array;

let xor = match array {
  [true, false] => true,
  [false, true] => true,
  _ => false,
}
</code></pre>
Array shorthand syntax🔗</a></h1>
Arrays with N</code> identical elements can now be constructed using [x; N]</code>, for example</p>
let all_false = [false; 8];
</code></pre>
Change syntax of generic numbers to use #uint or #int instead of🔗</a></h1>
As part of the changes made in this release, we had to change the syntax of
units taking generic methods from #N</code> to #uint N</code> or #int N</code> depending on
the use case. Existing code can be easily ported by replacing #</code> with #uint</code>,
#int N</code> was not expressible in the language before.</p>


Spade 0.9.0
2024-07-04T00:00:00+00:00

Associated changelog</a>
Swim changelog</a>
Git</a>
DOI</a>
</div>
Happy summer everyone, today we're releasing v0.9.0 of Spade. This is one of our
biggest releases yet and packs several really exciting improvements, especially
around writing generic code.</p>
As always, this blog post highlights the most exciting changes and you can read
the whole change log
here</a>.</p>
Generic impl blocks🔗</a></h1>
Spade has had impl</code> blocks for a while, but until now they have only been usable
on non-generic types limiting their usefulness. With 0.9.0 you can now write
generic impl</code> blocks such as the new standard library addition is_some</code></p>
impl<T> Option<T> {
  fn is_some(self) -> bool {
    match self {
      Some(_) => true,
      None => false,
    }
  }
}
</code></pre>
Thanks to Alex, Rene and Fabian for implementing
this</a> as part of
their bachelor project at JKU!</p>
Where clauses🔗</a></h1>
You can now use where</code> clauses to constrain integer parameters in generic units. For example, it is now possible to define a function with the same type signature as the +</code> operator for integers:</p>
fn add<#In, #Out>(x: int<In>, y: int<In>) -> int<Out>
  where Out: In + 1
</code></pre>
Fixed point library🔗</a></h2>
Combining generic impl</code> blocks and where clauses, it is now possible to start working on a fixed point math library in Spade</a></p>
As an example, here are the implementations of various arithmetic operators from that library</p>
struct Fp<#Size, #FracBits> {
    inner: int<Size>
}

impl<#Size, #FracBits> Fp<Size, FracBits> {
    fn add<#OutSize>(self, other: Fp<Size, FracBits>) -> Fp<OutSize, FracBits>
        where OutSize: Size + 1,
    {
        Fp(self.inner + other.inner)
    }

    fn sub<#OutSize>(self, other: Fp<Size, FracBits>) -> Fp<OutSize, FracBits>
        where OutSize: Size + 1,
    {
        Fp(self.inner - other.inner)
    }

    fn mul<#OutSize, #OutBits>(self, other: Fp<Size, FracBits>) -> Fp<OutSize, OutBits>
        where OutSize: Size+Size,
              OutBits: FracBits+FracBits
    {
        Fp(self.inner * other.inner)
    }

    fn abs<#OutSize>(self) -> Fp<OutSize, FracBits>
        where OutSize: Size + 1
    {
        if self.inner < 0 {
            Fp(0 - self.inner)
        } else {
            Fp(sext(self.inner))
        }
    }
}
</code></pre>
Named turbofish arguments🔗</a></h1>
The final improvements to generics in this release is named turbofish arguments. The turbofish</a> (::<></code>) is used to specify generic parameters if they cannot be inferred, however, previously you had to specify them positionally which gets confusing if you have a complex generic, for example1</a></sup>:</p>
  fn mul_fp<#Size, #FracBits, #OutSize, #OutBits>(self, other: Fp<Size, FracBits>) -> Fp<OutSize, OutBits>
    where OutSize: Size+Size,
          OutBits: FracBits+FracBits
{
    Fp(self.inner * other.inner)
}

fp_mul::<16, 8, 20, 16>(...)
      // ^^^^^^^^^^^^^ Hard to know what these numbers mean
</code></pre>
With named turbofish parameters (::$<></code>), you can specify the arguments by name, similar to specifying unit arguments</p>
fp_mul::$<Size: 16, FracBits: 8, OutSize: 20, OutBits: 16>(...)
</code></pre>
^{1</sup>
The keen reader may wonder why we don't use new fancy mul</code> method on
our FixedPoint</code> type. Unfortunately, methods don't support turbofish yet
:(</p>
</div>}impl</code> blocks in modules🔗</a></h1>
The final change to generics is a fix for impl</code> blocks being broken when used in a mod</code>, for example</p>
mod {
  impl X {
    ... // Oh no, compiler bug! 😱
  }
}
</code></pre>
Thanks to DasLixou</a> for fixing this and other
issues after looking at the code around namespacing and realizing it was
terrible in general!</p>
Test improvements🔗</a></h1>
Moving on from generics and impl blocks, the cocotb test bench API has seen 2
nice convenience improvements.</p>
Native python type support🔗</a></h2>
First, it is now possible to assign
integers, booleans and lists directly to Spade types, resolving the need for
some annoying stringifying</p>
# Before you had to do this if you wanted to assign a python bool to a Spade input
s.i.bool_value = "true" if value else "false"
# Now you can just do
s.i.bool_value = value

# You also no longer need to stringify integers
s.i.int_value = 5

# And you can use python lists natively
s.i.some_integers = [i for i in range(0, 8)]
</code></pre>
== operator🔗</a></h2>
This is a smaller change, but fixes an anoying issue where if you wanted to compare the output of a module with a Spade expression, you had to do</p>
s.o.value_eq("[1,2,3]")
</code></pre>
Now you can simply write</p>
s.o == "[1,2,3]"
</code></pre>
or combining both changes</p>
s.o == [1,2,3]
</code></pre>
Small fixes🔗</a></h1>
This release also includes several small convenience changes</p>

You can now suffix int literals with a signedness and size to help the type
inferer. For example 512u32</code> or 123i64</code></li>
Added /</code> and %</code> operators. These work for dividing by constant powers of
two. For other values, the resulting hardware is likely too slow to be what
you want so the compiler gives an error suggesting a different approach. If
you do want to do combinational division or mod, you can use
std::ops::comb_div</code> or std::ops::comb_mod</code> which is suggested by the
compiler</li>
Fixed incorrect code gen for enums with a single variant</li>
Swim cocotb tests now work on more operating systems</li>
</ul>


Spade 0.8.0
2024-05-14T00:00:00+00:00

Associated changelog</a>
Swim changelog</a>
Git</a>
DOI</a>
</div>
Today we're releasing v0.8.0</code> of Spade. This release adds a bunch of new stuff
to the standard library, fixes a bunch of papercuts around test and adds
inout<T></code> to work with inout ports. We also had 2 new contributors in this
release which is very fun to see, thanks @0xC01DC0FFEE and @phire</p>
Add reduce_*</code> functions (first contribution)🔗</a></h2>
@0xC01DC0FFEE added three new functions to std::ops</code>:</p>

fn reduce_and<#N>(x: uint<N>) -> bool</code></li>
fn reduce_or<#N>(x: uint<N>) -> bool</code></li>
fn reduce_xor<#N>(x: uint<N>) -> bool</code></li>
</ul>
These compute the and</code>, or</code> and xor</code> of all bits in a number. reduce_xor</code>
is especially useful for computing parity.</p>
stage</code> improvements (first contribution)🔗</a></h2>
Scott Mansell (@phire) has fixed several issues this release. The most
important fix resolves a long-standing issue where referencing pipeline
variables using stage</code> inside blocks would cause a panic. With this change,
you can now write</p>
    let x = if condition {stage(+1).y} else {stage(+2).y}
  reg;
    let y = /* ... */;
  reg;
</code></pre>
Higher level memory primitives in std::mem</code>🔗</a></h2>
std::mem::dp_bram</code> provides a more structured primitive for working with dual
port memories. Unlike the raw std::mem::clocked_memory</code> primitive which can be
used to model any memory but is quite clunky to use in the common case, the
dp_bram</code> provides a memory with one read port and one write port that can
belong to different clock domains.</p>
Writing to the memory is done using the std::Mem::WritePort</code> struct</p>
entity writer(
    clk: clock,
    wport: WritePort<10, uint<16>>,
) {
    let (addr0, write_val0) = /* ... */;

    set wport.addr = addr0;
    set wport.write = write_val0;
}
</code></pre>
And reads are done on the ReadPort</code> struct, preferably using std::mem::read_read_port</code></p>
pipeline(1) reader(
    clk: clock,
    rport: ReadPort<10, uint<16>>,
) -> [[uint<16>; 3]; 3] {
      let addr0 = /* ... */;
      let addr1 = /* ... */;

      let out0 = inst(1) read_read_port(clk, addr0, rport)
      // Since the memory read unit is a pipeline, we can't accidentally forget that the memory
      // has read latency
  reg;
      // Do something fun with the read values!
}
</code></pre>
The dp_bram</code> module returns two ports which you can then pass along to the reader and writer</p>
entity top(clk: clock) {
  let (write, read) = inst dp_bram::<1024, uint<16>, 10>$(write_clk: clk, read_clk: clk);

  let _ = inst writer(clk, write);
  let _ = inst reader(clk, read);
}
</code></pre>
One big advantage of this is that since the memory ports are struct port</code>, the compiler
will ensure that there aren't multiple users of the ports. For example, the following code results
in a compilation error</p>
entity top(clk: clock) {
  let (write, read) = inst dp_bram::<1024, uint<16>, 10>$(write_clk: clk, read_clk: clk);

  let _ = inst writer(clk, write);
  let _ = inst reader(clk, read);
                        // ^^^^ First use here
  let _ = inst reader(clk, read);
                        // ^^^^
                        // Use of consumed resource
}
</code></pre>
Clock domain crossing primitives🔗</a></h2>
The second addition to the stdlib is the new
std::cdc</code></a>
module which contains primitives for crossing clock domains. The primary
additions are std::cdc::sync2_bool</code>, std::cdc::sync_wide</code> and
std::cdc::handshake</code> which provide primitives for a few different crossing
scenarios. All of these are extremely danger</em> if used incorrectly, so make
sure to read the documentation for the
modules</a>
to make sure that you satisfy the constraints they have to behave correctly.</p>
Test improvements🔗</a></h2>
We have made several improvements to the testing system in Spade</p>
A minor but important change is that tests now support modules that return
void</code>. In addition, the verilator</code> wrapper now works on modules with &mut</code>
inputs.</p>
For verilator</code> tests, we have also added .spade_repr</code> to fields which returns
a human-readable Spade representation of the field. This is useful if you need
to, for example, print a result.</p>
Using these changes, it is possible to use the simulation speed of Verilator</code>
to write "interactive" test benches, here is an example of a testbench that
visualizes the memory access pattern of a camera project I'm working on:</p>
</p>
Latch-Up presentation🔗</a></h1>
Two weeks ago, Frans presented Spade at Latch-Up 2024 in Boston. You can see a
recording of the talk here:</p>
</iframe>


Spade 0.7.0
2024-03-21T00:00:00+00:00

Associated changelog</a>
Swim changelog</a>
Git</a>
DOI</a>
</div>
Today we're releasing v0.7.0</code> of Spade. This release adds additional
capabilities when writing generic code, some new features to the standard
library, and fixes several small annoyances and bugs.</p>
First contributions 🎉🔗</a></h2>
Three bachelor students from JKU have started contributing to Spade as part of
their bachelor project. They have made several improvements to the language
this release:</p>

In the previous release, we removed the need to use ()</code> after zero parameter
enum variants, but this was accidentally still needed when use</code>ing enum
variants. This has now been fixed, so None()</code> can be written as None</code></li>
You can now use the bitwise invert operator (~</code>) on unsigned integers</li>
Fixing a compiler panic when using the wrong number of arguments in a turbofish (::<></code>)</li>
</ul>
Thanks Alex, Rene and Fabian!</p>
Generic parameters as expressions🔗</a></h2>
With this release, it is now possible to use generic integers as constants
inside modules, for example a counter with a constant maximum value can be
written as:</p>
entity counter::<#Width, #Max>(clk: clock, rst: bool) -> uint<Width> {
    reg(clk) val reset(rst: 0) = if val == Max {0} else {trunc(val + 1)};
    val
}

// Emits a tick every 10th clock cycle
entity count_to_10(clk: clock, rst: bool) -> bool {
  inst counter::<4, 9>(clk, rst) == 9
}
</code></pre>
As part of this change, it is now also possible to refer to generic parameters
inside the body of units, so you no no longer have to rely on the type inferer
to get what you mean. This is very useful when wrapping memories</p>
entity fifo<#W, D, #C>(
    write_clk: clock,
    write_rst: bool,
    read_clk: clock,
    read_rst: bool
) -> (FifoWrite<D>, FifoRead<W, D>) {
    // ...
    let (ram_write, ram_read) = inst dp_bram::<W, D, C>(write_clk, read_clk);
                                            // ^^^^^^^ These had to be inferred previously
    // ...
}

</code></pre>
Misc smaller changes🔗</a></h2>

It is now possible to write 1-2</code>, previously a space was required.</li>
swim clean</code> no longer removes the compiled Spade compiler leading to faster clean build times.</li>
Added --use-sudo</code> to swim to run upload tools with superuser permissions. This can be helpful if you don't have udev rules set up.</li>
</ul>
Spade at conferences🔗</a></h1>
Frans will be at DATE</a> and OSDA
2024</a> next week! If you're also going to be there get in
touch!</p>
Spade will also be presented at
LatchUp</a> in Boston on May 19-21,
and the week after that Frans is co-organizing LATTE
2024</a> which is co-located with
ASPLOS</a>.</p>


Spade 0.6.0
2023-12-28T00:00:00+00:00

Associated changelog</a>
Swim changelog</a>
Git</a>
DOI</a>
</div>
This holiday season we're releasing 0.6.0 of Spade. The focus for this release has been
fixing small annoyances in the language to make it nicer to work with and more complete.</p>
Unsigned integers🔗</a></h2>
For a long time, Spade has only had one integer type: int</code> which has been primarily
used for signed integers but has been used to emulate unsigned integers where required.
However, as it turns
out</a>, this results in
incorrect values when additions add additional bits, as is the case for all
additions in Spade.</p>
This finally gave us the motivation to add a proper unsigned type, uint</code>. It
is a drop-in replacement for the old hacky signed-as-unsigned integer system
and all the basic operators are overloaded to work with both int</code> and uint</code>.
This uses a lot of compiler infrastructure that has been added for traits,
which means that user defined operator overloading is on the horizon.</p>
Turbofish🔗</a></h2>
For too long, the Spade language has not had any fish in the language itself.
That changes today! The "turbofish"</a> ::<></code> syntax can be
used to specify type parameters for units when they cannot be inferred, for example
trunc::<int<8>, int<6>>(a)</code>.</p>
Cast functions🔗</a></h2>
The standard library now contains several functions for casting between
bit-like types such as integers and arrays of bools.</p>
The star of the show is the new std::conv::unsafe::unsafe_cast</code> which simply
re-interprets the bits. As the name implies, the guarantees this provides for
most types are pretty much "lmao, good luck", so it is primarily to be used
internally in std::conv::int_to_bits</code> and std::conv::bits_to_int</code> which are
safe to call.</p>
For those times where you want to do cursed things with clocks, there is also
std::conv::unsafe::clock_to_bool</code> and std::conv::unsafe::bool_to_clock</code>.</p>
Finally, there is now a std::conv::flip_bits</code> which reverses the bits in an
array, since that is hard to express neatly in Spade without a builtin
function.</p>
Enum variant ergonomics🔗</a></h2>
In rust, if you instantiate an enum variant that has no parameters, like None</code>, you don't have to call it like a function, i.e. None()</code>.
The same thing now applies in Spade, making the language feel more familiar to
rust users, and a bit more consistent, since the parentheses were already not
needed in match patterns.</p>
To avoid massive breaking changes, the old style is also supported</p>
Array range indexing🔗</a></h2>
You can now index arrays by ranges, as long as the ranges are statically known. For example: the following code now compiles and runs without error</p>
let a = [1, 2, 3, 4];
assert a[1:3] == [2, 3];
</code></pre>
Block comments🔗</a></h2>
3 years in, Spade finally has block comments naturally denoted by /*</code> and
*/</code>. Of course, block comments can be nested, unlike some</em> languages</p>
Call by name🔗</a></h2>
A internal change has been made to the way the compiler instantiates units. In
the resulting Verilog code, arguments were previously passed positionally like
this:</p>
subunit unit_0(arg1, arg2, arg3);
</code></pre>
In 0.6.0 they are now instead instantiated by name</p>
subunit unit_0(.param1(arg1), .param2(arg2), .param3(arg3));
</code></pre>
While this makes no difference for Spade code where the compiler knows the
argument order, it did cause problems when instantiating external Verilog like
vendor primitives, or VHDL code where argument order is less well known.</p>
As an example, the following code now works as expected whereas it would behave incorrectly before</p>
#[no_mangle]
fn external_verilog_module(first_arg: bool, second_arg: bool, result: &mut bool) __builtin__
</code></pre>
module external_verilog_module(input second_arg_i, input first_arg_i, output result_o);
  // ...
endmodule
</code></pre>


Spade 0.5.0
2023-11-17T00:00:00+00:00

Associated changelog</a>
Swim changelog</a>
Git</a>
DOI</a>
</div>
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.</p>
Language reference🔗</a></h2>
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</a>.</p>
Verilator simulation🔗</a></h2>
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:</p>
// 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
</code></pre>
For more details on how to write testbenches, see the newly added Verilator documentation in the Spade
book</a>.</p>
oss-cad-suite</code>🔗</a></h2>
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</code> containing open source software for doing digital design. Swim
has learned about oss-cad-suite</code>, so now you can run swim install-tools</code> which
will install the latest version and use it when running Swim.</p>
$ 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
$ :-)
</code></pre>
tomldoc🔗</a></h2>
Swim projects are configured using a file called swim.toml</code>, much like how
Cargo projects are configured using a file called Cargo.toml</code>. 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</del> double nerd snipe</a>,
Frans wrote a tool to generate mdbook-documentation for configuration
files</a> 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</code>-documentation</a>
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</code> is supposed to look.</p>
Various bug fixes🔗</a></h2>
As usual, there are also additional bugfixes. Check out the Swim
changelog</a> and
Spade
changelog</a> for
more information!</p>
This version's featured bug-fix is
spade!235</a> where it
turned out Vivado parses \new</code> as the keyword new</code>, even though it is written
as an escaped identifier with the leading \</code>. Thanks, Vivado!</p>


Spade 0.4.0
2023-08-24T00:00:00+00:00

Associated changelog</a>
Git</a>
DOI</a>
</div>
After a small summer break, it's time to release Spade 0.4.0. It contains an
important milestone for Spade and several improvements to the surrounding
tooling along with the usual batch of small fixes and changes.</p>
Write your top module in Spade, not Verilog!🔗</a></h2>
A very exciting milestone is that writing Spade projects no longer requires writing
a Verilog shim! Historically, every Spade project has needed an outermost
Verilog file that takes care of two things:</p>

Generating a reset signal.</li>
Naming the signals from the pin file that will be used and passing them to the Spade code.</li>
</ol>
From now on, you can do all these things directly in Spade. You can see this in
action in the updated
swim templates repository</a>.</p>
Initial values for registers🔗</a></h2>
One change required for the previously mentioned heading is the possibility to
specify initial values for registers. For example, here is how you would define
a reset signal that is initialized to true</code> and then set to false</code> at the
first clock cycle.</p>
reg(clk) rst initial (true) = false;
</code></pre>
WAL integration🔗</a></h2>
In the Spring, we did a collaboration with the WAL
project</a>. WAL is a language for analyzing simulation
waveforms which makes it much easier to get high level information out of your
simulation results.</p>
The result of our joint work is a way to bundle WAL analysis code with Spade
libraries, a set of annotations to effortlessly request the use of the analysis
passes, and integration with Swim to allow running the requested passes in a
single command - swim plugin analysis</code>.</p>
As an example of the capability this adds we can look at a project consisting
of two devices communicating with a shared device via two wishbone
buses</a> connected to an
arbiter.</p>
We'll add the wishbone bus as a dependency to the project, along with the WAL analysis plugin:</p>
[libraries.wishbone]
git = "https://gitlab.com/spade-lang/lib/fishbone"
branch = "main"

[plugins.wal_analysis]
git = "https://gitlab.com/spade-lang/wal_analysis"
branch = "main"
</code></pre>
Then we'll instantiate two wishbone buses, connect their inputs and outputs to the master and arbiter:</p>
entity wb_harness(clk: clock, rst: bool)
  -> (int<16>, int<16>)
{
    let (wb1, wb1inv) = port;
    let (wb2, wb2inv) = port;

    #[wal_trace(clk=clk, rst=rst))]
    let wb1 = wb1;
    #[wal_trace(clk=clk, rst=rst))]
    let wb2 = wb2;

    let _ = inst wishbone_arbiter( clk, rst, wb1inv, wb2inv, ...);
    let o1 = inst wishbone_master( clk, rst, wb1, ...);
    let o2 = inst wishbone_master( clk, rst, wb2, ...);

    (o1, o2)
}
</code></pre>
The two #[wal_trace]</code> attributes are where the magic happens. This tells the
compiler to emit some special signals that the analysis scripts in the
wishbone library should look for.</p>
With this in place, after running swim plugin analysis</code> you will get a whole bunch of high level
information about the two buses:</p>
[ANALYSIS] # wb_harness.wb1
[ANALYSIS]    Nr. transactions : 697
[ANALYSIS]    Nr. reads        : 16
[ANALYSIS]    Avg read latency : 6 clock cycles
[ANALYSIS]    Nr. writes       : 681
[ANALYSIS]    Avg write latency: 9 clock cycles
[ANALYSIS]    Inactive cycles  : 6%
[ANALYSIS] # wb_harness.wb2
[ANALYSIS]    Nr. transactions : 421
[ANALYSIS]    Nr. reads        : 0
[ANALYSIS]    Avg read latency : - clock cycles
[ANALYSIS]    Nr. writes       : 421
[ANALYSIS]    Avg write latency: 12 clock cycles
[ANALYSIS]    Inactive cycles  : 22%
</code></pre>
And you'll even get a histogram showing the number of transactions over time
which can give a lot of insight into the behaviour of the system.</p>
</p>
We will present this work at FDL 2023</a>. If you want to learn more and see how it is implemented, you can read our paper</a>.</p>
Swim Simulation Improvements🔗</a></h2>
Swim has also gotten some love recently. It now discovers and runs each test
case in parallel instead of the previous fully sequential test running. Along
with that, it has a new UI for the test running which scales with the size of
your terminal, shows which tests are running, waiting and done, and only prints
the stdout of failed tests. All of this is easier to showcase in a video:</p>
</video></p>
Open VCD files in a single click🔗</a></h3>
In addition, if you run swim setup-links</code> and run a terminal that supports
OSC8
hyperlinks</a>,
swim will now print links to open the wave file from an individual test in a
waveform viewer.</p>
</video></p>
A new waveform viewer🔗</a></h2>
Frans Skarman</p>
Finally, in that last video you may have noticed an unusual waveform viewer. It
is called surfer and is something I've been working on and off for the past few
months. My goals here are a wave viewer with a nice to use interface
and which is easy to integrate with languages like Spade where signal values
are more than just bits. For Spade, that means it can translate Spade types into
their fields or enum variants, but the translation interface is general, so
other projects should also be able to add similar features.</p>
The interface is snappy and thanks to some work by Lucas
Klemmer</a> of WAL fame, it also
has a very nice keyboard centric interface as you can see in the next video.</p>
</video></p>
The project is still in its early stages, but I have been using it for all my wave surfing needs for the past few weeks. You can follow along at https://gitlab.com/surfer-project/surfer</a>.</p>


Spade 0.3.0
2023-06-01T00:00:00+00:00

Associated changelog</a>
Git</a>
DOI</a>
</div>
Today, we release Spade version 0.3.0. It comes with a few small fixes, and some major new features:</p>
Dynamic Pipelining🔗</a></h2>
The biggest new feature is native support for stalling pipelines. Pipelines can be stalled
by adding a condition for stalling to a stage as shown below:</p>
    reg[should_stall];
</code></pre>
If should_stall</code> is true, the registers corresponding to this reg</code>-statement will hold their
current value, instead of getting a new one. Additionally, all stages before</em> it will also stall,
in order to not throw away any data.</p>
When interacting with the outside world, it is of course important to know if a stage is ready to
receive data, and if data in a stage is valid. This can
be done using stage.valid</code> and stage.ready</code>.</p>
For a full description of the feature, see https://docs.spade-lang.org/language_reference/dynamic_pipelines.html</p>
Inverted Ports🔗</a></h2>
It is now possible to create inverted versions of port types, i.e. ports where
mut</code> wires non-mut</code> wires are switched.</p>
This is useful when wanting to create a port somewhere in between two units
communicating with ports, and passing each end to one unit. To create such
a port combination, the new port</code> expression can be used.</p>
As an example, here a port pair connecting a producer and a consumer is created:</p>
entity top() {
    let (p, p_inv) = port;

    let _ = inst consumer(p);
    let _ = inst producer(p_inv)
}

entity consumer(p: P) -> bool {
    // ...
}

entity producer(p: ~P) -> bool {
    // ...
}
</code></pre>
Experimental Word Length Inference🔗</a></h2>
The past few months, a master student has been working on adding better
handling of word lengths to Spade, and with 0.3.0, an experimental version of
that feature is included.</p>
The new word length inference can be turned on using --infer-method</code> to the
compiler, or by setting the environment variable SPADE_INFER_METHOD</code>. There
are three word length inference methods available: Interval Arithmetic (IA</code>),
Affine Arithmetic (AA</code>), and a mix of the two: (AAIA</code>)</p>
With one of these flags enabled, the compiler should infer tighter bounds on word
lengths, and will require far trunc</code> and sext</code> calls. For example, it is now
possible to write</p>
a + b + c
</code></pre>
without manual intervention.</p>
More predictable names🔗</a></h2>
The last major change in this release is improvements to the names used in the output Verilog.</p>
First, you can now use #[no_mangle]</code> on unit arguments in addition to on the
whole unit, allowing interop with more Verilog modules.</p>
The names of signals being generated have also been improved. They are no
longer globally unique, but this means that the names correspond more closely
to the corresponding name in the source code. In fact, variables with no shadowing
have the exact same name in the generated Verilog as they do in the source code.</p>


Spade 0.2.0
2023-04-20T00:00:00+00:00

Associated changelog</a>
Git</a>
DOI</a>
</div>
6 weeks have passed, so it is time for another Spade release! A lot of my time
has been spent at or preparing for conferences, so there are no huge changes
this time, but quite a few convenience features.</p>
Memory Initial Content🔗</a></h2>
The standard library has been extended with another function:
std::mem::clocked_memory_init</code>. Like its sibling clocked_memory</code>, it defines
a memory which can be read by read_memory</code>, but this one also allows
specifying initial content of the memory.</p>
This can be used to build ROMs if no write ports are specified, or RAMs with
initial content if the available memories support it.</p>
let rom = clocked_memory_init$(
    clk,
    writes: [],
    initial: [1,2,3,4]
);
reg(clk) rom_out = read_mem(rom, addr);
</code></pre>
More arithmetic ops🔗</a></h2>
This release adds min</code>, max</code> and order</code> functions to the standard library
under the std::ops</code> namespace, and the !=</code> operator to the core language.</p>
(Hacky) literals🔗</a></h2>
An issue that has been plaguing the language for a while is a lack of support for large or negative integer literals. For example, the following code failed to compile</p>
let x: int<8> = -128
</code></pre>
This is clearly not intentional, and has been fixed.</p>
In a related issue, the following code also failed to compile</p>
let x: int<8> = 128
</code></pre>
While this is</em> incorrect code since 128</code> does not fit in an 8-bit integer, Spade does not currently have an unsigned type and some features such as array indices treat signed integers as unsigned. This means that code like</p>
let array = [1,2,3,4];
let value = array[3];
</code></pre>
fails to compile. Until Spade gets a proper unsigned type, you can now suffix integer literals with u</code>, making the following code work</p>
let array = [1,2,3,4];
let value = array[3u];
</code></pre>
It is worth pointing out that this is only an integer literal representation change, so using u for anything but index-like operations will fail. For example,</p>
let x: int<8> = 1;
let y: int<8> = 150u;
x > y
</code></pre>
will evaluate to false</code>.</p>
Standard Library in Stand-alone Projects🔗</a></h2>
Previously, the standard library was included by swim</code> when compiling
projects. But this meant that one had to manually include the standard library
when running the spade compiler in stand-alone mode without swim.</p>
As of this version, spade</code> now includes the standard library and prelude
itself, allowing its use without swim.</p>
Note: If you use an old swim</code> with a new spade</code>, or vice versa, you will see
errors when building swim projects. Make sure to update both or neither.</p>
Error message improvements🔗</a></h2>
After 4 years of resistance, my advisor has finally written some Rust! Among
other things, he made numerous improvements to the grammar and clarity of the
error messages coming out of the compiler.</p>
Publications🔗</a></h2>
I managed to visit 2 workshops in the last month:
Latte'23</a> and OSDA</a>.
If you want to see the papers or presentations, check the publication list at
https://spade-lang.org/#publications</p>


Spade 0.1.0
2023-03-09T00:00:00+00:00

Associated changelog</a>
Git</a>
DOI</a>
</div>
Before this point, Spade has only had commit IDs to differentiate versions, but
for various reasons discussed in
https://gitlab.com/spade-lang/spade/-/merge_requests/161</a> having numbered
releases is useful.</p>
As with so many other aspects of this project, inspiration has been taken from
Rust's release and versioning scheme. New Spade versions will be published
every six weeks on a fixed schedule. Features and fixes that are on master</code>1</a></sup> are
included, everything else is not. Since the compiler and language are still in
an unstable development stage, all versions will be 0.x</code>, and breaking changes
will be the norm for now.</p>
As a user, it will still be advised to always use the master</code> branch. Releases
are more intended to give something to reference, especially on
https://zenodo.org</a>, and to serve as an opportunity to
summarize what has changed in the past few weeks and make some announcements.</p>
That's all for today! In 6 weeks, when 0.2 is released, the blog post will
hopefully have more interesting content, highlighting some new features.</p>
^{1</sup>
We should probably rename it to main</code> at some point 🤔</p>
</div>}


ISY Summer of Code 2022
2022-08-16T00:00:00+00:00
This summer I've had the opportunity to work in a Summer of Code organized by
the department of Electrical Engineering (ISY)</a> at
Linköping University</a>. This post will summarize a few of the
changes I worked on and had particularly fun with.</p>
Background🔗</a></h2>
I was selected to work half-time for two
months on Spade, but I had a lot of freedom in what exactly I did.
A complete listing of all merged merge requests (at least in the spade-lang</code>
Gitlab organization, so not counting e.g. prr</code>) can be found on
Gitlab</a>
(from spade!75 and onwards). Apart from that I also helped review some merge
requests (also on
Gitlab</a>).</p>
You can read more about Spade on the main Spade
website</a>. Spade, as well as most of the tooling, is
implemented in Rust</a>, so some of the content here will
also touch on Rust.</p>
About me🔗</a></h3>
Before I started university, I had not done any hardware programming (or
hardware anything really, apart from building my desktop computer) at all.
University introduced me first to digital electronics using physical wires and
later to VHDL and hardware programming.</p>
I had already been contributing to Spade for a couple of months, and I had used
it twice in game jam projects. (Not really the intended use case but it worked
out alright.) Still, I wouldn't call myself a expert in hardware by any means.
What's nice about a hardware compiler</em> is that I usually don't have to worry
that much about the actual hardware going on since the compiler hides most of
the weirdness behind abstractions. I could for example work on the parser without
worrying at all about Verilog.</p>
Tracing in the compiler🔗</a></h2>
As a first task, I wanted to get a better feel for the Spade compiler structure.
We had specialized tracing (logging) for the parser and typechecker, but I
wanted something more like the tracing found in the Rust
compiler</a>. It turns out Rust
uses public libraries (tracing</code></a>,
"scoped, structured logging and diagnostics", and
tracing-tree</code></a> for the output) so
we could add them right away.</p>
Adding tracing</code> and tracing-tree</code> was first done in
spade!75</a>. We opted to
not add the tracing events themselves all at once since the compiler is too
large for that. Instead, we added them as needed when we worked on fixing other
bugs.</p>

  </p>
</div>
  Example of tracing output for the AST lowering stage.</p>
</div>
</figure>
We still have two old systems that can annotate functions and show a tree-like
view of the program flow (for parsing and type checking) which are left for now.
At some point they could probably be incorporated into tracing.</p>
Multipart suggestions🔗</a></h2>
One important goal of the Spade compiler is to be friendly to humans. Here's an
example error message from a small fix I did in
spade!94</a>:</p>

  error: Multiple definitions of b
  ┌─ testinput:1:8
  │
1 │ entity b() -> bool {
  │        ^ Multiple items named b
  ·
5 │ use x::b;
  │     ---- Previous definition here
</code></pre>
</div>
  A Spade compiler error example</p>
</div>
</figure>
This can be compared with the output for the equivalent error (two entities
with the same name) when compiling some VHDL in one of my university courses,
using a to-be-unnamed proprietary compiler.</p>

  =========================================================================
*                          HDL Parsing                                  *
=========================================================================
Parsing VHDL file "/home/user/..../lab.vhd" into library work
Parsing entity <lab>.
Parsing entity <lab>.
ERROR:HDLCompiler:69 - "/home/user/..../lab.vhd" Line 13: <std_logic> is not declared.
ERROR:HDLCompiler:69 - "/home/user/..../lab.vhd" Line 14: <unsigned> is not declared.
ERROR:HDLCompiler:69 - "/home/user/..../lab.vhd" Line 15: <unsigned> is not declared.
ERROR:HDLCompiler:854 - "/home/user/..../lab.vhd" Line 12: Unit <lab> ignored due to previous errors.
Parsing architecture <Behavioral> of entity <lab>.
ERROR:HDLCompiler:69 - "/home/user/..../lab.vhd" Line 51: <rx> is not declared.
ERROR:HDLCompiler:69 - "/home/user/..../lab.vhd" Line 47: <rst> is not declared.
ERROR:HDLCompiler:1728 - "/home/user/..../lab.vhd" Line 46: Type error near clk ; current type unsigned; expected type std_ulogic
ERROR:HDLCompiler:69 - "/home/user/..../lab.vhd" Line 69: <rst> is not declared.
ERROR:HDLCompiler:1728 - "/home/user/..../lab.vhd" Line 68: Type error near clk ; current type unsigned; expected type std_ulogic
ERROR:HDLCompiler:69 - "/home/user/..../lab.vhd" Line 102: <rst> is not declared.
ERROR:HDLCompiler:1728 - "/home/user/..../lab.vhd" Line 101: Type error near clk ; current type unsigned; expected type std_ulogic
ERROR:HDLCompiler:69 - "/home/user/..../lab.vhd" Line 130: <rst> is not declared.
ERROR:HDLCompiler:1728 - "/home/user/..../lab.vhd" Line 129: Type error near clk ; current type unsigned; expected type std_ulogic
ERROR:HDLCompiler:69 - "/home/user/..../lab.vhd" Line 148: <rst> is not declared.
ERROR:HDLCompiler:1728 - "/home/user/..../lab.vhd" Line 147: Type error near clk ; current type unsigned; expected type std_ulogic
ERROR:HDLCompiler:69 - "/home/user/..../lab.vhd" Line 171: <rst> is not declared.
ERROR:HDLCompiler:1728 - "/home/user/..../lab.vhd" Line 170: Type error near clk ; current type unsigned; expected type std_ulogic
ERROR:HDLCompiler:1728 - "/home/user/..../lab.vhd" Line 192: Type error near clk ; current type unsigned; expected type std_logic
ERROR:HDLCompiler:69 - "/home/user/..../lab.vhd" Line 192: <rst> is not declared.
Sorry, too many errors..
-->
</code></pre>
</div>
  A VHDL compiler error example. Too many errors indeed.</p>
</div>
</figure>
We use a library called codespan</code></a> which renders
our source code annotated with labels that can point to different spans, as seen
above. Before the Summer of Code we had already implemented support for
suggestions in which we attach suggestions to error messages. These suggestions
consist of a span to remove and a text to replace it with. What's nice is that
all combinations of add and remove (only addition, only removal, and
replacement) could be chosen by leaving either the span or the text empty.</p>

  error: Expected array size
  ┌─ testinput:2:12
  │
2 │     let _: [bool] = [true, false];
  │            ^^^^^^ This array type
  │
  = Array types need a specified size
  = Insert a size here
  │
2 │     let _: [bool; N] = [true, false];
  │                 +++
</code></pre>
</div>
  An example of a suggestion with a single replacement. In this
case, the replacement span is the empty span between l</code> and ]</code>, and the
replacement text is ; N</code>.</p>
</div>
</figure>
In codespan!2</a>, I
then added support for suggestions that consist of multiple parts.</p>

  error: Unexpected `(`, expected `{`, `,`, or `}`
  ┌─ main.spade:2:6
  │
2 │     B(n: int<4>),
  │      ^ expected `{`, `,`, or `}`
  │
  = Use `{` if you want to add items to this enum variant
  │
2 │     B{n: int<4>},
  │      ~         ~
</code></pre>
</div>
  An example of a suggestion with multiple replacements.</p>
</div>
</figure>
There is still work left to do. For starters, suggestions currently need to be
on the same line to be rendered.</p>

  error: Unexpected `(`, expected `{`, `,`, or `}`
  ┌─ main.spade:2:6
  │
2 │     B(
  │      ^ expected `{`, `,`, or `}`
  │
  = (Note: skipped showing 1 multi-line suggestion)
</code></pre>
</div>
  An example of a suggestion over multiple lines that is skipped.</p>
</div>
</figure>
At some point we also probably want to upstream this into the original codespan
repository.</p>
Board presets in Swim configurations🔗</a></h2>
In addition to Spade, we also have a build tool called Swim. It handles some of
the work in getting your Spade code programmed onto an FPGA. It does this through
a series of steps.</p>

Build</li>
Synthesis</li>
Place and route</li>
Packing</li>
Uploading</li>
</ul>
Since FPGA models have unique hardware characteristics, we need to specify
different values and programs for different boards in a Swim configuration file. Here's
how it looks for the Go Board</a> I have at
home.</p>

  compiler_dir = "spade"

[synthesis]
top = "top"
extra_verilog = ["src/top.v"]
command = "synth_ice40"

[pnr]
architecture = "ice40"
device = "iCE40HX1K"
pin_file = "go.pcf"
package = "vq100"

[packing]
tool = "icepack"

[upload]
tool = "iceprog"
</code></pre>
</div>
  Example Swim.toml for the Go Board FPGA.</p>
</div>
</figure>
Compare this to the configuration required for the ECPIX-5. Notably, [pnr]</code>,
[upload]</code> and [packing]</code> contains completely different values.</p>

  compiler_dir = "spade"

[synthesis]
top = "top"
extra_verilog = [ "src/top.v" ]
command = "synth_ecp5"

[pnr]
architecture = "ecp5"
device = "LFE5UM5G-45F"
pin_file = "ecpix5.lpf"
package = "CABGA554"

[upload]
tool = "openocd"
config_file = "openocd-ecpix5.cfg"

[packing]
tool = "ecppack"
idcode = "0x81112043"
</code></pre>
</div>
  Example Swim.toml for the ECPIX-5 FPGA.</p>
</div>
</figure>
Now, most of this configuration will be the same for each Go Board, or ECPIX-5,
or insert your FPGA of choice here</em>. So in
swim!26</a> I added
support for a [board]</code>-directive in the configuration file. You could then instead of the
above configurations write:</p>

  compiler_dir = "spade"

[synthesis]
top = "top"
extra_verilog = ["src/top.v"]
command = "synth_ice40"

[board]
name = "go-board"
pcf = "go.pcf"
</code></pre>
</div>
  Example Swim.toml for the Go Board FPGA, with [board]</code>.</p>
</div>
</figure>

  compiler_dir = "spade"

[synthesis]
top = "top"
extra_verilog = [ "src/top.v" ]
command = "synth_ecp5"

[board]
name = "ecpix-5"
pin_file = "ecpix5.lpf"
config_file = "openocd-ecpix5.cfg"
</code></pre>
</div>
  Example Swim.toml for the ECPIX-5 FPGA, with [board]</code>.</p>
</div>
</figure>
The fields pin_file</code> and pcf</code> are used to map pins on the board to input and output
signals in the code, which means it is not the same from project to project and
therefore still specified.</p>
Lock file for "pinning" dependencies in Swim🔗</a></h2>
Before the Summer of Code, we had already added support for dependencies in Swim.</p>

  compiler_dir = "spade"

[libraries.my-dependency]
git = "https://example.com/git/repository.git
branch = "main"
</code></pre>
</div>
  Example dependency in a Swim configuration file</p>
</div>
</figure>
When you run swim build</code> for the first time, Swim will fetch a copy of the
repository, checkout the specified branch and build it as a separate module.
After the first build, Swim won't re-fetch the repository unless you run swim update</code> (so you don't have to have an internet connection ever time you build).
But if you later build this project on another computer, what happens if the
branch has been updated in the repository? To ensure the project uses the same
dependencies, we create a file swim.lock</code> containing the hash of the commit
which takes priority over the specified reference in swim.toml</code>. (It's a bit
hard to exemplify but you might be aware of lock files from other build tools
like Cargo, npm and Nix (flakes).)</p>
The hardest part about this change wasn't the actual change, but testing it.
What good is a complex feature like this if you can't trust that it even works
from the start? Most of Swim relied on relative paths and changing the active
directory (like cd</code>) which in combination with tests running in parallel made
the test suite more racy than an F1 GP. The solution was to not have
relative paths and tests that all change the active directory, by instead
making all paths absolute paths instead.</p>
What's more, the logging output was
not</em> captured by the test suite, so it all went to the same terminal, making it
borderline impossible to debug where stuff went wrong. (Usually, Cargo collects
output from tests and only prints it per test for failed tests. The solution was
to wrap the log call in a println</code> with fern::Output::call(|record| println!("{}", record.args()));</code>.) My misery can
be found in swim!37</a>.</p>
This also came during the worst of the summer heat, and I got to experience
first-hand the loss of productivity when it's 30+°C degrees outside and somewhere
around 25-28 °C inside for an entire week.</p>
Gitlab CI🔗</a></h2>
Speaking of tests, I found myself debugging CI pipelines at multiple points for
different projects. I've created new CI configurations for our mdbook, this
blog and our codespan fork. We also have a tool called Trawler</a> that tries to build a list of
projects to ensure we don't accidentally break "real" code (and as an incentive
to keep a couple of external projects up-to-date), so for that I wrote a
JUnit-generator since Gitlab understands and renders JUnit-reports.</p>

  </div>
  A Trawler JUnit report on Gitlab.</p>
</div>
</figure>
This blog🔗</a></h2>
Towards the end of the summer we felt like it would be nice to write a bit about
what I had done and how everything had went. Thus, this blog. I started with a
scrapped personal website and modified the look to be more like the main
spade-lang.org</a>. You're browsing the result right now
:).</p>
I've been getting used to Zola more and more, but some things are still a bit
difficult to do (and more importantly, not really documented). I have collected
an example in the appendix</a>. Still, right
when I want to give up and make an ugly hack in the Zola source, a solution
usually presents itself.</p>
Gitlab support for prr</code> for offline code reviews🔗</a></h2>
During development I found a tool called prr</code></a>.
From the repository:</p>

prr</code> is a tool that brings mailing list style code reviews to Github PRs.
This means offline reviews and inline comments, more or less.</p>
</blockquote>
I had found myself on quite a few train rides without internet access, so this
sounded like something I could use. I had gotten permission to work a bit on
unrelated tooling if it was to help me work on Spade, and since we use
Gitlab instead of Github I got to work on adding Gitlab support. This didn't
take too long (a day or two) since I had already used the
gitlab</code></a>-crate for doing API calls to Gitlab
before.</p>
The resulting fork can be found on Github</a>. It
doesn't support spanned comments due to some funky API documentation</a>.</p>
Appendix A: Zola workaround example🔗</a></h2>
In Zola, the special variables page</code> and section</code> aren't inherited when using
include "something.html"</code> (I think). So here's a weird solution to work around
that:</p>

  We want the header link (top left) to link to

1) If we're rendering a post, the containing section.
2) If we're rendering a section, this section.
3) If we're rendering the homepage, the homepage.

[[ templates/base.html ]]

{% if page %}
  {% set this = page %}
  {% set page = page %}
{% elif section %}
  {% set this = section %}
  {% set section = section %}
{% endif %}

[[ templates/partials/nav.html (included from
   templates/base.html) ]]
{% if page %}
  {% set section = get_section(path=page.ancestors | last) %}
  <a href={{ section.permalink }}>
    {{ section.title | default(value=config.title) }}
  </a>
{% elif section and section.title %}
  {{ section.title }}
{% else %}
  {{ config.title }}
{% endif %}
</code></pre>
</div>
  </div>
</figure>
Appendix B: Spanned comments using the Gitlab API🔗</a></h2>
While working on spanned comments (comments that target a line range instead of
a single line) I had a """fun""" problem with the API documentation. There is a
header in the documentation called Create a new merge request
thread</a>
which shows us how to create a thread pointing to a single line. Great! Let's
use it. We use the already existing code to take a review file and parse it into
a list of InlineComment</code>. Then, we use an iterator and map</code> (transform, sort
of) each inline comment into its own thread.</p>
(This code is simplified to make a point. Check the
original</a>
if you're interested.)</p>

  let discussions = inline_comments
  .iter()
  .map(|c| {
    let mut position = Position::new();
    match c.line {
      // Since we're commenting on a diff, all of these
      // contain two values: the line number the comment
      // is at before and after the diff is applied.
      LineLocation::Removed(old_line, _) => {
        position.old_line(old_line);
      }
      LineLocation::Added(_, new_line) => {
        position.new_line(new_line);
      }
      // Fun fact: having both old_line and new_line here
      // is mandated by the API.
      LineLocation::Changed(old_line, new_line) => {
        position.old_line(old_line).new_line(new_line);
      }
    }
    CreateMergeRequestDiscussion::new()
      .body(&c.comment)
      .position(position)
  });
</code></pre>
</div>
  Adding comments on single lines on Gitlab (simplified).</p>
</div>
</figure>
If you're not used to builders and/or Rust this might look a bit odd but the
point is that each InlineComment</code> is turned into a
CreateMergeRequestDiscussion</code> with a body and position. Both of those are
mapped from the InlineComment</code> without much trouble.</p>
Let's try to apply this to spanned comments. The API (Parameters for multiline
comments</a>)
tells us that we need a line code</em> and type</em> for the start and end of each
comment. The line code is documented right below this header and combines the
hash of the file we're commenting on, the line number before the change and the
line number after the change. This is information we have, so it should be fine.
The API also wants a "type" and I quote</em>:</p>


Attribute: position[line_range][start][type]</code></li>
Type: string</li>
Required: yes</li>
Description: "Use new</code> for lines added by this commit, otherwise old</code>"</li>
</ul>
</blockquote>
Since our chosen API wrapper is well made it mirrors this. Well, I tried
implementing it, but it didn't work. It's a bit difficult to debug since the
comments still show up as normal single line comments. I did however compare the
request that is sent (top) with the one sent when using Gitlabs own web UI
(bottom):</p>

  line_range: Some(
  LineRange {
    start: LineCode {
      line_code: "1b[...]b7_12_10",
      type_: Old,
    },
    end: LineCode {
      line_code: "1b[...]b7_15_14",
      type_: Old,
    },
  }
)
</code></pre>
"line_range":{
  "start":{
    "line_code":"1b[...]b7_12_10",
    "type":null,
    "old_line":12,
    "new_line":10
  },
  "end":{
    "line_code":"1b[...]b7_15_14",
    "type":null,
    "old_line":15,
    "new_line":14
  }
}
</code></pre>
</div>
  What should be the same comment. Comparison between my
prr-fork (top) and the
Gitlab web-UI (bottom).</p>
</div>
</figure>
Interestingly, we see that Gitlab:</p>

Sets type</code> to null</code> even though it should be a string that is either
"old"</code> or "new"</code> according to the documentation.</li>
Sets old_line</code> and new_line</code> on line_range[start]</code> and line_range[end]</code>,
fields that don't exist in the documentation. They're also duplicated from
information that is already present in the line code.</li>
</ol>
Maybe there is a way to "bypass" the type system and modify the API calls with
custom fields? In any case, I've given up on spanned comments for now since
single line comments look almost exactly the same. If you have any ideas, feel
free to drop by the forked repo at sornas/prr
(github)</a>.</p>


Hello World
2022-08-15T00:00:00+00:00
This is the first post on this blog. We hope you will enjoy the articles to
come.</p>
The blog (at least in its first form) uses the static site generator
Zola</a>. The base theme is called
Apollo</a>, but at this point it has been
modified so much that the only parts that can be recognized are the link
highlights and the #</code> header prefix. If you're interested, the source is
available on Gitlab</a>.</p>

Thanks 🔗</a></h1>
This release marks a small milestone for external contributions to Spade. Out of the 17 merge requests in the changelog, 12 of them are by José Miguel Sánchez García, making it the first release where Frans hasn't made the majority of the changes! Thanks José 🎉</p>

`Contributors🔗</a></h1> This release contains contributions from Astrid Lauenstein, DasLixou, Ethan Uppal, José Miguel Sánchez García, and Oscar Gustafsson making it the release with the largest number of contributors to date, thanks everyone!</p>`

`The client🔗</a></h2> The client is less interesting to discuss here, and even took longer to write than the hardware implementation. If you are curious, the source code is available at https://gitlab.com/TheZoq2/quickscope/-/tree/main/client?ref_type=heads</a></p>`

`Functions can now contain wires🔗</a></h1> Previously, the language did not allow &</code> or inv &</code> in functions. This ended up being too restrictive as it is entirely possible to write combinatorial functions using them. This restriction is now lifted.</p>`

Other fixes 🔗</a></h1>
There have also been numerous small fixes and improvements that don't fit in this blog post, you can read them all in the Changelog</a></p>

SPADETID!🔗</a></h1>
Frans has started regularly streaming Spade development on https://www.twitch.tv/thezoq2/</a>. If you want to be notified when this happens, you can join the discord</a> and give yourself the `SPADETID</code> role.</p>`

`Latch-Up presentation🔗</a></h1> Two weeks ago, Frans presented Spade at Latch-Up 2024 in Boston. You can see a recording of the talk here:</p> </iframe>`

Language reference 🔗</a></h2>
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</a>.</p>

Open VCD files in a single click 🔗</a></h3>
In addition, if you run `swim setup-links</code> and run a terminal that supportsOSC8 hyperlinks</a>, swim will now print links to open the wave file from an individual test in a waveform viewer.</p>`
`</video></p>`

Publications 🔗</a></h2>
I managed to visit 2 workshops in the last month: Latte'23</a> and OSDA</a>. If you want to see the papers or presentations, check the publication list at https://spade-lang.org/#publications</p>

The Spade Blog

Spade 0.17.0

Spade 0.16.0

I Built a Processor for Advent of Code Day 8

Spade 0.15.0

Quickscope — A quick, but not dirty Integrated Logic Analyzer

Spade 0.14.0

Spade 0.13.0

Spade 0.12.0

Spade 0.11.0

Spade 0.10.0

Spade 0.9.0

Spade 0.8.0

Spade 0.7.0

Spade 0.6.0

Spade 0.5.0

Spade 0.4.0

Spade 0.3.0

Spade 0.2.0

Spade 0.1.0

ISY Summer of Code 2022

Hello World

The Spade Blog

Spade 0.17.0

Spade 0.16.0

I Built a Processor for Advent of Code Day 8

Spade 0.15.0

Quickscope — A quick, but not dirty Integrated Logic Analyzer

Spade 0.14.0

Spade 0.13.0

Spade 0.12.0

Bug Squashing🔗</a></h2> We've fixed quite a few bugs with this release. A lot of them related to compiler panics or miscompilations when writing zero size types.</p> Fix a few codegen bugs around enums with 1 variant and no members</li> Fix codegen bug when matching on zero size literals</li>

Spade 0.11.0

Spade 0.10.0

Spade 0.9.0

Spade 0.8.0

Spade 0.7.0

Misc smaller changes🔗</a></h2> It is now possible to write 1-2</code>, previously a space was required.</li> swim clean</code> no longer removes the compiled Spade compiler leading to faster clean build times.</li>

Spade 0.6.0

Spade 0.5.0

Spade 0.4.0

Write your top module in Spade, not Verilog!🔗</a></h2> A very exciting milestone is that writing Spade projects no longer requires writing a Verilog shim! Historically, every Spade project has needed an outermost Verilog file that takes care of two things:</p> Generating a reset signal.</li>

Spade 0.3.0

Spade 0.2.0