TinyComputers.io (Posts about verilog)

Part 4: 132 Tests, Zero Failures - Verifying the Sampo CPU on Real Hardware

A.C. Jokela — Sun, 15 Feb 2026 20:00:00 GMT

In Part 1, we designed the Sampo 16-bit RISC architecture. In Part 2, we synthesized it to an ECP5 FPGA on the ULX3S board. In Part 3, we built an LLVM backend so Rust could compile for it. But there was a glaring gap in the project: we'd never systematically verified that the hardware actually implements the ISA correctly.

The "Hello, Sampo!" demo program exercises maybe 10 of the CPU's 66 instructions. The LLVM backend generates code that assumes the hardware matches the spec. If a single instruction is subtly wrong - a carry flag not set, a branch offset miscalculated, a byte load sign-extending when it shouldn't - the entire toolchain is built on sand.

This post documents the process of building a comprehensive test suite, running it in simulation, finding a real pipeline hazard bug in the CPU, and then the surprisingly treacherous journey of getting those tests running on real FPGA hardware.

The Test Strategy

The approach is straightforward: write assembly programs that exercise every instruction in the ISA, compare results against known-good values, and report PASS or FAIL over UART. The testbench monitors the serial output, and if it sees "FAIL" anywhere, the test run fails.

Each test follows the same pattern:

; Load known inputs
LIX  R8, 0x1234
LIX  R9, 0x5678

; Execute the instruction under test
ADD  R10, R8, R9

; Check the result
MOV  R4, R10          ; actual value
LIX  R5, 0x68AC       ; expected value
JALX check_eq         ; prints PASS or FAIL

The check_eq subroutine compares R4 (actual) against R5 (expected) and prints the result over the UART. This makes the test output human-readable and machine-parseable:

=== ALU Tests ===
ADD basic: PASS
ADD zero: PASS
ADD carry out: PASS
ADD overflow: PASS
SUB basic: PASS
...
Done.

The Test Framework

Every test program begins with a block of helper subroutines that handle UART communication and result reporting. The core is a busy-wait loop that polls the MC6850-compatible UART status register:

.equ ACIA_STATUS 0x80
.equ ACIA_DATA   0x81

print_char:
    ; R5 = character to output
.wait:
    INI  R6, ACIA_STATUS    ; Read status register
    AND  R7, R6, R6         ; Copy to R7
    ADDI R7, -2             ; Check if TX ready (bit 1)
    BNE  .wait              ; Loop until ready
    OUTI ACIA_DATA, R5      ; Send character
    JR   RA                 ; Return

The check_eq helper prints "PASS" or "FAIL" based on a register comparison, and the print_str helper walks a null-terminated string byte by byte. These routines are duplicated in each test file rather than linked - there's no linker in this toolchain, just a single-file assembler.

Test Coverage

We organized the tests into 10 programs, each targeting a specific area of the instruction set:

Test Program	Instructions Tested	Test Count
test_alu	ADD, SUB, AND, OR, XOR, NEG + flags	20
test_addi	ADDI with signed immediates + flags	10
test_shift	SLL, SRL, SRA, ROL, ROR, SWAP (1/4/8-bit variants)	17
test_muldiv	MUL, MULH, DIV, DIVU, REM, REMU	12
test_loadstore	LW, LB, LBU, SW, SB + offset variants	11
test_branch	All 16 branch conditions (taken + not taken)	24
test_jump	J, JR, JALR, JX, JALX	6
test_stack	PUSH, POP, CMP, TEST, MOV	12
test_misc	EXX, GETF, SETF, SCF, CCF, NOP	9
test_extended	ADDIX, SUBIX, ANDIX, ORIX, XORIX, SLLX, SRLX, SRAX	11
Total		132

The branch tests are particularly thorough - each of the 16 conditions (BEQ, BNE, BLT, BGE, BLTU, BGEU, BMI, BPL, BVS, BVC, BCS, BCC, BGT, BLE, BHI, BLS) gets tested both for the taken and not-taken case. We set up flags with arithmetic, then verify the branch goes the right way.

Finding a Real Bug: The Pipeline Hazard

The first time we ran the full test suite in simulation, 130 of 132 tests passed. Two tests in test_loadstore were failing: the multi-word store/load test and a load with offset test.

The failing pattern was consistent: any test that performed a store followed immediately by a load from a different address would read stale data. The load would return the value from the previous memory operation instead of the current one.

The root cause was a pipeline hazard between the MEMORY and FETCH states. Here's what was happening:

Cycle N:   MEMORY state - store completes, mem_ready asserts
Cycle N+1: FETCH state  - new instruction fetch begins

The problem: mem_ready is a one-cycle delayed version of mem_valid (because the RAM is synchronous). When the CPU transitions from MEMORY to WRITEBACK to FETCH, the mem_ready signal from the store was still asserted during the first cycle of the next FETCH. The CPU latched the stale mem_rdata from the previous store operation as if it were the new instruction.

The fix was to add a WRITEBACK state after every MEMORY operation - not just loads, but stores too. This gives mem_ready a cycle to deassert before the next FETCH begins:

Before: MEMORY → FETCH          (mem_ready still high from store)
After:  MEMORY → WRITEBACK → FETCH  (mem_ready deasserts during WRITEBACK)

A one-line change to the next-state logic:

`ST_MEMORY: begin
    if (mem_ready) begin
        // Always go through WRITEBACK after MEMORY.
        // For stores: allows mem_ready to deassert before
        // next FETCH (prevents stale rdata latch).
        next_state = `ST_WRITEBACK;
    end
end

This is exactly the kind of bug that simulation catches and manual inspection misses. The instruction executes correctly in isolation - it's only the interaction between consecutive memory operations that triggers the hazard. After the fix, all 132 tests passed in simulation.

Taking It to the FPGA

With simulation clean, the next step was running the tests on real hardware. The ULX3S board has an FTDI FT231X USB-serial chip connected to the FPGA, so UART output appears on a serial port at 115200 baud.

There was an immediate practical problem: the test programs run fast. At 12.5 MHz, the entire 20-test ALU suite completes in about 30 milliseconds. By the time openFPGALoader finishes programming the FPGA and releases the USB port, the test output is long gone. The FTDI chip has a small receive buffer, but 364 characters of test output overflows it before you can open the serial port.

