retro-silicon

A second FPGA family: the PYNQ-Z2

Tue, 27 Oct 2026 00:00:00 +0000

The NES runs on an AMD Zynq-7020, on a TUL PYNQ-Z2, built entirely with the open-source openXC7 toolchain, and every test gives the Tang boards’ CRCs: nestest, the save-state round trip, all 42 PPU test ROMs, and HDMI at 720p, checked by checksum and through the capture device. The parts it shares with the Tang boards now count as Portable: verified on two FPGA families.

Getting there turned up four limits of the toolchain, each worked around in the board’s own files or in a part that now avoids it on every board: clock settings with fractions came out wrong, the ninth bit of a 9-bit-wide block RAM was lost, deep memories built from cascaded block RAM couldn’t be placed, and the timing varied widely from one placement to the next.

The picture on HDMI

Mon, 26 Oct 2026 00:00:00 +0000

The NES’s picture now goes out over HDMI at 720p: three times its size, centred, with the console kept in step with the display so each display frame shows one NES frame whole. On the Tang Nano 20K a checksum of every symbol sent to the display matches the simulation’s, a desk monitor shows the picture, and a USB capture device’s picture of each test’s frame matches the frame the console drew.

First frames: 42 PPU test ROMs match MesenCE

Sun, 25 Oct 2026 00:00:00 +0000

The picture processor, video/ppu-2c02, draws its first frames on the board, and they match the reference emulator exactly. Its timing follows MesenCE’s, so a frame from the core and a frame from MesenCE can be compared as raw palette values, CRC for CRC.

42 test ROMs pass that way, in the simulation and on the Tang Nano 20K: blargg’s VBL and NMI tests, PPU open bus and OAM reads, the sprite hit and overflow tests, VBL/NMI timing, palette RAM, nmi_sync and full_palette. A whole frame captured from the board line by line matches MesenCE’s pixel for pixel. Five bugs planted in the PPU on purpose were each caught by the ROMs.

Save states that move between boards

Sun, 25 Oct 2026 00:00:00 +0000

The NES now runs on a second board, the Sipeed Tang Console 138K, with its memory in block RAM, and every test gives the same CRCs as on the Tang Nano 20K: nestest 0xebba51ce, and all 42 PPU test ROMs with MesenCE’s frames.

A save-state controller stops the system at a frame boundary and copies the CPU, the PPU and every RAM, 20,920 bytes, out through the test shell and back. Saved partway through a test, reset, restored and finished, a run ends with the same frame, line CRCs, bus trace and cycle count as an uninterrupted one. A state saved halfway on either board also finishes on the other with MesenCE’s frames, for nmi_sync, sprite_overflow-3 and ppu_vbl_nmi-10.

nestest on the board

Sat, 24 Oct 2026 00:00:00 +0000

The CPU now runs on real hardware. On the Sipeed Tang Nano 20K, systems/nes reads its program from the board’s SDRAM through the new memory/sdram controller, and nestest’s run gives the bus-trace CRC 0xebba51ce: a checksum of every bus cycle, the same in the simulation, on the board, and from the CPU’s own test bench.

The SDRAM controller worked on the board the first time: 8 MB of random data written and read back with the simulation’s CRC. The simulation had caught two of its bugs first.

The 6502, cycle for cycle

Sat, 24 Oct 2026 00:00:00 +0000

The NES’s CPU core, cpu/6502, matches the original chip on every bus access. In simulation it ran in lockstep with perfect6502, a transistor-level model of the real 6502, over two million cycles of random code with random interrupts, and on 1,500 decimal-mode cases. All 8,991 lines of nestest’s reference log match, cycle counts included, and blargg’s test of every official opcode passes.

The lockstep also turned up three things outside our own code: a memory bug in perfect6502’s newest version, an operation perfect6502 leaves out of three rarely used opcodes, and the exact half-cycle at which the chip samples its interrupt lines.

About

