drhelius/geartowns/geartowns-debugging

FM Towns Game Debugging with Geartowns

Overview

Debug FM Towns games using the Geartowns emulator as an MCP server. Control execution (pause, step, breakpoints), inspect the Intel 80386 CPU and hardware (CRTC, VRAM layers, sprite engine, YM3438 FM, RF5C68 PCM, 8259A PIC, 8253 PIT, uPD71071 DMA, CD-ROM and floppy controllers, SCSI host interface), 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 Geartowns MCP server is already connected in your current session. In the default mode, call debug_get_status directly. If Geartowns was intentionally started with --mcp-router, call get_tool_info with {"name":"debug_get_status"}, then call execute_tool with {"name":"debug_get_status","arguments":{}}. A valid response from either workflow means the server is active and ready.

Only if neither workflow is available or the call fails, you need to help install and configure the Geartowns MCP server:

Installing Geartowns

Run the bundled install script (macOS/Linux):

bash scripts/install.sh

This installs Geartowns 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/geartowns on macOS.

Connecting as MCP Server

Configure your AI client to run Geartowns as an MCP server via STDIO transport. For Claude Code:

claude mcp add --transport stdio --scope user geartowns -- /path/to/geartowns --mcp-stdio

For Codex:

codex mcp add geartowns -- /path/to/geartowns --mcp-stdio

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

Firmware

The FM Towns needs its firmware (FMT_SYS.ROM and companion files). Set the BIOS directory in the emulator before starting, or call load_bios with the directory path. get_media_info reports whether the firmware is ready.

Hardware Documentation (References)

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

Debugging Workflow

1. Load and Orient

load_bios → load_media → get_media_info → get_i386_status → get_screenshot

Start every session by making sure the firmware is loaded (load_bios with the firmware directory, unless it is already configured), then load the CD image, confirming it loaded correctly with get_media_info, then checking CPU state and taking a screenshot to understand the current game state. Games are CD images (.cue, .chd, .iso, .zip) loaded with load_media. Some titles also need a boot floppy: use insert_floppy with a .d77, .d88, .hdm, .img, .xdf, .mfm, .m3u or .zip image in drive 0 or 1. Titles installed to a hard disk run from a raw image on a SCSI ID: attach_hard_disk (or load_media with .hdd, .h0-.h6, .hdm over 8 MB), which a running machine takes at the next reset. list_recent_media shows recently opened images.

Load symbols with load_symbols (a text file with ADDRESS NAME or NAME = ADDRESS per line) or add individual labels with add_symbol.

2. Pause and Inspect

Always call debug_pause before inspecting state. While paused:

• CPU state: get_i386_status — general registers, EIP, EFLAGS bits, CS:EIP with linear and physical PC, CR0/CR2/CR3, mode (real, protected, vm86), CPL, IOPL, segment descriptor caches, GDTR/IDTR/LDTR/TR, debug registers, and an fpu section (stack, CW, SW, tags, last instruction) when an 80387 is fitted
• Disassembly: get_disassembly with start_address and end_address or count — decodes the current contents of memory; use code_size (auto, 16, 32) to force 16-bit or 32-bit decoding and detailed for control flow, targets, I/O port names and interrupt vector names
• Call stack: get_call_stack — calls, interrupts and exceptions with their vectors
• Memory: read_memory with a memory area ID (use list_memory_areas to discover available areas and their IDs)
• Debugger state: debug_get_status — paused state, what stopped execution, linear and logical PC, CPU mode, halted

Addresses

Every tool that takes an Intel 80386 address accepts:

• 1234ABCD, 0x1234ABCD or $1234ABCD — a linear address
• CS:1234 — a segment register (CS, DS, ES, FS, GS, SS) and an offset, using its cached base
• 0008:00001234 — a selector in protected mode (read from the GDT or LDT) or a segment in real and VM86 mode, and an offset

Use translate_address to walk an address through segmentation and paging (PDE, PTE, page flags, physical address, region) or to find out why it fails. get_page_directory lists the present page tables. get_i386_descriptors decodes GDT, LDT and IDT entries (in real mode the IDT is the interrupt vector table).

3. Set Breakpoints

Use breakpoints to stop execution at points of interest:

Breakpoints support three address spaces (space): linear (default), physical and io. Execute breakpoints are linear or physical. enabled: false adds or keeps a breakpoint disabled. Interrupt breakpoints by vector take a source (any, exception, hardware, software) and stop before the handler's first instruction.

Important: Read, write and access breakpoints stop after the instruction that made the memory access, so the PC is at the following instruction. Execute breakpoints stop before the instruction runs. debug_get_status reports in breakpoint what stopped execution (kind, space, address, size, or the vector and source of an interrupt).

Manage breakpoints with list_breakpoints (address, interrupt and IRQ breakpoints), remove_breakpoint and clear_breakpoint_on_interrupt (by vector and source, or by irq).

4. Step Through Code

After hitting a breakpoint or pausing:

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

5. Trace Execution

The trace logger records executed instructions (CS:EIP, linear address, mode, bytes, Intel syntax) interleaved with hardware events (IRQ requests, interrupt entries, I/O port accesses, DMA, CD-ROM and floppy controller commands, SCSI commands and phases, VSYNC).

1. set_trace_log with enabled: true to start recording (optionally set filters and output)
2. Let the game run or step through code (the trace records while the debugger runs the machine)
3. set_trace_log with enabled: false to stop (entries are preserved)
4. get_trace_log to read recorded entries (start negative reads the last N lines, count up to 1000)

Trace filters are event streams such as cpu.instructions, cpu.irqs, io.writes, video.vsync or cdrom.commands, or a whole group: cpu, io, pic, timer, dma, video, sprite, fm, pcm, mixer, cdrom, fdc, scsi, keyboard, input, system (the tool schema lists every stream). Instruction lines carry the general and segment registers and EFLAGS. output: "disk" also streams the trace to a text file (output_path, disk_size) for long captures; memory_size sets how many entries are kept in memory.

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

6. Profile

set_profiler (start, stop, reset) collects calls and CPU cycles per function and interrupt vector while the debugger runs the machine. get_profiler_data returns the results (sort: inclusive, exclusive, calls, average, max; count; filter). Use it to find the hot routines of a game before stepping through them.

Hardware Inspection

CPU (Intel 80386)

• get_i386_status — full CPU state: registers, EFLAGS, CR0/CR2/CR3, mode, CPL, IOPL, descriptor caches, GDTR/IDTR/LDTR/TR, debug and test registers, and the 80387 when fitted
• write_i386_register — modify a register live (EAX-EDI, EIP, EFLAGS, CR0, CR2, CR3, DR0-DR7, CS-GS). Segment writes reload base and limit in real and VM86 mode and load the descriptor in protected mode
• get_i386_descriptors — decode gdt, ldt or idt entries (table, start, count)
• get_page_directory — present page-directory entries, or with index the present pages of that page table

Interrupt Controllers, Timers, DMA and Clock