The solution: patch the hex files to loop instead of halting. Replace the HALT instruction with a delay loop followed by a jump back to the reset vector. The test runs, outputs its results, waits about half a second, and starts over. You can open the serial port at any time and catch a complete iteration.

The Delay Loop Patch

The hex_loop_patch.py script performs binary patching on the assembled hex files. It finds the HALT instruction (encoded as 0xE100) and replaces it with a delay loop:

; Delay ~0.38 seconds at 12.5 MHz
    LIX  R8, 0x0008       ; outer counter
outer:
    LIX  R9, 0xFFFF       ; inner counter = 65535
inner:
    ADDI R9, -1
    BNE  inner
    ADDI R8, -1
    BNE  outer
    JX   0x0100            ; jump back to reset vector

The first version of this script inserted these 10 words at the HALT position. This seemed obviously correct. The tests ran on FPGA. Characters appeared on the serial port.

They were the wrong characters.

The Address Shift Bug

The FPGA output for the "Hello, Sampo!" test program was \x08\x08\x08\x08 - four backspace characters, repeating forever. The ALU test suite showed truncated output with roughly 45% of characters missing. Same pattern at 12.5 MHz and 6.25 MHz, ruling out timing violations. Simulation with realistic UART timing (1,080 cycles per byte, matching the hardware baud rate) passed perfectly.

I spent considerable time investigating the wrong theories. Was the UART transmitter dropping bytes? Was there a clock domain crossing issue? Was $readmemh in Yosys interpreting the hex file differently from Icarus Verilog? None of these panned out.

The breakthrough came from staring at \x08. That's the byte value 8. Where would 8 come from? The "Hello, Sampo!" program loads its message pointer with LIX R4, message where message is the label for the string data. In the assembled hex, message resolves to address 0x011E - the byte immediately after the HALT instruction.

And there it was. Look at the assembly structure:

done:
    HALT                    ; address 0x011C
message:
    .asciz "Hello, Sampo!\n" ; address 0x011E

The string data lives immediately after HALT. When hex_loop_patch.py inserts 10 words of delay loop code at the HALT position, it pushes the string data down by 20 bytes. But the LIX R4, 0x011E instruction still points to the original address. At 0x011E there's now the second word of LIX R8, 0x0008 - which contains the value 0x0008. The low byte is 0x08.

The CPU faithfully reads byte 0x08 from the patched address, outputs it via UART, advances the pointer to 0x011F where the high byte is 0x00 (the null terminator), and stops. One \x08 per iteration, four iterations captured. Mystery solved.

This same address shift corrupted every test program. The test strings ("ADD basic: ", "PASS\n", etc.) all live after HALT and all got displaced. The CPU was reading from locations that now contained delay loop machine code instead of ASCII text. Some fragments of text survived because adjacent strings partially overlapped with their shifted locations, producing the truncated output we saw.

The Fix

The correct approach: don't shift any data. Place the delay loop at address 0x0000 - the 256 bytes of unused memory before the 0x0100 reset vector - and replace the single-word HALT with a single-word relative J (jump) instruction that jumps backward to the loop code. One word replaces one word. No data moves.

# Place delay loop at address 0x0000 (unused space)
for i, w in enumerate(LOOP_PATCH):
    words[loop_base + i] = w

# Replace HALT with J instruction to address 0x0000
# J encoding: opcode 0x9, 12-bit signed offset
# target = PC + 2 + (sign_extend(offset) << 1)
offset = (target_addr - halt_addr - 2) // 2
j_word = 0x9000 | (offset & 0xFFF)
words[halt_idx] = j_word

There's a subtle complication: the J instruction shares opcode 0x9 with JR (register indirect jump) and JALR (jump and link register). The decoder distinguishes them by specific bit patterns in the offset field. If the calculated offset happens to have bits[3:0] == 0x1 and bits[11:8] != 0xF, the decoder interprets it as JALR instead of J. The script tries successive target addresses (0x0000, 0x0002, 0x0004, ...) until it finds one that doesn't collide with the JR/JALR encoding space.

After the fix, the patched hex files have exactly the same number of words as the originals. The only changes are the delay loop code written to the zero page and the HALT word replaced with a backward jump.

With the corrected patcher, the "Hello, Sampo!" program finally works on the FPGA - looping cleanly with zero character loss:

The Testbench: Trusting but Verifying

One important discovery during this process: the simulation testbench had tx_ready = 1 permanently. The simulated UART never pushed back on the CPU - it accepted every byte instantly. This meant the CPU's busy-wait loop (INI R6, ACIA_STATUS / ADDI R7, -2 / BNE wait) was never actually tested in simulation. The status register always returned "ready," so the loop body executed zero times.

On real hardware, the UART transmitter takes about 87 microseconds per byte at 115200 baud. The busy-wait loop runs hundreds of times per character, exercising the INI instruction, the AND/ADDI flag-setting sequence, and the BNE branch in a tight loop. If any of those instructions had a subtle bug, it would only manifest on hardware.

We added realistic UART timing to the testbench:

parameter TX_BYTE_CYCLES = 108 * 10;  // ~1080 cycles per byte
reg [15:0] tx_delay_cnt;

always @(posedge clk) begin
    if (tx_valid && tx_ready) begin
        tx_ready <= 0;
        tx_delay_cnt <= TX_BYTE_CYCLES;
    end else if (tx_delay_cnt > 0) begin
        tx_delay_cnt <= tx_delay_cnt - 1;
        if (tx_delay_cnt == 1)
            tx_ready <= 1;
    end
end

With this change, simulation exercises the same code paths as the hardware. All 132 tests still pass - the UART flow control logic was correct all along, it just wasn't being tested.

Running All Tests on the FPGA

Your browser does not support the video tag.

With the patch bug fixed, we ran the complete suite. Each test requires a separate FPGA build (Yosys synthesis, nextpnr place-and-route, ecppack bitstream generation), programming via JTAG, and serial capture. The Makefile automates the entire pipeline:

fpga-%: $(BUILD_DIR)/sampo_%.bit
    openFPGALoader -b ulx3s $<
    sleep 1
    python3 fpga_capture.py $(SERIAL_PORT) $(SERIAL_BAUD) 5