Mon, 01 Jan 0001 00:00:00 +0000

retro-silicon is an open library of FPGA parts for rebuilding retro systems: CPUs, video and sound chips, memory controllers, and the systems built from them. The code is at github.com/particlesector/retro-silicon.

How the cores are verified

A core is only as good as the evidence that it behaves like the original. Each part goes through the same steps.

Simulation first. Every part has tests that run in Verilator, a simulator that turns the hardware description into a fast C++ model. Where there’s a software model to compare against, the tests use it: the 6502 CPU runs in lockstep with perfect6502, a transistor-level simulation of the real chip, for millions of half-cycles.

common/cdc

Mon, 01 Jan 0001 00:00:00 +0000

A flip-flop synchronizer: brings a signal from another clock domain into this one through STAGES flip-flops, so a value that changes near the clock edge settles before anything uses it.

Module cdc_sync. It’s safe only for signals whose bits can be taken in any mix of old and new without harm:

a level;
a toggle, one bit that flips once per event;
a Gray-coded count, which changes one bit per step;
a value the sending side holds steady from before a toggle it sends until after the toggle is seen here.

Ports

Port	Dir	Width	Meaning
`clk`	in	1	This domain’s clock
`d`	in	`W`	From the other domain
`q`	out	`W`	`d`, `STAGES` clocks later

Parameters

Parameter	Default	Meaning
`W`	1	Bits
`STAGES`	2	Flip-flops in the chain, 2 or more

Status

Sim test: the output is the input STAGES clocks later. In video/line-scaler and systems/nes, between the NES’s clock and the HDMI pixel clock, on a Tang Nano 20K.

common/clock-enable

Mon, 01 Jan 0001 00:00:00 +0000

A clock enable at NUM/DEN of the clock rate, exact on average: a phase accumulator gains NUM each enabled clock and fires when it reaches DEN, so pulses come floor(DEN/NUM) or ceil(DEN/NUM) clocks apart and never drift. It’s how a system on one fast clock runs a chip at its original rate: the NES’s PPU dot rate, 236.25/44 MHz, is NUM = 35, DEN = 176 from 27 MHz.

common/crc32

Mon, 01 Jan 0001 00:00:00 +0000

CRC-32 as used by zlib, Ethernet and PNG (IEEE 802.3 polynomial, reflected, initial value and final XOR 0xFFFFFFFF), consuming W bits per enabled clock, bit 0 first: by default one byte. The test shell uses it for frame, scanline and audio CRCs, and the harness’s software rig::Crc32 matches it.

Ports

Port	Dir	Width	Meaning
`clk`	in	1	Clock
`rst`	in	1	Synchronous; restarts the CRC
`en`	in	1	Consume `data` this cycle
`data`	in	`W`	Next byte, or `W` bits
`crc`	out	32	CRC of every byte since reset, final XOR applied
`st_we`, `st_wdata`	in	1, 32	Save state: set the CRC to `st_wdata`, ahead of any byte that clock

Parameters

Parameter	Default	Meaning
`W`	8	Bits per enabled clock, 1 to 32

Save state

One word, the CRC: crc is its read side (it needs no address). Writing a saved CRC back makes the next bytes go on from it exactly as if the bytes before it had gone in. Tie st_we low where nothing restores the CRC.

common/fifo

Mon, 01 Jan 0001 00:00:00 +0000

Synchronous first-in, first-out queue. The read port is registered, so synthesis maps the storage to block RAM: rdata holds a byte the cycle after its read is accepted.

Ports

Port	Dir	Width	Meaning
`clk`, `rst`	in	1	Clock; synchronous reset, which empties the FIFO
`wdata`	in	`WIDTH`	Entry to write
`wen`	in	1	Write `wdata`; ignored when full
`full`	out	1	No room for a write this cycle
`ren`	in	1	Read the oldest entry; ignored when empty
`rdata`	out	`WIDTH`	The entry read on the previous cycle; held otherwise
`empty`	out	1	Nothing to read this cycle

