Project 1: Toolchain and ROM Header Verification

Build a DMG ROM that boots and validates its header.

Quick Reference

Attribute	Value
Difficulty	Level 2
Time Estimate	Weekend
Main Programming Language	Game Boy Assembly (SM83/LR35902)
Alternative Programming Languages	C (GBDK-2020), C++ (GBDK-2020)
Coolness Level	Level 4
Business Potential	Level 1
Prerequisites	DMG memory map, VBlank timing, basic assembly concepts
Key Topics	ROM header, boot process, fixed bank layout

1. Learning Objectives

By completing this project, you will:

Build and verify a working toolchain and rom header verification system.
Apply DMG hardware constraints (timing, memory, and I/O rules).
Create repeatable validation steps using emulator tooling.
Document decisions and trade-offs for future projects.

2. All Theory Needed (Per-Concept Breakdown)

ROM Header and Boot Pipeline

Fundamentals A DMG ROM only boots if the cartridge header is correct. The header contains the Nintendo logo bytes, title, cartridge type, ROM/RAM sizes, and checksums. This makes the header more than metadata; it is a hardware gatekeeper. The boot ROM verifies the logo bytes and checksum, then transfers control to the entry point. If any field is wrong, real hardware refuses to run the ROM. Understanding this pipeline teaches you how the DMG transitions from a fixed boot state to your program and why the fixed ROM bank exists. It also teaches disciplined toolchain usage: assemble, link, fix header, validate, and only then test in an emulator or on hardware.

Deep Dive into the concept The DMG boot process is a hardware-driven contract. At power-up, the boot ROM initializes registers, sets basic LCD state, and checks the cartridge header. The logo bytes act as a signature: they must match a specific sequence for the system to proceed. The header checksum ensures the header bytes are internally consistent. Only after these validations does the system jump to the cartridge entry point. From that moment, your ROM is responsible for everything: interrupt vectors, stack setup, and hardware initialization. This means you must be meticulous about ROM layout. A fixed bank at 0000-3FFF must contain interrupt vectors and the entry point. Even if your game uses multiple banks, the boot entry and interrupt handlers must remain reachable from the fixed bank. This is why many DMG projects reserve a small, stable system layer in bank 0 and place variable content elsewhere. A robust build pipeline includes an explicit header verification step, a reproducible ROM size target, and checks to ensure the header fields align with the actual build. For ROM modding, understanding the header is equally critical: modifications must preserve the logo and update checksums, or the patched ROM will fail on hardware. The header is the single most important byte range in the ROM; treat it like a hardware API, not a comment block.

How this fit on projects This concept is central to Toolchain and ROM Header Verification. It informs the build pipeline, timing discipline, and verification steps used throughout the project.

Definitions & key terms

Cartridge header: Metadata block at 0100-014F that the DMG verifies before boot.
Logo bytes: A fixed byte sequence used by the boot ROM to validate the cartridge.
Header checksum: A checksum over header bytes used for integrity verification.
Entry point: The address the DMG jumps to after boot checks pass.

Mental model diagram

Power On -> Boot ROM -> Check Logo/Checksum -> Jump Entry -> Your Code
              | fail?
              v
           Halt/No Boot

How it works (step-by-step)

System powers on and executes boot ROM.
Boot ROM verifies logo bytes and header checksum.
If valid, boot ROM initializes registers and disables itself.
CPU jumps to cartridge entry point in fixed bank 0.
Your code initializes stack, interrupts, and hardware.

Minimal concrete example (pseudocode)

verify_header(rom)
if valid: jump_to_entry()
else: fail_boot()

Common misconceptions

“Emulators ignore headers” -> strict emulators and hardware enforce them.
“The logo is optional” -> the boot ROM requires it.

Check-your-understanding questions

Why does the DMG require a fixed ROM bank?
What fields in the header affect boot behavior?
Predict what happens if the checksum is wrong.

Check-your-understanding answers