The fpga_capture.py script opens the serial port, discards the first partial iteration (we might join mid-stream), waits for the === ... === header line that starts each test, captures everything until the header repeats, and outputs one clean iteration.

The results:

========================================
=== FPGA: test_alu ===
========================================
=== ALU Tests ===
ADD basic: PASS
ADD zero: PASS
ADD carry out: PASS
...
AND clr C/V: PASS
All tests passed!

========================================
=== FPGA: test_addi ===
========================================
...
All tests passed!

...

========================================
FPGA Test Summary: 10 passed, 0 failed
========================================

All 10 test suites pass. All 132 individual tests pass. Zero failures on real hardware.

Test Suite	Tests	FPGA Result
ALU (ADD, SUB, AND, OR, XOR)	20	All PASS
ADDI (immediate arithmetic)	10	All PASS
Shift (SLL, SRL, SRA, ROL, SWAP)	17	All PASS
MulDiv (MUL, DIV, REM variants)	12	All PASS
Load/Store (LW, LB, LBU, SW, SB)	11	All PASS
Branch (all 16 conditions)	24	All PASS
Jump (J, JR, JALR, JX, JALX)	6	All PASS
Stack (PUSH, POP, CMP, TEST, MOV)	12	All PASS
Misc (EXX, GETF, SETF, SCF, CCF, NOP)	9	All PASS
Extended (ADDIX, SUBIX, SLLX, etc.)	11	All PASS
Total	132	All PASS

What This Means

Having all 132 ISA tests pass on hardware is a significant milestone for the project. It means:

The Verilog RTL is correct. Every instruction in the Sampo ISA produces the right result, sets the right flags, and handles edge cases (zero, overflow, carry, sign extension) correctly. Not just in behavioral simulation, but in synthesized logic on a real FPGA running at 12.5 MHz.

The assembler is correct. All 66 instructions encode properly. Branch offsets calculate correctly. Extended instructions (LIX, JALX, OUTX) with their 32-bit encoding work. The sasm Rust assembler and the Verilog decoder agree on every instruction format.

The LLVM backend has a solid foundation. When the Rust compiler generates a ADD or BNE or JALX, the hardware will execute it correctly. The test suite doesn't exercise every possible code generation pattern, but it validates every primitive instruction that the compiler builds upon.

The UART subsystem works end-to-end. Status register polling, TX busy-wait, byte transmission, baud rate generation - all verified on hardware. The MC6850-compatible interface works exactly as specified.

Lessons Learned

Test your assumptions. The testbench had tx_ready = 1. It went unnoticed because simulation "worked." The real hardware exercises code paths that simulation shortcuts. Add realistic peripheral timing to your testbenches from day one.

Binary patching is fragile. Inserting bytes into a binary without updating references is a classic relocation bug - the same class of problem that linkers exist to solve. If your patch changes the size of anything, every address reference past the patch point is wrong. The fix - placing the patch in unused address space and using a same-size replacement instruction - avoids the problem entirely.

Simulation is necessary but not sufficient. The pipeline hazard bug was caught by simulation. The address shift bug was invisible to simulation (both used the same patching script, and the original programs - without patching - worked fine). You need both simulation and hardware testing, exercising different code paths and different failure modes.

Systematic testing finds bugs that demos don't. "Hello, Sampo!" worked on the FPGA from day one. It exercises LIX, LBU, CMP, BEQ, INI, OUTI, ADDI, and J - about 8 instructions. The pipeline hazard only manifested when a store was followed by a load to a different address, a pattern that doesn't occur in a simple print loop. You need tests specifically designed to exercise corner cases.

What's Next

The entire Sampo project - assembler, emulator, Verilog RTL, FPGA build scripts, test suite, and LLVM backend - is open source on GitHub. With hardware verification complete, the next steps might be:

Running Rust-compiled code on the FPGA. The LLVM backend generates assembly, the assembler produces hex files, and we now know the hardware executes them correctly. Closing this loop - cargo build to blinking LEDs - is the obvious next milestone.
Adding more peripherals. The ULX3S has 32MB of SDRAM, an HDMI output, a microSD slot, and an ESP32 co-processor. Each of these opens up interesting possibilities for a working 16-bit computer.
Performance optimization. The CPU currently runs at 12.5 MHz with a multi-cycle FSM (5-8 cycles per instruction). Pipelining could push this significantly higher on the ECP5.

But first: 132 tests, zero failures. The Sampo CPU works.

This is Part 4 of the Sampo series. Part 1 covers architecture design, Part 2 covers FPGA implementation, and Part 3 covers the LLVM backend.

Recommended Resources

OrangeCrab ECP5 FPGA Board - A compact Lattice ECP5 board with DDR3 and USB-C, available on Amazon
ECP5 FPGA Development Boards - Other ECP5 boards available on Amazon
Getting Started with FPGAs by Russell Merrick - Beginner-friendly introduction with Verilog and VHDL examples
FTDI USB Serial Adapters - Useful for UART debugging with FPGAs
USB Logic Analyzers - Essential for debugging digital signals

Source Code

github.com/ajokela/sampo - CPU architecture, assembler, emulator, Verilog RTL, test suite, and FPGA build scripts
github.com/ajokela/llvm-sampo - LLVM backend and Rust target specification

Review of "Getting Started with FPGAs" by Russell Merrick

A.C. Jokela — Sat, 07 Feb 2026 14:13:49 GMT

Introduction and Overview

Field programmable gate arrays occupy a fascinating position in the landscape of digital electronics: immensely powerful, endlessly flexible, and yet stubbornly inaccessible to newcomers. Unlike microcontrollers, which have benefited from decades of beginner-friendly ecosystems like Arduino and Raspberry Pi, FPGAs have long remained the province of electrical engineering graduates and industry professionals. The learning curve is steep, the toolchains are complex, and the fundamental paradigm shift from sequential software thinking to parallel hardware description is enough to discourage many aspiring digital designers before they write their first line of HDL. Russell Merrick's Getting Started with FPGAs: Digital Circuit Design, Verilog, and VHDL for Beginners, published by No Starch Press in 2024, makes a deliberate and largely successful attempt to change that.