Parameters

Parameter	Default	Meaning
`WIDTH`	8	Bits per entry
`DEPTH_LOG2`	11	log2 of the entry count; 2,048 × 8 bits is one 18 Kbit Gowin BSRAM

Status

Sim tests at 16 and 2,048 entries: it fills to its depth, ignores a write when full and a read when empty, empties on reset, and matches a software queue over 100,000 cycles of random reads and writes. On a Tang Nano 20K, inside systems/uart-echo, it carried 100 MB at 1.5 Mbaud with no errors.

common/por

Mon, 01 Jan 0001 00:00:00 +0000

Power-on reset: holds rst high for CYCLES clocks after the FPGA is configured, then low for good. It’s the one block that relies on a register’s initial value, which FPGAs load at configuration; everything else resets from its rst. It won’t work on an ASIC or an FPGA that ignores initial values; use a reset pin there instead.

common/save-state

Mon, 01 Jan 0001 00:00:00 +0000

Saves a system’s whole state into a block-RAM buffer and loads it back, by walking a list of byte regions on the system’s own bus: the regions where the system maps its components’ save-state ports (docs/conventions.md) and its memories. A save taken on one board loads on any other board running the same system, at any clock.

common/uart

Mon, 01 Jan 0001 00:00:00 +0000

8N1 UART: a receiver (uart_rx) and a transmitter (uart_tx), each set to a rate by CLKS_PER_BIT (clock frequency divided by baud rate).

uart_rx

Synchronises rx through three flops, samples each bit at its middle, and goes back to idle in the middle of the stop bit, so a sender running slightly fast never loses sync. A low pulse shorter than half a bit is ignored as a glitch.

cpu/6502

Mon, 01 Jan 0001 00:00:00 +0000

An NMOS 6502 that is cycle-exact on the bus: one access per CPU cycle, including the original’s dummy reads and writes, so memory-mapped hardware sees what it would on the real chip. The NES’s 2A03 is this CPU with DECIMAL = 0; the Atari 2600’s 6507 and the C64’s 6510 keep decimal mode.

Module cpu_6502 (the folder name can’t start a module name).

debug/test-shell

Mon, 01 Jan 0001 00:00:00 +0000

A UART command engine that gives a host framed, CRC-checked access to a core: it reads and writes the core’s bus, and reports a build ID so every result ties to the exact RTL that produced it. Later blocks (ROM loader, run control, video and audio CRCs, frame dump, trace buffer) are reached through the same commands and bus.

debug/video-probe

Mon, 01 Jan 0001 00:00:00 +0000

Checks and captures a system’s video for the test shell: a CRC-32 of each frame and of each line, and a capture of one chosen line at a time that holds the system until the host has read it. Holding a system’s clock enables leaves its behaviour unchanged, so a frame dumped line by line is exactly the frame it would have shown, at the link’s speed rather than the video’s.

memory/arbiter

Mon, 01 Jan 0001 00:00:00 +0000

Shares one byte-port memory among N clients by fixed priority, client 0 first. A system takes its memory through this, so a board can put any memory behind the one port: memory/sdram on the Tang Nano 20K, memory/bram on the Tang Console 138K.

Module mem_arbiter.

Timing

Ports: the clients’ and the memory’s all work as memory/sdram’s user port: hold req (with addr, we, wdata) until ack, a one-clock pulse that also marks rdata valid on a read. req may still be high while ack is.
Grant: when the memory is free, the first requesting client is granted on the next clock, and its request goes straight to the memory until the memory acks. The ack goes to that client in the same clock.
Latency: a client waits for the rest of any access already running, then for every client before it. Client 0 waits for at most one access, plus the grant clock and its own access; that bound is what lets a CPU fit its reads into a fixed cycle.

Ports