The fixed bank ensures vectors and entry point are always visible.
Logo bytes, cartridge type, ROM/RAM size, and checksums are critical.
Hardware halts or refuses to boot the ROM.

Real-world applications

Bootable homebrew ROMs
Reliable ROM patching and validation

Where you’ll apply it You’ll apply it in Section 3.1, Section 4.1, and Section 5.2. Also used in: P18 ROM Patch Pipeline.

References

Pan Docs: The Cartridge Header
RGBDS documentation

Key insights The header is a hardware contract, not metadata.

Summary Correct headers and fixed-bank layout are prerequisites for all DMG software.

Homework/Exercises to practice the concept

List every required header field and its purpose.
Explain why the entry point must be in bank 0.

Solutions to the homework/exercises

Use Pan Docs to verify required fields and ensure checksums match.
Bank 0 is always mapped; other banks are not guaranteed.

3. Project Specification

3.1 What You Will Build

You will build a DMG project component focused on Toolchain and ROM Header Verification. It will be functional, repeatable, and verifiable in strict emulators. It will include clear output signals (visual or logged) and a documented validation process. It will exclude advanced extras beyond scope, such as CGB-only features.

3.2 Functional Requirements

Core functionality: Implement the primary system described in Toolchain and ROM Header Verification.
Deterministic output: Provide a repeatable visible or logged result.
Hardware constraints: Respect VRAM/OAM timing and memory map rules.

3.3 Non-Functional Requirements

Performance: Must stay within a safe per-frame budget.
Reliability: Must behave consistently across two emulators.
Usability: Clear on-screen or logged indicators for success.

3.4 Example Usage / Output

Build:
$ rgbasm -o build/main.o src/main.asm
$ rgblink -o build/game.gb build/main.o
$ rgbfix -v -p 0 build/game.gb

Run:
$ sameboy build/game.gb

Expected:
- No header warnings
- Stable on-screen indicator or log output

Exit Codes:
- 0 = success
- 1 = build failure
- 2 = header validation failure

3.5 Data Formats / Schemas / Protocols

StateRecord (pseudocode shape):

frame_counter: u16
input_mask: u8
flags: u8

AssetIndex (pseudocode shape):

bank_id: u8
offset: u16
length: u16

UpdateQueue item:

target: VRAM/OAM
dest: address
size: bytes

3.6 Edge Cases

VRAM/OAM access outside safe windows
Bank switch not restored
Input sampled multiple times per frame

3.7 Real World Outcome

A stable, reproducible DMG component that can be verified visually or via emulator logs, with no flicker or corruption.

3.7.1 How to Run (Copy/Paste)

$ rgbasm -o build/main.o src/main.asm
$ rgblink -o build/game.gb build/main.o
$ rgbfix -v -p 0 build/game.gb
$ sameboy build/game.gb

Exit Codes:

0 = success
1 = build failure
2 = header validation failure

3.7.2 Golden Path Demo (Deterministic)

Load ROM
Observe the expected on-screen state or log output
Confirm stability for 30 seconds

3.7.3 Failure Demo (Deterministic)

Force a known invalid state (e.g., wrong bank selected)
Observe expected failure behavior (visual corruption or emulator warning)

4. Solution Architecture

4.1 High-Level Design

Input/Timer -> Core Logic -> Render/Sound Updates -> Validation

4.2 Key Components

Component	Responsibility	Key Decisions
Input/Timing	Stable cadence	VBlank-driven loop
Data/Assets	Storage & layout	Fixed bank + banked assets
Renderer	Safe updates	VBlank/STAT windows

4.4 Data Structures (No Full Code)

State: counters, flags, and last-input snapshot
Asset tables: offsets + bank IDs
Update queue: list of VRAM/OAM updates

4.4 Algorithm Overview

Key Algorithm: Frame Update

Wait for VBlank
Read input and update state
Apply safe VRAM/OAM updates
Render or log output

Complexity Analysis:

Time: O(n) over visible entities or updates
Space: O(n) for entity/state tables

5. Implementation Guide