Merrick brings a distinctive combination of credentials to this task. A University of Massachusetts electrical engineering graduate with a master's degree in the same field, he has worked in defense at BAE Systems and L-3 Communications, in aerospace at satellite propulsion startup Accion Systems, and in commercial electronics at fitness wearable company WHOOP. More importantly for a book of this nature, he has been creating FPGA educational content at nandland.com and its accompanying YouTube channel since 2014, even designing his own FPGA development board, the Nandland Go Board. This decade of answering beginner questions on Stack Overflow and producing tutorial content informs every page of the book. Merrick knows exactly where newcomers get stuck, because he has been watching them get stuck for years.

The book spans 11 chapters plus two appendices across roughly 280 pages, targeting the Lattice iCE40 family of FPGAs. This choice of hardware is itself a pedagogical decision: iCE40 devices are inexpensive, the toolchain (iCEcube2 and Diamond Programmer) is lightweight, and the open source community has embraced Lattice parts for low-level hacking. More expensive FPGAs from AMD (Xilinx) or Intel (Altera) come with sophisticated but overwhelming development environments that can intimidate beginners. By choosing the simpler end of the market, Merrick keeps the focus on understanding FPGA fundamentals rather than wrestling with tool complexity.

The Dual-Language Approach

Perhaps the most distinctive pedagogical choice in the book is Merrick's decision to present every code example in both Verilog and VHDL, side by side. This is no small commitment for an author. It effectively doubles the code content of the book and requires careful attention to ensure that both versions are correct, idiomatic, and illustrative of the same concepts. The payoff, however, is substantial: readers can follow along with whichever language suits their situation without needing to purchase a second book or mentally translate between the two.

Merrick provides a thoughtful comparison of the two languages in Chapter 1 that avoids the partisan flame wars common in FPGA circles. He notes that VHDL, born from the U.S. Department of Defense and inheriting Ada's strong typing, requires more verbose code but catches errors at compile time. Verilog, syntactically closer to C and weakly typed, is more concise but will happily let you write incorrect code without complaint. He even includes a Google Trends analysis showing regional preferences: Verilog dominates in the United States, China, and South Korea, while VHDL is preferred in Germany and France. His practical advice is refreshingly simple: learn whichever language your school or employer uses.

The dual-language presentation also serves as an implicit lesson in the differences between the two HDLs. Readers can observe firsthand how VHDL's strong typing forces explicit resize() calls and type conversions that Verilog handles automatically, or how VHDL's process blocks map to Verilog's always blocks. These side-by-side comparisons provide a deeper understanding of both languages than either one alone could offer.

Building Foundations: Logic, Memory, and Time

The book's first four chapters establish the fundamental building blocks of FPGA design with admirable clarity. Chapter 1, "Meet the FPGA," provides historical context starting from the Xilinx XC2064 in 1985 and surveys the modern FPGA landscape, including the AMD acquisition of Xilinx for $35 billion and Intel's earlier purchase of Altera for $16.7 billion. The chapter's comparison of FPGAs versus microcontrollers versus ASICs across dimensions of cost, speed, power, flexibility, and ease of use is presented in a clean table that serves as a useful reference throughout the reader's career. Merrick is honest about where FPGAs fall short: they are more expensive than microcontrollers at scale, consume more power, and are harder to use. But when you need raw bandwidth, parallel computation, or hardware flexibility, nothing else will do.

Chapter 2 walks through hardware and tool setup, getting readers to their first working FPGA project: wiring switches to LEDs. This "hello world" equivalent may seem trivial, but it introduces the full development workflow: writing HDL code, creating a project, adding pin constraints, running the build, connecting the board, and programming the FPGA. Each step is a potential stumbling block for beginners, and Merrick guides through them methodically.

Chapter 3 on Boolean algebra and the look-up table is where the book begins to reveal its deeper ambitions. Rather than treating logic gates as abstract mathematical curiosities, Merrick connects them directly to the physical reality inside an FPGA. The key insight, clearly articulated, is that discrete logic gates do not actually exist inside modern FPGAs. Instead, all Boolean operations are implemented through look-up tables, programmable devices that can represent any truth table you can imagine. A single three-input LUT can replace an AND gate, an OR gate, an XOR gate, or any combination thereof. This understanding, that LUTs and flip-flops are the two fundamental building blocks from which all FPGA designs are constructed, is the conceptual foundation upon which the entire book rests.

Chapter 4 introduces the flip-flop and with it the concept of state. Where LUTs handle combinational logic, flip-flops provide sequential logic, giving the FPGA memory of what happened previously. The chapter carefully distinguishes between combinational and sequential logic, explains the clock signal and its role in synchronizing operations, and warns about the dangers of latches, an accidental design pattern that causes unpredictable timing behavior. Merrick's years of answering beginner questions are evident here; the latch warning, including the specific synthesis warning message readers should watch for, addresses one of the most common FPGA beginner mistakes.

Simulation, Testing, and the Black Box Problem

Chapter 5, on simulation, contains some of the book's most valuable practical wisdom. Merrick frames the motivation perfectly: your FPGA is essentially a black box. You can change the inputs and observe the outputs, but you cannot see what is happening inside. Simulation cracks open that black box, letting you examine every internal signal, register, and wire as your design executes.

He drives this point home with an anecdote from his professional experience: a coworker spent weeks debugging an FPGA design using oscilloscopes and logic analyzers, trying to find a data corruption issue on the physical hardware. Merrick checked the code out, built a simulation testbench, and found the bug within hours. The lesson is clear: simulation is not an optional nicety but an essential part of the FPGA development process that will save you enormous amounts of time.

The chapter introduces EDA Playground, a free web-based simulator, as the primary tool. This is a pragmatic choice that eliminates the barrier of downloading and configuring multi-gigabyte vendor tools. Readers learn to write testbenches, the HDL code that exercises a design by providing inputs and monitoring outputs. The first testbench, for the AND gate project from Chapter 3, walks through every detail: declaring signals, instantiating the unit under test, driving stimulus with delay statements, and generating waveform output for visual analysis. The progression to more sophisticated testing, including self-checking testbenches that automatically verify correctness and a discussion of formal verification, shows that Merrick understands the professional importance of testing even as he keeps the material accessible.

Common Modules and the Building-Block Philosophy

Chapter 6, "Common FPGA Modules," represents a turning point in the book's complexity. Having established the primitive components, LUTs and flip-flops, Merrick now shows how to combine them into reusable building blocks: multiplexers, demultiplexers, shift registers, RAM, and FIFOs. Each module is explained conceptually, implemented in both Verilog and VHDL, and connected to practical applications.

The FIFO (First In, First Out) implementation is particularly well done. Merrick walks through the complete design including read and write address management, element counting, full and empty flags, and "almost full" and "almost empty" threshold flags. The code is production-quality, handling edge cases like simultaneous read and write operations and providing anticipatory flags that let higher-level modules stop writing before the FIFO actually overflows. This is not a toy example; it is a genuinely useful piece of infrastructure that readers can adapt for their own projects.

The Linear Feedback Shift Register (LFSR) implementation showcases a more specialized application: generating pseudo-random sequences using nothing more than shift registers and XOR gates. Merrick explains why this matters in practice, as LFSRs are used in everything from encryption to test pattern generation, and provides the implementation alongside a conceptual explanation of why specific feedback tap positions produce maximum-length sequences.

The Build Process Demystified

Chapter 7 tackles synthesis, place and route, and crossing clock domains, subjects that many beginner texts either skip or relegate to appendices. Merrick treats them as essential knowledge, and rightly so. Understanding what happens when you press the "Build FPGA" button is critical for writing efficient, correct designs.

The synthesis discussion is particularly strong. Merrick explains logic optimization, the tool's process of minimizing the resources your design consumes, and connects it to the utilization report that tells you how many LUTs, flip-flops, and block RAMs your design uses. He provides practical guidance on what to do when your design does not fit: switch to a larger FPGA, rewrite resource-intensive modules, or remove functionality. His anecdote about a division operation that forced a million-dollar hardware upgrade to a larger FPGA family illustrates the real-world consequences of resource-intensive code.

The section on non-synthesizable code addresses a source of deep confusion for beginners transitioning from software: not all valid Verilog or VHDL code can be translated into physical hardware. Time delays, print statements, file operations, and certain loop constructs exist solely for simulation and will be silently ignored or flagged during synthesis. Merrick's treatment of synthesizable versus non-synthesizable for loops is especially valuable. In software, a for loop iterates sequentially over time. In synthesizable FPGA code, a for loop unrolls into replicated hardware that executes simultaneously in a single clock cycle. Beginners who expect a 10-iteration loop to take 10 clock cycles will be baffled when it completes in one. Merrick shows both the pitfall and the correct pattern for implementing sequential iteration using counters and if statements.

The clock domain crossing section covers a topic that trips up even experienced FPGA designers. When signals pass between parts of a design running at different clock frequencies, metastability can cause unpredictable behavior. Merrick explains the problem and presents standard solutions: double-flop synchronizers for single-bit signals and FIFOs for multi-bit data transfers.

State Machines and the Memory Game

Chapter 8, "The State Machine," brings together all the preceding material in the book's most ambitious project: an interactive memory game using a seven-segment display. State machines are the standard way to implement sequential behavior in FPGAs, a series of states connected by transitions triggered by events. Merrick presents two implementation styles (two-process and one-process blocks), discusses best practices, and then launches into a full project that requires planning the state machine, organizing the design across multiple modules, interfacing with a seven-segment display, and writing comprehensive testbenches.

The memory game project is a strong capstone for the book's middle section. It requires the reader to synthesize knowledge of flip-flops, multiplexers, RAM, state machines, and physical I/O constraints into a working interactive system. The project is complex enough to feel like genuine FPGA engineering but simple enough to complete without despair.

FPGA Primitives and the Hardware Reality

Chapter 9 examines the specialized hardware blocks that differentiate FPGAs from simple arrays of LUTs and flip-flops. Block RAM provides dedicated memory resources that are faster and more efficient than flip-flop-based storage. The Digital Signal Processing (DSP) block offers hardened multiply-accumulate units that are essential for math-intensive applications like filtering and signal processing. The Phase-Locked Loop (PLL) generates new clock frequencies from an input clock, enabling designs that need multiple clock domains.

Merrick explains both the capabilities and the creation process for each primitive, covering both instantiation (directly connecting to the hardware block in your code) and the GUI approach (using vendor tools to configure the block graphically). This dual treatment acknowledges that different workflows suit different situations and different engineers.

Numbers, Math, and the Rules of Binary Arithmetic

Chapter 10, "Numbers and Math," is arguably the most technically dense chapter in the book, and it may also be the most practically valuable. Performing mathematical operations inside an FPGA is fraught with subtle pitfalls that can produce silently incorrect results. Merrick distills years of hard-won experience into six clear rules that, if followed, will prevent the most common binary math errors.

The chapter progresses methodically through addition, subtraction, multiplication, and division, showing both correct and incorrect implementations at each step. The emphasis on showing code that produces wrong answers is a particularly effective teaching strategy. When Merrick demonstrates that adding two 4-bit unsigned numbers (9 + 11) and storing the result in a 4-bit output gives 4 instead of 20, the reader understands viscerally why Rule #1 (the result should be at least 1 bit bigger than the biggest input) matters. The discussion of sign extension, the process of increasing a binary number's bit width while preserving its sign and value, is handled with exceptional clarity.

The treatment of division is refreshingly honest. Merrick states plainly that division is resource-intensive and should be avoided when possible inside an FPGA. He presents three alternatives: restricting divisors to powers of 2 (implemented as simple shift-right operations), using precalculated lookup tables stored in block RAM, and spreading the operation across multiple clock cycles using iterative subtraction. His anecdote about "the million-dollar divide," where a single division operation forced an upgrade to a more expensive FPGA family at a cost exceeding $1 million in hardware changes, makes the point memorably.

The fixed-point arithmetic section that closes the chapter is an excellent primer on representing decimal values in hardware without the complexity and resource cost of floating-point. Merrick introduces the UX.Y and SX.Y notation for unsigned and signed fixed-point formats, explains the conversion between formats, and works through addition and multiplication examples that demonstrate the rules for matching decimal widths and sizing outputs.

I/O, SerDes, and the Edge of the Chip

The final technical chapter covers getting data in and out of the FPGA, where the digital logic meets the physical world. Merrick covers GPIO pin configuration including I/O buffers, output enable signals, and bidirectional communication. He explains operating voltage standards (LVCMOS33, TTL, LVCMOS25), drive strength in milliamps, and slew rate, the speed at which a signal transitions between high and low. The discussion of single-ended versus differential signaling provides useful background for understanding high-speed interfaces.