Port	Dir	Width	Meaning
`clk`, `rst`	in	1	Clock; synchronous reset, which drops any grant
`c_req`, `c_we`, `c_ack`	in, in, out	N	Per client
`c_addr`, `c_wdata`	in	N×AW, N×8	Client i in bits `[iAW +: AW]` and `[i8 +: 8]`
`c_rdata`	out	8	Read data, for the client being acked
`m_req`, `m_we`, `m_addr`, `m_wdata`	out	1, 1, AW, 8	To the memory
`m_ack`, `m_rdata`	in	1, 8	From the memory

Parameters

Parameter	Default	Meaning
`N`	2	Clients
`AW`	23	Address bits

Status

Sim test (N = 3) against a memory with a random latency of 1 to 7 clocks, with three clients each keeping requests going in its own part of the address space: 200,000 clocks in which every request is served exactly once, every read gives the byte last written, and client 0 never waits more than two accesses. In systems/nes it serves the CPU’s PRG reads and the shell, on both boards.

memory/bram

Mon, 01 Jan 0001 00:00:00 +0000

2^AW bytes of block RAM behind memory/sdram’s byte port, for a board whose own memory a system can’t use yet, such as the Tang Console 138K’s DDR3. Every access takes one clock. Addresses wrap at 2^AW, so a wider port mirrors it.

Module bram_mem.

Ports

Port	Dir	Width	Meaning
`clk`, `rst`	in	1	Clock; synchronous reset (the contents stay)
`req`, `we`, `addr`, `wdata`	in	1, 1, IW, 8	An access, held until `ack`; `req` may still be high while `ack` is
`ack`, `rdata`	out	1, 8	One-clock pulse a clock after `req`; read data with it
`ready`	out	1	Always high: block RAM needs no power-up sequence

Parameters

Parameter	Default	Meaning
`AW`	18	Bytes: 2^AW (256 KB)
`IW`	23	The port’s address width; bits above AW are ignored

Status

Sim test (AW = 10, IW = 12): 40,000 random reads and writes, through the mirror, against a byte array, each acked in one clock, with req left high during the ack. In systems/nes (nes_bram) it holds PRG ROM on the Tang Console 138K.

memory/sdram

Mon, 01 Jan 0001 00:00:00 +0000

Controller for a 2M × 32 SDR SDRAM (8 MB: 4 banks, 2048 rows, 256 columns), such as the 64 Mbit chip inside the Tang Nano 20K’s GW2AR-18. The user side is a byte port. Each access opens its row and closes it with auto-precharge, so every access takes the same number of clocks except when a refresh gets there first; that fixed bound is what lets a system fit an access into a CPU cycle.

video/hdmi

Mon, 01 Jan 0001 00:00:00 +0000

Video timing and TMDS encoding for an HDMI output in DVI mode: picture and syncs, no data islands yet (audio and InfoFrames come with the APU). Every HDMI sink accepts DVI. Each pixel clock it gives the three 10-bit symbols to send; a board’s serializers send them at ten times the pixel rate, bit 0 first. The defaults are CEA-861’s 1280x720 at 60 Hz, a 74.25 MHz pixel clock.

video/line-scaler

Mon, 01 Jan 0001 00:00:00 +0000

Shows a source’s frames on a display that runs on another clock, scaled up by a whole number, through a ring of 2^LINES_LOG2 source lines in block RAM instead of a frame buffer. It’s how the NES (256x240) reaches 720p: three times its size, 768x720, in the middle of the 1280-pixel line, with 32 lines of block RAM (four of the GW2AR-18’s) rather than a whole frame.

video/ppu-2c02

Mon, 01 Jan 0001 00:00:00 +0000

The NES’s 2C02 picture processing unit (NTSC), dot-exact: 341 dots by 262 lines, with background and sprite rendering, scrolling, the palette, VBL and NMI, sprite 0 hit, and sprite overflow with its hardware bug. Its timing follows the 2C02 as MesenCE models it, so its frames match MesenCE’s pixel for pixel; that is how it’s tested.