5.1 Development Environment Setup

Install RGBDS
Install DMG-accurate emulator
Set up project folder

5.2 Project Structure

project-root/
|---- src/
|   |---- main.asm
|   |---- hardware.asm
|   `---- assets.asm
|---- build/
|---- tools/
`---- README.md

5.3 The Core Question You’re Answering

“How do I build toolchain and rom header verification that behaves correctly under DMG hardware constraints?”

5.4 Concepts You Must Understand First

Stop and research these before coding:

ROM Header and Boot Pipeline
- What parts are most timing-sensitive?
- Why does DMG hardware enforce this?
- Book Reference: “Game Boy Coding Adventure” - relevant chapters

5.5 Questions to Guide Your Design

Timing and Safety
- Where are the safe update windows?
- How will you ensure you only write during those windows?
Validation
- What will you see or log when it works?
- How will you reproduce the result exactly?

5.6 Thinking Exercise

Draw the Timing Window

Sketch a frame timeline and mark exactly where your updates will occur.

5.7 The Interview Questions They’ll Ask

Prepare to answer these:

“What hardware constraints drive your design?”
“How do you validate correctness on DMG?”
“What makes your updates deterministic?”
“How do you avoid timing glitches?”
“How do you debug errors when you have no OS?”

5.8 Hints in Layers

Hint 1: Start with a stable VBlank loop Build the simplest loop that waits for VBlank and updates a single state.

Hint 2: Add one subsystem at a time Layer in input, rendering, or audio only after the base loop is stable.

Hint 3: Validate with emulator tools Use VRAM/OAM viewers and breakpoints to confirm data correctness.

Hint 4: Stress test timing Intentionally add workload and watch for corruption or flicker.

5.9 Books That Will Help

Topic	Book	Chapter
DMG fundamentals	“Game Boy Coding Adventure”	Ch. 1-5
Low-level systems	“The Art of Assembly Language”	Ch. 1-6

5.10 Implementation Phases

Phase 1: Foundation (2-4 days)

Goals:

Build a bootable ROM and stable loop
Create a minimal visible output

Tasks:

Set up toolchain and build pipeline
Display a simple on-screen indicator

Checkpoint: Emulator shows stable output without warnings

Phase 2: Core Functionality (1 week)

Goals:

Implement the core system for Toolchain and ROM Header Verification
Add validation logs or overlays

Tasks:

Build the main subsystem
Verify correctness with emulator tools

Checkpoint: System behaves correctly for 30 seconds

Phase 3: Polish & Edge Cases (3-5 days)

Goals:

Handle edge cases and timing failures
Document limitations and fixes

Tasks:

Add edge case handling
Stress test and refine

Checkpoint: No flicker/corruption under stress test

5.11 Key Implementation Decisions

Decision	Options	Recommendation	Rationale
Update timing	VBlank only / HBlank	VBlank only	Safest for DMG
Data layout	Dense / Aligned	Aligned	Easier debugging

6. Testing Strategy

6.1 Test Categories

Category	Purpose	Examples
Unit Tests	Validate small routines	Input decoding, counters
Integration Tests	Subsystem behavior	Loop + rendering
Edge Case Tests	Timing stress	Max sprites, heavy updates

6.2 Critical Test Cases

Baseline run: ROM boots and shows stable output.
Stress test: Maximum updates without flicker.
Regression test: Repeat run after changes and compare results.

6.3 Test Data

Input sequence: Up, Up, A, Start
Expected: deterministic state changes and stable display

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

Pitfall	Symptom	Solution
Wrong update timing	Flicker or corruption	Move writes to VBlank
Bank not restored	Random crashes	Save/restore bank state
Incorrect register setup	Blank screen	Verify I/O writes

7.2 Debugging Strategies

Use emulator VRAM/OAM viewers: confirm data and timing.
Log state changes: compare expected vs actual frames.

7.3 Performance Traps

Overloading a frame with too many updates causes missed safe windows. Cap work per frame.