The SerDes (serializer/deserializer) section introduces the concept of converting parallel data to serial for high-speed transmission and back again at the receiver. While the iCE40 FPGAs used in the book's projects do not include SerDes blocks, Merrick covers the topic at a conceptual level to prepare readers who may eventually work with more capable devices. This forward-looking coverage, explaining concepts that exceed the current hardware's capabilities, is a sensible choice that increases the book's long-term value.

The Appendices: Beyond the Technical

Appendix A surveys three development boards compatible with the book's projects: the Nandland Go Board, the Lattice iCEstick, and the Alchitry Cu. The Nandland Go Board, designed by Merrick himself, is naturally the most fully supported option, but the inclusion of alternatives from other vendors demonstrates good faith.

Appendix B, "Tips for a Career in FPGA Engineering," is an unusual and welcome addition to a technical book. Merrick covers resume construction, interview preparation, and job offer negotiation with the practical specificity of someone who has been on both sides of the hiring table. He advises listing HDL projects prominently on resumes, preparing for whiteboard coding exercises in Verilog or VHDL, and understanding that FPGA engineering positions often command premium salaries due to the specialized skill set. For readers considering FPGA development as a career rather than a hobby, this appendix alone could be worth the price of the book.

Strengths and Unique Value

The book's greatest strength is its accessibility. Merrick has an uncommon talent for explaining hardware concepts in software-friendly terms without being condescending or imprecise. His comparison of low-level FPGA programming to building with individual LEGO bricks while high-level microcontroller programming is like working with preconstructed LEGO sets captures the essential difference in a way that immediately resonates. The parallel-versus-serial thinking distinction, hammered home from the first chapter, is the single most important conceptual hurdle for software developers entering FPGA territory, and Merrick addresses it directly and repeatedly.

The hands-on projects embedded throughout the book, from wiring switches to LEDs through blinking an LED, debouncing a switch, selectively blinking LEDs, and building a memory game, provide a satisfying progression of complexity. Each project builds on concepts from previous chapters and results in something that works on real hardware, providing the tangible feedback that keeps learners motivated.

The dual Verilog/VHDL presentation is a genuine differentiator. Most FPGA books choose one language and leave readers of the other to fend for themselves. Merrick's commitment to both languages, while surely doubling his authorial workload, produces a reference that serves a broader audience and provides implicit comparative education that deepens understanding of both languages.

The inclusion of professional engineering wisdom, from the million-dollar divide anecdote to the latch warnings to the career advice appendix, gives the book a practical grounding that purely academic treatments lack. Merrick writes as someone who has shipped FPGA designs in defense, aerospace, and consumer electronics, and that experience informs his choices about what to emphasize and what to warn against.

Limitations and Missed Opportunities

The book's commitment to the iCE40 platform, while pedagogically sound, does impose limitations. These are small, inexpensive FPGAs with limited resources, no hard processor cores, and minimal specialized IP blocks. Readers who complete the book and want to tackle more ambitious projects, say, implementing a RISC-V soft processor or building a video processing pipeline, will need to transition to AMD or Intel FPGA platforms with significantly different (and more complex) toolchains. The book provides a conceptual foundation for that transition but no practical guidance through it.

The Windows-centric tooling requirement is a notable friction point. Merrick acknowledges that the iCE40 tools work best on Windows and recommends a virtual machine for Mac and Linux users. In an era when open source FPGA tools like Yosys and nextpnr have matured significantly, especially for iCE40 targets, the absence of any mention of the open source toolchain feels like a missed opportunity. For Linux users in particular, the Yosys/nextpnr/IceStorm flow provides a native, arguably simpler development experience than running Windows tools in a VM.

The book could benefit from more substantial treatment of debugging workflows. While simulation is covered well, on-FPGA debugging receives only brief mention. Topics like using integrated logic analyzers, reading back internal signals through JTAG, or structured approaches to narrowing down hardware bugs would strengthen the book's practical value for readers who move beyond simulation into real hardware deployment.

Some readers may find the book's pace in early chapters slow if they already have digital logic background from university courses. The extensive coverage of Boolean algebra, truth tables, and logic gates in Chapter 3, while valuable for true beginners, may feel redundant for readers with prior exposure. Conversely, the later chapters on clock domain crossing, SerDes, and fixed-point arithmetic accelerate considerably and could benefit from additional worked examples.

Who Should Read This Book

The book is best suited for three audiences. First, software developers who are curious about hardware and want to understand what happens below the abstraction layer of their programming languages. The explicit comparisons between software concepts (sequential execution, for loops, variables) and their FPGA counterparts (parallel execution, hardware replication, signals and registers) make this a natural bridge text. Second, electronics hobbyists and makers who have experience with microcontrollers like Arduino or Raspberry Pi and want to explore the next level of hardware control. Third, university students encountering FPGAs in coursework who need a more approachable companion text to supplement dense academic material.

Experienced FPGA engineers will find little new technical content here, though the book's explanations may provide useful language for mentoring junior colleagues. Readers looking for advanced topics like high-level synthesis, SystemVerilog verification methodology, or FPGA-based machine learning acceleration will need to look elsewhere.

Conclusion

Getting Started with FPGAs succeeds at its stated goal: building a solid foundation for anyone interested in the world of FPGA design. Russell Merrick has distilled a decade of educational content creation into a coherent, well-structured text that respects the reader's intelligence while acknowledging the genuine difficulty of the subject matter. The dual-language approach, the hands-on projects, the honest treatment of where FPGAs excel and where they fall short, and the professional engineering perspective all contribute to a book that fills a genuine gap in the FPGA literature.

The book does not attempt to be comprehensive. It will not teach you everything about Verilog or VHDL, will not prepare you to design a production FPGA system from scratch, and will not cover the full depth of any single topic it addresses. What it will do is give you a clear mental model of how FPGAs work at a fundamental level, equip you with enough Verilog and VHDL to write and simulate basic designs, and provide the conceptual vocabulary to continue learning independently. For a subject as intimidating as FPGA development, that is no small achievement.

