Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

Project Tartarus is the effort to port the original DOOM (1993) to the HaDes-V architecture, an educational, modular, pipelined 32-bit RISC-V processor developed at the Embedded Architectures & Systems Group at Graz University of Technology. The project builds upon the base implementation created during the Microcontroller Design lab course.

DOOM is known for its portability, having run on countless platforms, but it still poses significant challenges on a soft-core RISC-V CPU implemented in FPGA logic. The game requires substantial memory (the WAD alone is over 4 MB), sustained graphics throughput, precise input handling, and real-time audio, all while running at a modest 75 MHz clock frequency with no floating-point hardware (relying on 16.16 fixed-point arithmetic).

The base HaDes-V system was designed for the Digilent Basys 3 board (XC7A35T FPGA, 256 KB BRAM, no external memory). To meet DOOM’s requirements, the system was ported to the Nexys 4 DDR (XC7A100T FPGA, 128 MB DDR2 SDRAM) and extended with numerous hardware and software additions.

Hardware Additions

  • Port to the Nexys 4 DDR: board bringup, pin constraints, clock generation, synthesis infrastructure
  • M-Extension: hardware multiplier (3-stage pipelined, DSP-based) and divider (radix-2 non-restoring)
  • SD Card Controller & Bootloader: SPI-based SD card interface, BootROM v2 loading programs from SD
  • BRAM Refactoring & Clock Optimization: improved BRAM model enabling 75 MHz CPU clock
  • DDR2 Memory Subsystem: MIG IP integration, 128-bit Wishbone bridge, memory arbiter
  • Instruction Cache: reduces DRAM read latency for code fetches
  • Data Cache: write-through cache reducing DRAM pressure for data accesses
  • PS/2 Keyboard Controller: PS/2 receiver with hardware FIFO, Wishbone interface
  • VGA Controller Rework: double-buffered framebuffer, DOOM-native resolution and color depth, DMA-style framebuffer writes
  • Audio Subsystem: PWM audio output module with Wishbone control interface
  • Cycle Counter: hardware performance counter for profiling

Software Additions

  • Build System & Toolchain: Makefile refactoring, compiler optimization flags (-O2 (partially), -mstrict-align)
  • Standard Library: DDR2-backed malloc/free/realloc, utility functions
  • Hardware Abstraction Layer: the hades_v_doom.c glue layer connecting DOOM’s backend to custom hardware drivers
  • Audio Implementation: sound queue management, PCM sample feeding to the PWM output
  • WAD Integration: DOOM WAD linked directly into the binary, custom memory-mapped I/O layer replacing file system access
  • Performance Optimizations: optimized column rendering in r_draw.c, fixed-point math fixes, cycle counter-driven profiling

Result

DOOM is running on the Nexys 4 DDR with full graphics and sound (no music). Depending on graphical settings, the game achieves between 10 and 30 FPS.

Document Structure

This documentation is divided into two main parts:

  • Hardware: covers all custom hardware modules, peripheral bringup, and architectural changes
  • Software: covers the build system, DOOM HAL, drivers, and performance optimizations

Each chapter describes the motivation, design decisions, and implementation details of the respective change.

Acknowledgements

The Game Engine Black Book: DOOM by Fabien Sanglard was an invaluable resource for understanding the inner workings of the DOOM engine. Its detailed exploration of the rendering pipeline, WAD format, and game subsystems greatly aided both the porting effort and the writing of this documentation.

Use of Large Language Models

During the development of Project Tartarus, several LLM-based tools were used:

  • GitHub Copilot was occasionally used for single-line code completions during software development, providing suggestions for boilerplate and repetitive code patterns.
  • Gemini (Chat) was used as a sounding board for architectural decisions. Design ideas were discussed in a “tell me why my idea is stupid” style to identify flaws and consider alternatives before implementation. Furthermore, it was used to generate testcases for testbenches without being given prior knowledge of the system, in the hopes of finding edge cases I would be too biased to consider, before running synthesis which takes more than an hour on my machine.
  • DeepSeek V4 Pro and DeepSeek Flash provided the primary assistance with writing this documentation, including chapter planning, content drafting, and diagram creation.