8. Extensions & Challenges

8.1 Beginner Extensions

Add a visual status indicator for success
Add a simple on-screen counter

8.2 Intermediate Extensions

Add a debug toggle for extra metrics
Add a second validation scenario

8.3 Advanced Extensions

Run the ROM on real hardware via flash cart
Add a small automated test harness

9. Real-World Connections

9.1 Industry Applications

Embedded firmware: fixed timing loops and I/O constraints
Retro toolchains: reproducible builds for constrained devices

RGBDS: https://rgbds.gbdev.io/ - DMG assembler/linker
SameBoy: https://sameboy.github.io/ - Accurate DMG emulator

9.3 Interview Relevance

Hardware timing questions
Memory map and register-level reasoning

10. Resources

10.1 Essential Reading

Game Boy Coding Adventure by Maximilien Dagois - DMG fundamentals
The Art of Assembly Language by Randall Hyde - registers and timing

10.2 Video Resources

DMG dev walkthroughs (YouTube) - focus on timing and VRAM rules

10.3 Tools & Documentation

Pan Docs: https://gbdev.io/pandocs/ - hardware reference
RGBDS: https://rgbds.gbdev.io/ - toolchain docs

Previous Project: Toolchain and ROM Header Verification
Next Project: Frame Loop + Input Sampler

11. Self-Assessment Checklist

11.1 Understanding

I can explain the core hardware constraints behind this project
I can describe why the chosen timing model works
I can explain one trade-off I made

11.2 Implementation

All functional requirements are met
All test cases pass in two emulators
The output is stable and deterministic

11.3 Growth

I can explain this project in an interview
I documented what I would do differently next time

12. Submission / Completion Criteria

Minimum Viable Completion:

Core functionality works and is visible
ROM builds without warnings
Behavior is reproducible

Full Completion:

All edge cases handled
Performance budget respected

Excellence (Going Above & Beyond):

Verified on real hardware
Includes automated validation steps

Project 1: Toolchain and ROM Header Verification

Quick Reference

1. Learning Objectives

2. All Theory Needed (Per-Concept Breakdown)

ROM Header and Boot Pipeline

3. Project Specification

3.1 What You Will Build

3.2 Functional Requirements

3.3 Non-Functional Requirements

3.4 Example Usage / Output

3.5 Data Formats / Schemas / Protocols

3.6 Edge Cases

3.7 Real World Outcome

3.7.1 How to Run (Copy/Paste)

3.7.2 Golden Path Demo (Deterministic)

3.7.3 Failure Demo (Deterministic)

4. Solution Architecture

4.1 High-Level Design

4.2 Key Components

4.4 Data Structures (No Full Code)

4.4 Algorithm Overview

5. Implementation Guide

5.1 Development Environment Setup

5.2 Project Structure

5.3 The Core Question You’re Answering

5.4 Concepts You Must Understand First

5.5 Questions to Guide Your Design

5.6 Thinking Exercise

Draw the Timing Window

5.7 The Interview Questions They’ll Ask

5.8 Hints in Layers

5.9 Books That Will Help

5.10 Implementation Phases

Phase 1: Foundation (2-4 days)

Phase 2: Core Functionality (1 week)

Phase 3: Polish & Edge Cases (3-5 days)

5.11 Key Implementation Decisions

6. Testing Strategy

6.1 Test Categories

6.2 Critical Test Cases

6.3 Test Data

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

7.2 Debugging Strategies

7.3 Performance Traps

8. Extensions & Challenges

8.1 Beginner Extensions

8.2 Intermediate Extensions

8.3 Advanced Extensions

9. Real-World Connections

9.1 Industry Applications

9.2 Related Open Source Projects

9.3 Interview Relevance

10. Resources

10.1 Essential Reading

10.2 Video Resources

10.3 Tools & Documentation

10.4 Related Projects in This Series

11. Self-Assessment Checklist

11.1 Understanding

11.2 Implementation

11.3 Growth

12. Submission / Completion Criteria