In the broader context of No Starch Press's catalog of accessible technical books, Getting Started with FPGAs fits naturally alongside titles that demystify complex subjects without dumbing them down. It occupies a niche that has been surprisingly underserved: the true beginner FPGA book that takes the reader seriously. For anyone who has stared at an FPGA development board with a mixture of curiosity and trepidation, wondering how to bridge the gap between software thinking and hardware reality, this book provides a clear and well-lit path forward.

Part 2: Implementing Sampo on the ULX3S FPGA

A.C. Jokela — Mon, 02 Feb 2026 18:00:00 GMT

After designing the Sampo RISC architecture on paper (complete with a working assembler and emulator) it's time to bring it to life in silicon. Or at least, in programmable logic. This post documents the hardware selection and implementation planning for synthesizing Sampo on an FPGA.

The Story So Far

If you haven't read Part 1 of this series, here's the quick version: Sampo is a 16-bit RISC CPU designed to bridge the gap between clean RISC design principles and Z80-friendly features. It has 16 general-purpose registers, ~66 instructions, port-based I/O, block operations (LDIR, LDDR), alternate registers for fast interrupt handling, and hardware multiply/divide.

The project already includes working tools written in Rust:

sasm - A full assembler
semu - An emulator with TUI debugger (step, breakpoints, memory inspection)

And for hardware implementation, we now have two complete RTL implementations:

Amaranth HDL (/rtl/):

cpu.py, alu.py, decode.py, regfile.py, soc.py
Python-based, excellent for rapid iteration
Generates Verilog for synthesis

AI Assisted Hand-written Verilog (/verilog/rtl/):

cpu.v, alu.v, decode.v, regfile.v, shifter.v, uart.v, ram.v, soc.v
Readable, portable, works with any toolchain
Includes testbenches for Icarus Verilog and Verilator

Now it's time to synthesize it to real hardware.

Choosing an FPGA Platform

The FPGA world is split between proprietary toolchains (Xilinx Vivado, Intel Quartus) and the growing open source ecosystem. For a project like Sampo, where understanding every layer of the stack matters, open source tooling is the clear choice.

Open Source FPGA Options

FPGA Family	Capacity	Toolchain	Maturity
Gowin GW1N/GW2A	1K-55K LUTs	Project Apicula	Good
Lattice iCE40	1K-8K LUTs	Project IceStorm	Excellent
Lattice ECP5	12K-85K LUTs	Project Trellis	Excellent
Xilinx 7-series	10K-200K+ LUTs	Project X-Ray (partial)	Experimental

For Sampo, which estimates at ~1,500-2,500 LUTs for the basic CPU, even the smaller FPGAs have more than enough capacity. But if we want room to grow (adding caches, more peripherals, maybe even multi-core experiments) a larger device makes sense.

The ULX3S Board

The ULX3S is an open hardware development board built around the ECP5 FPGA. It's designed by Radiona.org and has become the de facto standard for open source FPGA development.

Specifications

Component	Specification
FPGA	Lattice ECP5 (LFE5U-85F/45F/12F-6BG381C)
LUTs	12K / 44K / 84K (depending on variant)
USB	FTDI FT231XS (500 kbit JTAG, 3 Mbit serial)
GPIO	56 pins (28 differential pairs), PMOD-compatible
RAM	32 MB SDRAM @ 166 MHz
Flash	4-16 MB Quad-SPI
Storage	microSD slot
LEDs	11 total (8 user, 2 USB, 1 WiFi)
Buttons	7 (4 direction, 2 fire, 1 power)
Audio	3.5mm jack (stereo + digital/composite)
Video	GPDI (HDMI-compatible) with level shifter
Display	Header for 0.96" SPI OLED (SSD1331)
Wireless	ESP32-WROOM-32 (WiFi/Bluetooth, standalone JTAG)
ADC	8 channels, 12-bit, 1 MS/s (MAX11125)
Clock	25 MHz onboard, differential input available
Power	3 switching regulators (1.1V, 2.5V, 3.3V)
Sleep	5 µA standby, RTC wake-up with battery backup
Dimensions	94mm × 51mm

Why ULX3S for Sampo

The ULX3S isn't just an FPGA breakout board; it's a complete system:

32MB SDRAM: Real memory, not just block RAM. Essential for running actual programs.
HDMI output: Video terminal without external hardware.
microSD slot: Load programs, implement a filesystem.
ESP32 co-processor: WiFi-based JTAG debugging from any device.
Buttons and LEDs: Instant I/O for testing without wiring anything.
Audio output: Even supports composite video through the audio jack.

Budget Alternative: Tang Nano 9K

Before we dive into the ULX3S, it's worth mentioning a much cheaper option. The Tang Nano 9K (~$15 on AliExpress) uses a Gowin GW1NR-9 FPGA with 8,640 LUTs, more than enough for Sampo:

8,640 LUTs
64Mbit PSRAM (can serve as the full 64KB address space and then some)
HDMI output for a video terminal
USB-C programming
Fully supported by open-source toolchain (Yosys + nextpnr-gowin)

For initial development and testing, the Tang Nano 9K is hard to beat on price. But the ULX3S offers more I/O, more RAM, and a richer peripheral set, making it the better choice for a more complete Sampo system.

LUT Budget Planning

The Sampo RTL implementation is designed to be compact. Here's the resource breakdown:

Component	Estimated LUTs
16 × 16-bit registers	~256 FFs
ALU (16-bit)	200 - 400
Control logic	500 - 1,000
Instruction decode	300 - 500
Sampo CPU core	~1,500 - 2,500
UART (115200 baud)	200 - 300
SPI controller (SD card)	300 - 500
GPIO controller	200 - 400
Basic system	~2,500 - 4,000
SDRAM controller	500 - 1,000
Instruction cache	1,000 - 2,000
Data cache	1,000 - 2,000
Full system	~6,000 - 10,000

These estimates are based on typical RISC CPU implementations. The actual numbers will depend on optimization choices and synthesis settings.

Variant Recommendations

12K LUTs (ULX3S-12F): Plenty for basic Sampo + peripherals, tight for caches.
45K LUTs (ULX3S-45F): Comfortable. Full CPU with cache, room for experiments.
85K LUTs (ULX3S-85F): Luxurious. Multi-core experiments, extensive peripherals.

Toolchain Setup

The ECP5 toolchain is fully open source:

