The Spade Hardware Description Language

Type-Level Operations

Metatypes like #int, #bool, or #str are not limited to values: a set of operations are available at the type level via const generics. These allow expressing rich definitions, constraints and conditions. They must be surrounded by curly braces inside type expressions, but may appear naked in other contexts like gen if conditions.

The following operations are supported:

• Arithmetic, on #ints or #uints: +, -, *, /, %, <<, >>.
• Ordering comparisons, on #ints or #uints: <, >, <=, >=.
• Logical comparisons,, on #bools: !, &&, ||, ^^
• Equality comparisons, on any metatype: ==, !=.

Some extra function-like operations are supported:

• uint::bits_for(x) returns the minimum amount of bits needed to represent $𝑥$ as a uint value. This value can be calculated as $\lceil {log}_2\left(𝑥+1\right)\rceil$. Notably, it does not return $\lceil {log}_2\left(𝑥\right)\rceil$, which may be desirable when calculating address widths for a certain element count. Given a collection of $𝑁$ elements, addresses range from $0$ to $𝑁-1$, so in that case the correct expression would be uint::bits_for(N - 1).

• int::bits_for(x) returns the minimum amount of bits needed to represent $𝑥$ as an int value including the sign bit. The exact value returned is better understood piecewise:

  • When $𝑥\ge 0$, the unsigned representation of $𝑥$ can be augmented with a $0$ sign bit, so the number of bits required for its signed integer representation is uint::bits_for(x) + 1 or $\lceil {log}_2\left(𝑥+1\right)\rceil +1$.
  • When $𝑥<0$, the same number of bits is required to represent $𝑥$ than to represent its positive counterpart. Taking into account the asymmetry of two’s complement representation ($-𝑁$ maps to $𝑁-1$, not $𝑁$), the number of bits required for its signed integer representation is equivalent to int::bits_for(-x - 1), or uint::bits_for(-x - 1) + 1 or $\lceil {log}_2\left(-𝑥\right)\rceil +1$.

Using Const Generics as Values

Type-level operations can also be included in expressions directly using const type { ... }. This provides a shortcut around certain language impositions, for example allowing arbitrary-precision arithmetic and division to be performed freely and unconstrained from concerns like bit widths.

    const type { 300 / 7 /* spooky! but it's not actually a divider */ }