Compiles is not the same as correct
You will learn
Why green checks are not proof, and how to catch code that compiles and is wrong.
A compiler that accepts your code only tells you the code is well formed. It does not tell you the code means what you meant. This recording shows a tool that found specs which compile, pass every gate and are still read wrongly. The lesson for hardware is sharper still: a bug in silicon cannot be patched. Plant a bug yourself in the mutation recording and watch the tests catch it.
Try it
Open the mutation recording under Also try and count how many planted bugs the tests caught.

1,144 of 1,156 specs generate; 41 spec-shape pairs are read wrongly with every gate green.
specs/tutorial/03_operators.t27
// SPDX-License-Identifier: Apache-2.0
; 03 — Operators
; Lesson 3. Arithmetic, bitwise, shifts, comparison and the logical keywords.
; The bitwise group matters more here than in most languages: a spec that
; describes hardware spends most of its time on masks and shifts.
; phi^2 + 1/phi^2 = 3 | TRINITY
module tutorial-03-operators;
// ============================================================================
// Arithmetic
// ============================================================================
pub fn arithmetic(a: i32, b: i32) i32 {
const sum = a + b;
const difference = a - b;
const product = a * b;
const quotient = a / b;
const remainder = a % b;
return sum + difference + product + quotient + remainder;
}
// ============================================================================
// Bitwise
//
// `&` and, `|` or, `^` xor, `~` not. These are the tools for packing and
// unpacking fields, which is most of what a hardware spec does.
// ============================================================================
pub fn mask_and(value: u16, mask: u16) u16 {
return value & mask;
}
pub fn mask_or(value: u16, bits: u16) u16 {
return value | bits;
}
pub fn mask_xor(value: u16, bits: u16) u16 {
return value ^ bits;
}
// ============================================================================
// Shifts
//
// `<<` and `>>`. Extracting a field is a shift followed by a mask, and that
// pair appears in nearly every numeric spec in this corpus.
// ============================================================================
pub const EXP_SHIFT : u16 = 9;
pub const EXP_MASK : u16 = 0b111111;
pub fn extract_exponent(bits: u16) u16 {
return (bits >> EXP_SHIFT) & EXP_MASK;
}
pub fn place_exponent(exp: u16) u16 {
return (exp & EXP_MASK) << EXP_SHIFT;
}
// ============================================================================
// Comparison
// ============================================================================
pub fn is_greater(a: i32, b: i32) bool {
return a > b;
}
pub fn in_range(value: i32, low: i32, high: i32) bool {
return value >= low and value <= high;
}
// ============================================================================
// Logical
//
// `and`, `or` and `!` are spelled as words rather than symbols, so they never
// read as their bitwise cousins.
// ============================================================================
pub fn either(a: bool, b: bool) bool {
return a or b;
}
pub fn both(a: bool, b: bool) bool {
return a and b;
}
pub fn neither(a: bool, b: bool) bool {
return !a and !b;
}
// ============================================================================
// Tests
// ============================================================================
test "extract and place are inverse for a value that fits" {
const exp : u16 = 42;
try std.testing.expectEqual(exp, extract_exponent(place_exponent(exp)));
}
test "in_range is inclusive at both ends" {
try std.testing.expect(in_range(0, 0, 10));
try std.testing.expect(in_range(10, 0, 10));
try std.testing.expect(!in_range(11, 0, 10));
}
test "neither is true only when both are false" {
try std.testing.expect(neither(false, false));
try std.testing.expect(!neither(true, false));
}
All lessons
Module 1 · The chip
What an FPGA is, which chip we use, and how its pins meet the board.
Module 2 · Numbers in hardware
Bits, trits and number formats, and what arithmetic costs in logic.
Module 3 · Your t27 program
Write a spec, test it, and see why compiling is not the same as being right.
Module 4 · Inside t27c
How the compiler reads a spec and what it writes, including the native t27b.
Module 5 · From spec to hardware
The Verilog t27c writes, the cells it becomes, and what one LUT does.
Module 6 · Reading synthesis
What yosys reports about your design, and which warnings matter.
Module 7 · Place, route, timing
Where the cells land on the die, and whether the clock is met.
Module 8 · The bitstream
How a routed design becomes the bits the chip loads, with no Vivado.
Module 9 · On the board
Ask the chip who it is, load the bits, and check them.