# macOS (Homebrew)
brew install yosys nextpnr-ecp5 ecpprog fujprog

# Ubuntu/Debian
apt install yosys nextpnr-ecp5 ecpprog

# Amaranth HDL (for our existing RTL)
pip install amaranth amaranth-boards

# Or build FPGA tools from source for latest features
git clone https://github.com/YosysHQ/yosys
git clone https://github.com/YosysHQ/nextpnr
git clone https://github.com/YosysHQ/prjtrellis

Tool Roles

Tool	Purpose
Amaranth	Python-based HDL (generates Verilog)
Yosys	Verilog synthesis (RTL → netlist)
nextpnr-ecp5	Place and route (netlist → bitstream)
Project Trellis	ECP5 bitstream documentation
ecpprog/fujprog	Upload bitstream to board

Amaranth Build Flow

Since Sampo's RTL is written in Amaranth, the build flow starts with Python:

# Generate Verilog from Amaranth
cd rtl/
python -m amaranth generate soc.py > sampo.v

# Then synthesize with standard tools
yosys -p "synth_ecp5 -top sampo_soc -json sampo.json" sampo.v
nextpnr-ecp5 --85k --package CABGA381 \
    --lpf ulx3s.lpf --json sampo.json --textcfg sampo.config
ecppack sampo.config sampo.bit

# Program the board
fujprog sampo.bit

Hand-Written Verilog Implementation

In addition to the Amaranth RTL, we now have a complete ai-assisted hand-written Verilog implementation at /verilog/. While Amaranth can generate Verilog, the auto-generated output isn't particularly readable. The hand-written version is designed for clarity and portability:

verilog/
├── rtl/
│   ├── sampo_pkg.vh   # Opcodes, constants, state definitions
│   ├── alu.v          # 16-bit ALU with all operations
│   ├── shifter.v      # Barrel shifter (1/4/8-bit shifts, rotates)
│   ├── regfile.v      # 16 registers + alternate set (EXX)
│   ├── decode.v       # Instruction decoder
│   ├── cpu.v          # FSM-based CPU core (8 states)
│   ├── ram.v          # 64KB synchronous RAM
│   ├── uart.v         # Simple UART for serial I/O
│   └── soc.v          # Top-level SoC integration
├── tb/
│   ├── alu_tb.v       # ALU unit tests
│   ├── regfile_tb.v   # Register file tests
│   └── sampo_tb.v     # Full system testbench
├── programs/
│   └── hello.hex      # Test program in Verilog hex format
├── Makefile           # Build automation
└── bin2hex.py         # Convert sasm output to Verilog $readmemh format

The Verilog implementation uses an 8-state FSM for the CPU: RESET → FETCH → FETCH_EXT → DECODE → EXECUTE → MEMORY → WRITEBACK → HALTED. This makes timing predictable and debugging straightforward.

Simulation with Icarus Verilog

The Verilog implementation includes a complete Makefile for testing:

cd verilog/

# Run the main simulation (hello world)
make test

# Run ALU unit tests
make test-alu

# Run register file tests
make test-regfile

# Build with Verilator (faster simulation)
make verilate

# View waveforms in GTKWave
make wave

Sample output from make test:

=== Sampo CPU Testbench ===
RAM init file: ../programs/hello.hex

CPU started at PC=0x0100
UART output:
----------------------------------------
Hello, Sampo!
----------------------------------------

Simulation complete:
  Final PC:    0x011E
  Cycles:      847
  UART chars:  14
  Status:      HALTED

The Verilog version is portable to any FPGA toolchain (Xilinx, Intel, Lattice, Gowin) without requiring Amaranth or Python in the build chain.

Implementation Roadmap

With both Amaranth and Verilog implementations complete and tested in simulation, the roadmap is now about bringing them up on hardware.

Phase 1: Core Bring-up ✓ (Complete)

✓ Instruction fetch and decode
✓ ALU operations (all 16 operations)
✓ Barrel shifter (1/4/8-bit shifts, rotates, RCL/RCR)
✓ Register file with alternate set (EXX)
✓ FSM-based CPU core (8 states)
✓ RAM interface (64KB)
✓ UART for serial I/O
✓ SoC integration
✓ Testbenches passing (ALU, regfile, full system)
✓ Hello World runs in simulation

Phase 1.5: FPGA Bring-up (Current)

○ ULX3S pin constraints (.lpf file)
○ Clock setup (PLL from 25MHz)
○ Map UART to FTDI
○ LED heartbeat / debug outputs

Phase 2: Memory System

SDRAM controller for 32MB RAM
Instruction cache (optional but helps timing)
Basic interrupt handling

Phase 3: Peripherals

SPI controller for SD card boot
GPIO controller (buttons, LEDs)
Timer/counter module

Phase 4: Advanced Features

Data cache
MMU for memory protection
HDMI text console (VGA timing → GPDI)
ESP32 WiFi integration for wireless debugging

Recommended Tools & Books

Hardware

Tang Nano 9K FPGA - Budget-friendly FPGA board (~$25 on Amazon, ~$15 on AliExpress)
USB Logic Analyzer - Essential for debugging signals (24MHz, 8 channels)

Books

If you're new to Verilog or FPGA development, these are excellent starting points:

Getting Started with FPGAs by Russell Merrick - Beginner-friendly with Verilog and VHDL examples
Programming FPGAs: Getting Started with Verilog by Simon Monk - Practical hands-on guide
Verilog by Example by Blaine Readler - Concise reference for working engineers

Resources

Sampo on GitHub - Full source including assembler, emulator, and RTL
ULX3S GitHub - Schematics, examples, documentation
Project Trellis - ECP5 bitstream documentation
Amaranth HDL - Python-based hardware description
nextpnr - Place and route tool
Yosys - Verilog synthesis

Where to Buy

ULX3S: - AliExpress - ~$100-150 depending on variant - Mouser - Official distribution - CrowdSupply - Original campaign page

Tang Nano 9K (budget alternative): - Amazon - ~$25, faster shipping - AliExpress - ~$15, slower shipping

Next up: Getting our first instructions executing on real hardware. Both the Amaranth and Verilog implementations are ready and tested; Hello World runs in simulation and the testbenches pass. Now it's a matter of pin constraints, clock domains, and debugging the inevitable timing issues.