Atari Lynx Game Debugging with Gearlynx

Overview

Debug Atari Lynx games using the Gearlynx emulator as an MCP server. Control execution (pause, step, breakpoints), inspect the 6502 CPU and hardware (Mikey, Suzy), read/write memory, disassemble code, trace instructions, and capture screenshots — all through MCP tool calls. Hardware documentation is available in the references/ directory.

MCP Server Prerequisite

IMPORTANT — Check before installing: Before attempting any installation or configuration, you MUST first verify if the Gearlynx MCP server is already connected in your current session. Call debug_get_status — if it returns a valid response, the server is active and ready.

Only if the tool is not available or the call fails, you need to help install and configure the Gearlynx MCP server:

Installing Gearlynx

Run the bundled install script (macOS/Linux):

bash scripts/install.sh

This installs Gearlynx via Homebrew on macOS or downloads the latest release on Linux. It prints the binary path on completion. You can also set INSTALL_DIR to control where the binary goes (default: ~/.local/bin).

Alternatively, download from GitHub Releases or install with brew install --cask drhelius/geardome/gearlynx on macOS.

Connecting as MCP Server

Configure your AI client to run Gearlynx as an MCP server via STDIO transport. Example for Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "gearlynx": {
      "command": "/path/to/gearlynx",
      "args": ["--mcp-stdio"]
    }
  }
}

Replace /path/to/gearlynx with the actual binary path from the install script. Add --headless before --mcp-stdio on headless machines.

Hardware Documentation (References)

Atari Lynx hardware documentation is available in the references/ directory. Load them into your context when investigating specific hardware.

Debugging Workflow

1. Load and Orient

load_media → get_media_info → get_6502_status → get_screenshot

Start every session by loading the ROM, confirming it loaded correctly, then checking CPU state and taking a screenshot to understand the current game state. If a .sym, .elf, .lbl, or .noi file exists alongside the ROM, symbols are loaded automatically.

Load additional symbols with load_symbols or add individual labels with add_symbol.

2. Pause and Inspect

Always call debug_pause before inspecting state. While paused:

• CPU state: get_6502_status — registers A, X, Y, S, P (flags), PC, interrupt status, MAPCTL visibility
• Disassembly: get_disassembly with a start/end address range — only shows executed code paths
• Call stack: get_call_stack — current subroutine hierarchy
• Memory: read_memory with area name (RAM, Zero Page, Stack, Bank 0, Bank 0A, Bank 1, Bank 1A, BIOS, EEPROM) and address/length

3. Set Breakpoints

Use breakpoints to stop execution at points of interest:

Important: Read/write breakpoints stop with PC at the instruction after the memory access.

Manage breakpoints with list_breakpoints, remove_breakpoint, list_breakpoints_on_irq, clear_breakpoint_on_irq.

4. Step Through Code

After hitting a breakpoint or pausing:

After each step, call get_6502_status and get_disassembly to see where you are.

5. Trace Execution

The trace logger records CPU instructions interleaved with hardware events (Suzy math/sprites, Mikey timers/audio/UART, cartridge access).

1. set_trace_log with enabled: true to start recording (optionally filter event types)
2. Let the game run or step through code
3. set_trace_log with enabled: false to stop (entries are preserved)
4. get_trace_log to read recorded entries

Tracing is essential for understanding timing-sensitive code, interrupt handlers, and hardware interaction sequences.

Hardware Inspection

Mikey (Display, Timers, Audio)

• get_mikey_registers — all registers at $FD00-$FDFF, or filter by address
• get_mikey_timers — Timer 0-7 status (HBLANK, VBLANK, UART, sample rate, etc.)
• get_mikey_audio — audio channel 0-3 status (volume, feedback, output, etc.)
• get_lcd_status — LCD pixel/DMA info (only on visible lines)
• write_mikey_register — modify a Mikey register live

Suzy (Sprites, Math)

• get_suzy_registers — all registers at $FC00-$FCFF, or filter by address
• write_suzy_register — modify a Suzy register live

Other Hardware

• get_uart_status — ComLynx serial port state
• get_cart_status — cartridge address generation, bank info, AUDIN
• get_eeprom_status — EEPROM type, size, mode, state, IO pins

Frame Buffers and Screenshots

• get_screenshot — current rendered frame as PNG
• get_frame_buffer — raw debug frame buffer (VIDBAS from Suzy or DISPADR from Mikey)

Use screenshots after stepping or continuing to see the visual impact of changes.

Common Debugging Scenarios

Finding an Interrupt Handler

