mGBA Logo mGBA

mGBA Architecture Overview

This document provides an overview of mGBA's codebase architecture, components, and design principles. Understanding the architecture is essential for contributing to the project or customizing mGBA.

Overview

mGBA is written primarily in C, with some C++ for platform-specific code and Qt-based GUI. The codebase is designed for accuracy, performance, and portability across multiple platforms.

Core Architecture

Modular Design

mGBA uses a modular architecture with separate components:

  • Core: Core emulation engine (CPU, memory, hardware components)
  • Frontend: Platform-specific UI implementations (Qt, SDL, etc.)
  • Backend: Platform-specific backends (OpenGL, Vulkan, Direct3D, Metal)
  • Support: Supporting libraries and utilities

Directory Structure

Key directories in the mGBA source tree:

  • src/: Main source code
  • src/core/: Core emulation engine
  • src/gb/: Game Boy/Game Boy Color emulation
  • src/gba/: Game Boy Advance emulation
  • src/platform/: Platform-specific code
  • src/util/: Utility functions and helpers
  • src/debugger/: Debugger functionality
  • src/feature/: Feature implementations (cheats, scripting, etc.)

Core Components

CPU Emulation

The CPU core implements ARM7TDMI processor emulation:

  • ARM Mode: 32-bit ARM instruction set
  • THUMB Mode: 16-bit THUMB instruction set
  • Cycle Accuracy: Cycle-accurate instruction timing
  • Pipelining: CPU pipeline simulation

Memory Management

Memory system implements complete GBA memory map:

  • Memory Map: Complete 32-bit address space
  • Memory Regions: WRAM, VRAM, ROM, SRAM, I/O registers
  • DMA: Direct Memory Access transfers
  • Cache: CPU cache simulation

Graphics System

Graphics rendering system:

  • PPU (Pixel Processing Unit): Graphics pipeline emulation
  • Rendering Backends: Software, OpenGL, Vulkan, Direct3D, Metal
  • Layers: Background layers and sprite layer
  • Effects: Scaling, rotation, alpha blending

Audio System

Audio processing system:

  • Sound Channels: PCM, PSG channel emulation
  • Mixing: Audio channel mixing
  • Resampling: Sample rate conversion
  • Output: Platform-specific audio output

Frontend Architecture

Qt Frontend

Qt-based GUI frontend for desktop platforms:

  • Cross-platform GUI framework
  • Native look and feel on each platform
  • Rich widget set for configuration and debugging

SDL Frontend

SDL-based frontend for simpler UI or embedded systems:

  • Lighter weight than Qt frontend
  • Used for embedded ports (3DS, Wii U, Vita)
  • Basic windowing and input handling

Backend Architecture

Rendering Backends

Multiple rendering backends for different platforms:

  • Software: CPU-based rendering (always available)
  • OpenGL: Cross-platform hardware acceleration
  • Vulkan: Modern low-level API (Linux/Windows)
  • Direct3D 11: Windows-specific acceleration
  • Metal: macOS/iOS native acceleration

Design Principles

Accuracy First

mGBA prioritizes accuracy over performance:

  • Cycle-accurate emulation as default
  • Hardware-accurate behavior for all components
  • Performance optimizations must not sacrifice accuracy

Portability

Code is written with portability in mind:

  • Platform abstraction layers for OS-specific code
  • Standard C/C++ where possible
  • Conditional compilation for platform-specific features

Modularity

Components are designed to be modular and independent:

  • Clear separation between core and frontend
  • Pluggable backends for rendering and audio
  • Optional features can be enabled or disabled

Key Components

Core Emulator (mCore)

The core emulator class manages emulation state:

  • Initializes and manages all hardware components
  • Handles ROM loading and game state
  • Coordinates CPU, memory, graphics, and audio
  • Manages save states and battery saves

Game Boy Advance (GBA)

GBA-specific emulation:

  • ARM7TDMI CPU core
  • GBA memory map and hardware
  • GBA-specific features (link cable, RTC, etc.)

Game Boy/Game Boy Color (GB/GBC)

Backward compatibility with GB/GBC games:

  • Separate GB/GBC emulation core
  • Automatic detection of GB/GBC games
  • Same features available for GB/GBC games

Platform Ports

mGBA supports multiple platforms through platform-specific ports:

  • Desktop: Windows, macOS, Linux (Qt frontend)
  • Mobile: Android, iOS (native UI)
  • Embedded: 3DS, Wii U, Vita (SDL frontend)

Feature Modules

Optional Features

Features can be enabled or disabled at compile time:

  • Lua Scripting: Lua 5.4 integration
  • Debugger: Debugging tools and memory inspection
  • Cheat Codes: Cheat code support
  • Link Cable: Multiplayer support
Learn More: For detailed information about specific components, see the source code documentation in the repository or check the code comments.

Related Articles

For more information about mGBA development: