Doom on MicroBlaze

A bare-metal Doom port running on a MicroBlaze soft processor (synthesized on an AMD Artix-7 FPGA) with custom VHDL hardware accelerators. The system runs Doom at 320x240 resolution with hardware upscaling to 640x480 VGA output on the Digilent Arty A7 board.

See demo images here.

Hardware platform

Board Configuration

• Board: Digilent Arty A7-35T
• FPGA: AMD/Xilinx Artix-7
• External Memory: 256 MB DDR3 SDRAM
• Display: VGA (via Pmod VGA adapter)
• Debug Interface: UART

FPGA Design Components

View block diagram (needs to be opened as raw PDF file in order to be able to zoom)

MicroBlaze Processor

• AMD/Xilinx soft processor core synthesized on Artix-7 FPGA
• Running at ~100 MHz
• Configured for standalone (bare-metal) operation

Custom VHDL components

Hardware-Accelerated VGA Controller (vga_controller3.vhd)

• Custom VHDL implementation with AXI-Stream input
• Hardware FIFO for clock domain crossing between memory and VGA timing
• Palette decoding in hardware:
  • Software renders frames with palette encoding where each frame begins with palette definition followed by indexed pixel data
  • Hardware decoder converts palette indices to RGB values on-the-fly
• Hardware upscaling: 320x240 → 640x480 (2x bilinear scaling)
• VGA output at 640x480 @ 60Hz

HMI Controller (hmi_controller.vhd)

• Custom VHDL module for board interface
• Exports Arty A7 button states as memory-mapped registers
• AXI-Lite interface for processor access
• Controls board LEDs for status indication

AMD/Xilinx DMA IP Components

Video DMA (VDMA)

• AMD/Xilinx AXI VDMA IP core
• Continuously reads from dedicated video frame buffer in DDR memory
• Streams pixel data to VGA controller via AXI-Stream
• Enables smooth frame updates without CPU intervention

Central DMA (CDMA)

• AMD/Xilinx AXI CDMA IP core
• Hardware-accelerated memory-to-memory transfers
• Used for fast frame buffer operations

Software Architecture

Doom Port Implementation

• Based on doomgeneric by ozkl
• Ported to MicroBlaze standalone environment (no operating system)
• Includes Doom v1.9 shareware IWAD

System Software Components

Minimal C Library

Custom implementations of required syscalls (e.g., open(), close(), read(), write(), lseek(), fd_lookup(), etc). See syscalls.c for implementation details.

Virtual Filesystem

• Minimal VFS implementation which enables Doom to access WAD files, saved games, and configuration
• Operates entirely in-memory

Drivers

• HMI Driver: Button/switch input reading and LED control
• VDMA Driver: Frame buffer management (AMD/Xilinx provided)
• CDMA Driver: Memory transfer operations (AMD/Xilinx provided)
• Timer Driver: Game timing and frame rate control (AMD/Xilinx provided)
• UART Driver: Debug output and logging (AMD/Xilinx provided)

Prerequisites

• AMD/Xilinx Vivado 2024.1 or later
• AMD/Xilinx Vitis 2024.1 or later
• Digilent Arty A7 board files installed in Vivado

Controls

• BTN0: Move forward
• BTN1: Move backward
• BTN2: Turn left
• BTN3: Turn right
• SW0: Fire

License

Please see LICENSE.md for license information.

Project Status

Note: This is an educational/experimental project demonstrating FPGA SoC design and bare-metal embedded programming. The project is a work-in-progress, not actively maintained, and runs at low frame rates (3-4 FPS; although it could be optimized further in theory). It serves primarily as a learning resource for hardware/software co-design on FPGAs.

Resources & References

• Arty A7 Reference Manual
• MicroBlaze Processor Reference Guide
• MicroBlaze with DDR3 RAM on Arty A7 Tutorial
• doomgeneric - Multi-platform Doom port framework

---

Built with AMD/Xilinx Vivado/Vitis 2024.1