1. set_breakpoint_on_irq for the target IRQ (e.g., Timer0 for HBLANK, Timer2 for VBLANK)
2. debug_continue to run until the IRQ fires
3. get_6502_status + get_disassembly to see the handler code
4. get_call_stack to see how deep you are
5. add_symbol to label the handler address and any subroutines it calls

Diagnosing Graphics Corruption

1. debug_pause → get_suzy_registers — check VIDBAS, COLLBAS, sprite control
2. get_frame_buffer — capture both Suzy and Mikey buffers
3. get_mikey_registers — check DISPADR, display DMA settings
4. get_lcd_status — verify line-by-line rendering state
5. Set read/write breakpoints on display buffer addresses to catch corruption source

Analyzing a Subroutine

1. set_breakpoint at the subroutine entry point
2. debug_continue → when hit, get_6502_status
3. Step through with debug_step_into / debug_step_over
4. After each step: check registers, read relevant memory
5. add_symbol for the routine and any called subroutines
6. add_disassembler_bookmark to mark interesting locations

Tracking a Variable

1. add_memory_watch on the variable's address — watches are visible in the emulator GUI
2. Set a write breakpoint with set_breakpoint (type: write) on that address
3. When hit, get_disassembly reveals what code is modifying it
4. get_call_stack shows the call chain leading to the write

Timing Analysis

1. set_breakpoint_on_irq for Timer interrupts
2. set_trace_log with enabled: true to start recording
3. get_trace_log to see the interleaved CPU + hardware events
4. Analyze timer reload values via get_mikey_timers
5. Correlate timer fires with code execution in the trace

Debug Output for Homebrew Development

Homebrew games can send debug text to the Trace Logger via unused Mikey registers $FDC0–$FDC4 — a printf-style mechanism without breakpoints.

1. set_trace_log with enabled: true and debug_output: true
2. Run your game — text written through the registers appears in get_trace_log

ca65 example:

; Print string + hex value in a single trace entry
; A/X = string pointer, Y = hex value
.proc debug_print
    sta $FDC3       ; pointer low
    stx $FDC4       ; pointer high (triggers copy)
    sty $FDC2       ; append Y as hex
    lda #1
    sta $FDC0       ; flush
    rts
.endproc

    lda #<message
    ldx #>message
    ldy player_hp
    jsr debug_print

message: .asciiz "Player HP: "

When disabled (the default), these registers are no-ops — safe to leave in shipping code.

Organizing Your Debug Session

• Symbols: Use add_symbol liberally to label addresses you've identified — makes disassembly readable
• Bookmarks: Use add_disassembler_bookmark for code locations and add_memory_bookmark for data regions
• Watches: Use add_memory_watch for variables you're tracking across steps
• Save states: Use save_state / load_state to snapshot and restore emulator state at interesting points
• Rewind: Use get_rewind_status + rewind_seek to scrub back through recent execution history without manual save states
• Screenshots: Capture visual state with get_screenshot after significant changes

Rewind (Time Travel Debugging)

The emulator continuously records snapshots into a ring buffer during gameplay. You can seek to any recorded snapshot to restore full emulator state at that point in time — like time travel debugging.

Workflow

1. Check availability: get_rewind_status — returns snapshot count, capacity, buffered seconds
2. Pause: debug_pause — the emulator must be paused before seeking
3. Seek: rewind_seek with a snapshot number (1 = oldest, snapshot_count = newest)
4. Inspect: get_6502_status, get_disassembly, get_screenshot, read_memory, etc.
5. Iterate: Seek to different snapshots to narrow down when a bug first appeared
6. Resume or continue debugging: debug_continue to resume from the seeked state

Tools

Key Details

• Non-destructive seeking: rewind_seek loads a snapshot without removing it. You can seek to the same snapshot multiple times, or jump between different snapshots freely.
• Snapshot numbering: Snapshot 1 is the oldest available, snapshot_count is the newest (most recent).
• Buffer size: Configured by the user (default: 10 seconds). When full, oldest snapshots are overwritten.
• Granularity: Snapshots are taken every N frames (configurable). Default is every frame for maximum precision.

Bug Reproduction with Rewind

1. Let the game run past the bug occurrence
2. debug_pause → get_rewind_status to see how far back you can go
3. Binary search with rewind_seek: try the midpoint, check if the bug is visible (get_screenshot), then narrow the range
4. Once you find the exact snapshot where the bug appears, inspect CPU/memory state
5. Set breakpoints at the relevant code, then rewind_seek to a snapshot just before the bug and debug_continue