Copperline 0.19.0

Copperline 0.19.0 is the developer release. An Amiga program can now be debugged at source level from Visual Studio Code -- breakpoints, stepping, Step Back, variables, custom-chip registers and source-mapped CPU profiles -- through a new Debug Adapter Protocol server, and Bartman's Amiga C/C++ extension runs on Copperline with its visual CPU/DMA, Copper, bitmap and blitter profiler fed by the emulator's own per-colour-clock bus captures. Around that: an MCP server so AI coding agents can drive a live machine, a WinUAE-compatible uaelib trap with KPrintF and on-screen debug overlays, an HRTMon freezer cartridge, CPU chip-bus wait attribution and live Kickstart symbols in the Frame Analyzer, warp boot, and WinUAE save-state import. Away from the debugger: open-source replacements for the CD32 FMV cartridge ROM (with a Video CD player) and the A2091/A590 boot ROM, Simon Dick's emulator-native copperhf.device hard-disk controller, uncapped integer scaling with per-axis pixel-aspect fitting and display-window autocrop, --run on a bare Kickstart 1.3, and a bundled AROS ROM refresh. As always it is a hardware-behavior release: the Paula floppy, Akiko CD, Agnus display-fetch and 68030/68040 timing fixes below model the underlying subsystems rather than individual titles.

Compatibility notes

Save states from 0.18.0 do not load in 0.19.0. The uaelib trap, the freezer cartridge, the copperhf board, the Akiko command buffer and the floppy read-shifter framing all changed the serialized machine shape, so the state format version moves from 70 to 79. Re-create snapshots after upgrading. Saves are now written atomically (a temp file renamed over the old one, so a failed save never destroys the previous snapshot) and expansion boards carry permanent wire IDs, so a state written by one feature build is no longer misread by another.

Your host data has moved to Documents, and nothing migrates it for you. Configs, the launcher's saved default, save states, screenshots, recordings, NVRAM, traces, gamepad calibrations, keymaps and the WHDLoad library and saves now live in ~/Documents/Copperline/ on macOS and Linux and %USERPROFILE%\Documents\Copperline\ on Windows, instead of the hidden ~/.config/copperline/ / %APPDATA%\copperline\ tree. Move or copy the old directory to the new location once; otherwise Copperline starts at factory settings with empty save slots and no WHDLoad library. Portable installs (portable.txt) and publisher-kit players are unaffected.

The CD32 profile now fits an FMV cartridge by default. A CD32 configuration that names no fmv_rom boots with the bundled open-source FMV ROM as its first Zorro II board, so the guest sees cd32mpeg.device and, under Kickstart, a Video CD player. fmv_rom = "" (or the launcher's Remove button on the FMV module ROM row) gives a stock CD32; an explicit path to Commodore's v40.30 image still wins.

The A2091/A590 no longer needs a dumped ROM. [scsi] controller = "a2091" with no rom used to be a configuration error; it now loads the bundled open-source A2091 boot ROM. A real image named in rom (or rom plus rom_odd) is used exactly as before.

The uaelib trap is on. Every non-CDTV machine has a 32-byte readable stub at $F0FF60, and a guest warpmode(1) genuinely unpaces a windowed session until warpmode(0), the warp hotkey or power off. [emulation] uaelib = false leaves $F0FF60 unmapped.

Emulated 68030 and 68040 speed changed. m68k 0.12.1 runs the 68030 on the MC68020UM tables and gives the 68040 a single-issue pipeline model, both calibrated against a real A4000 (see below). 68000/010/020/060 timing is unchanged. Separately, the 68000 interrupt-recognition pipe now keeps one deadline per source and bounds an idle STOP nap by a latched interrupt, so handlers that used to be entered a nap late now enter on time; that moves the emulated timeline of any run that depended on the old behavior.

No configuration keys were removed or renamed. Everything else is additive: [emulation] auto_launch, warp_boot, warp_boot_idle, warp_until, uaelib, uaelib_files; [cartridge] model and rom; [copperhf] unit0..unit6; [display] autocrop; and the flags --warp-boot, --warp-until, --cartridge, --freeze-after, --gdb-gui, --gdb-dialect, --load-uss, --video, --run-stack and --run-detach. --run under --control/--control-gui now stops once with reason loadseg when the program loads, as --gdb already did; scripts that expect to run straight through need one more continue.

Highlights

• Source-level debugging in VS Code. copperline-ctl --dap is a Debug Adapter Protocol server built on the control protocol, and tools/vscode-copperline packages it as a VS Code extension (debug type copperline). A launch.json names the Amiga executable and the machine (model, chip, slow, rom, factory...); F5 boots the bundled AROS ROM or a Kickstart from 1.3 up, warp-boots to the program and stops at main. From there: source, function, instruction, data and exception breakpoints with machine-evaluated conditions (d0 == 5, [$DFF006] != 0); Step Over/Into/Out at statement or instruction granularity; Step Back and Reverse Continue from the snapshot ring; Registers (FPU included), Locals, Globals and a Chipset scope with every custom register; hovers and watch expressions; Memory and Disassembly views with per-instruction cycle counts and live ROM names such as [exec] AllocMem+$12; a Debug Console that carries KPrintF and serial output and accepts raw !method {json} control-protocol calls. The toolbar opens Copperline's native Debugger, Console and Frame Analyzer windows, a Custom Registers tree documents every register's bits and access rules, and Profile captures one or more frames as a source-mapped .cpuprofile with a [Bus wait] child separating chip-DMA contention from CPU work. Debug information comes from vasm LINE hunks, amiga-gcc 6.5's DWARF hunk, or an ELF sibling from Bartman's m68k-amiga-elf-gcc (DWARF 4/5, including relocatable -r multi-file builds, whose debug-section relocations the reader applies itself). nvim-dap and any other DAP client work the same way over stdio or --dap-listen. Command palette extras: Init Amiga Project (vasm, amiga-gcc, vbcc or Bartman toolchains), Convert EXE to ADF and Profile File Size. See docs/debugger/vscode.md and docs/debugger/dap.md.
• Bartman's Amiga C/C++ extension runs on Copperline. A public fork of the extension (LinuxJedi/vscode-amiga-debug, branch copperline-backend; upstream PR 307) adds amiga.emulator = "copperline". Copperline supplies the other half: --gdb-gui attaches the GDB stub to the interactive window, --gdb-dialect bartman speaks the patched GDB's wire contract (qOffsets per hunk, the $FFFFFFFF return-from-ROM breakpoint, monitor reset, DBG: output), monitor profile writes the extension's binary profile format from the precise sampler and full bus trace, and a windowed launch waits paused until GDB connects so the guest cannot outrun its debugger. The result is Bartman's visual profiler on a cycle-driven machine: the CPU call-stack and DMA/blitter timeline, the displayed bitmap inferred from the recorded Copper writes (or a bitmap the guest registered by name), the Copper list, blitter A/B/C/D channel previews per blit, and the per-function profiler tree. Six real captures are in docs/debugger/vscode-bartman.md, with a pinned, reproducible install of the fork.
• Profiling and chip-bus tracing. profile.start/profile.stop/profile.status stream one JSON record per committed frame: chip-bus ownership per Agnus owner, blit records, the guest's idle clocks, optionally the per-colour-clock owner grid in vAmiga's DMA-debugger letter code and a screenshot per frame. "samples": true records every retired instruction with its PC, colour-clock cost and optional registers, plus live call stacks from a client-supplied unwind table; copperline-ctl profile-report converts a capture to a Chrome .cpuprofile or Bartman annotations. frame.slots and the bus event family expose a full 24-byte record per raster colour clock (register, DMA kind and subtype, size, IPL, CIA E-clock phase, address, data, and a hardware-event mask: blitter start/finish, Copper WAIT wake, DDF strobes, VB/VS/LOF, CIA IRQ pins, STOP entry and wake). The Frame Analyzer's Beam tab gains a CPU wait view (W) that attributes every colour clock the 68000 lost to the DMA class that held the bus, with a per-line stall gutter and the top stalled PCs; CPUWAIT prints the same in the console. blit.render reconstructs any channel of any blit from the captured DMA words, the new Blits tab shows sources and result side by side, Copper MOVE slots are drawn on the beam, and capture.screenshot can overlay blit destinations, chip-RAM overdraw heat or Denise pixel provenance. copperline-ctl profile profiles a saved .clstate or WinUAE .uss offline.
• Live Kickstart symbols. ROM addresses in call stacks, disassembly, stalled-PC lists and profiles are resolved from the running guest -- Exec's library and device lists, their LVO jump tables and the resident list -- against a table of public AmigaOS LVO names, so names follow SetFunction() patches and work on any Kickstart or AROS revision without a per-ROM address database (WHO ADDR, symbols.resolve, symbols.rom).
• A WinUAE-compatible uaelib trap. $F0FF60 answers the calls Bartman's template makes: warpmode() unpaces the window, KPrintF lands on stdout and in the debugger console as DBG: lines, debug_register_bitmap/_palette/_copperlist feed a new Frame Analyzer Resources tab (decoded bitmap previews, palette swatches, disassembled Copper lists, heat-map presets per resource, PNG export) and the debug control-protocol events, debug_start_idle/stop_idle account the guest's idle time per frame, and the overlay commands (debug_rect, debug_text...) are drawn on the windowed presentation without ever reaching screenshots or captures. debug_load/debug_save are available behind [emulation] uaelib_files, sandboxed below the program's directory. The trap is 32 bytes of real 68k code decoded on the bus; there is no A-line or TRAP hook.
• An MCP server. copperline-ctl --mcp exposes every control-protocol method as an MCP tool (95 tools, one per method with dots mapped to underscores) plus session_launch, session_attach, events_next and friends, so Claude Code, Cursor or any MCP client can boot a machine, set breakpoints, step, read memory and receive screenshots as image blocks. claude mcp add copperline -- copperline-ctl --mcp is the whole setup.
• HRTMon freezer cartridge. [cartridge] model = "hrtmon" (or --cartridge hrtmon) fits an Action Replay-style cartridge with HRTMon 2.39 built reproducibly from the upstream GPL source: a 1 MiB bank at $A10000, a configuration block written from the fitted boards at reset, a shadow of every custom and CIA register copied into the bank on a freeze, and the freeze itself as a level-7 NMI through the current VBR that the 68000 takes at the next instruction boundary whatever the SR mask. Tools > Freeze or Cmd/Alt+Shift+B in the window, --freeze-after SECS headless, cartridge.freeze over the protocol; x in the monitor returns to the interrupted program.
• Warp boot and auto-launch. --warp-boot runs any configuration unpaced from power-on until its floppy and hard-disk activity has been idle for warp_boot_idle seconds (10 by default; CD audio deliberately does not count), then re-paces with audio; --warp-until SECS warps to an absolute emulated time. Both have launcher rows, and Lee Hobson's [emulation] auto_launch makes a saved default boot straight past the launcher screen, so a double-click lands on a settled Workbench.
• Open ROM replacements. The CD32 FMV cartridge now works without Commodore's image: a clean-room GPL ROM (fmv-rom/) installs cd32mpeg.device, whose worker reads Mode-2 sectors through the host cd.device and feeds the CL450 and L64111 ports (no proprietary microcode is copied), plus a videocd.library and version-41 cdstrap that cold-boot a White Book Video CD into a track player under Kickstart; under AROS the matching driver merged upstream in AROS PR 1089. Cannon Fodder's filmed intro plays on both paths. The A2091/A590 gets a clean-room 64 KiB autoboot ROM (a2091-rom/): scsi.device 42.40 derived from the A4091 software, an RDB automounter with Kickstart 1.3 support, a WD33C93 transport that uses the DMAC for even-aligned chip-side buffers and a chip-RAM bounce buffer otherwise, and a build that also emits split U13/U12 EPROM halves for a real board.
• copperhf.device. Copperline's own zero-cost hard-disk controller, the analogue of uaehf.device: a Zorro II board with a doorbell/completion-queue register block, an autoboot ROM with an RDB mounter that autoboots on Kickstart 1.3 as well as 2.0+ and AROS, the full trackdisk family (TD64, NSD, HD_SCSICMD with autosense, disk-change interrupts and TD_EJECT), and a completion time that is a pure function of emulated time so host disk speed never reaches the guest. [copperhf] unit0..unit6 take RDB hardfiles, bare images, .hdz and host directories; copperhf.attach/copperhf.eject swap them live; the launcher's Storage page gains a Copperline HD sub-page; and copperline-import-uae now maps WinUAE uaeN drives onto it. Contributed by Simon Dick.
• Display scaling and autocrop. A new WGSL scaler pass replaces the pixels crate's built-in draw, so integer scaling is no longer capped at 4x on a 5K or 6K display. Under the default tv pixel aspect, integer scaling now presents the unresampled square canvas with a separate whole-number factor per axis chosen to approximate the glass's pixel shape (a 200-line NTSC game with autocrop on a 1080p display is drawn at 2x5). [display] autocrop crops the presentation to the display window the hardware actually programs -- the renderer's own per-line DIW bounds over rows carrying fetched bitplane data, with a latch that adopts growth immediately and shrinks only after half a second of stability -- and works for programmable DblPAL/Multiscan/31 kHz scans too. Captures keep their aperture. The browser demo at copperline.dev/try gains the same Scaling and Autocrop controls.
• WinUAE save-state import. --load-uss reads a WinUAE .uss AmigaStateFile, derives the machine from its chunks, verifies the ROM by CRC and restores CPU, custom, Copper, bitplane, blitter, CIA, palette, sprite and audio state. It is an approximate interchange for resident code, not cycle-exact resumption; docs/guide/winuae-state.md has the coverage table.
• --run on a bare Kickstart 1.3. The staged boot volume now carries small GPL 68000 FailAt, CD, Stack, Echo and Execute commands, so a direct executable launch reaches LoadSeg on a 1.3 ROM with no Workbench files (detached launches still need 2.0+ or AROS). --run-stack, --run-detach and --video PAL|NTSC join the launch flags.
• Smaller things. Every custom-chip register now has a documentation page under docs/reference/custom-registers/ -- bit fields, access side effects, AGA readback, Copperline's own limits -- compiled at build time into the IO Map, the console's CUSTOM REG, custom.dump, the DAP Chipset scope and the VS Code register tree; --gdb-gui and --control-gui can share one window, with warp holds released per client; regs.get reports FPU registers, run_until takes a pc_outside window, watchpoints can be read or read/write, and the GDB stub gains Z3/Z4; the About panel thanks patron Sphair.

Hardware accuracy fixes

• Every drive's motor latch clocks on its own /SEL edge. DF0 was modelled level-sensitive, so a loader that restored a stale CIA-B PRB shadow with MTR high while still selected stopped the motor it had just started; DF0's /RDY now also mirrors /TRK0 while its motor is off. Alongside it: the 68000 IPL recognition pipe keeps one deadline per interrupt source and bounds an idle STOP nap by an interrupt already latched in INTREQ, the pre-display sprite DMA lines are replayed slot by slot at their own beam time so a descriptor rewritten from the vertical-blank interrupt is seen when the hardware would see it, and a trackloader parked on DSKSYNC no longer costs a whole-revolution cell scan per idle slice (Spooky Town under Kickstart 1.3 was the witness, compared against a vAmiga 5 reference frame).
• DSKBYTR is framed by the read shifter. Paula frames the byte with the shifter's bit counter, the one a WORDSYNC match resets, not the track's own byte grid, so bytes read off an IPF or flux track at an arbitrary sync phase were shifted; WORDEQUAL is now the comparator's live one-cell level, and IPF density models 3..9 (Copylock, Speedlock, Brierley) decode with the mastered variable cell timing instead of uniform 2 us cells. Lemmings' Copylock key-track check passes (issue #610).
• Akiko delivers subcode frames during CD-DA play. The Q channel is regenerated from the TOC (control, track, index counting a pregap down, track-relative and absolute MSF in BCD, inverted CRC-16) at 75 Hz with the subcode interrupt, and the SubQ command reports the running position; Liberation's intro, which busy-waits on CD_ADDFRAMEINT, plays through. The TX DMA now drains the guest's 256-byte command ring into a drive-side buffer while a lead-in dump streams, instead of consuming one byte per delivered packet, so discs with more than about 25 tracks no longer lap the ring and produce checksum-error replies the real drive never sends (Pinball Illusions, 39 tracks).
• Agnus cancels a fetch run carried past the last display line. The bitplane sequencer honours DDFSTOP only at the next fetch-unit boundary, so a hires window whose last unit overruns the line end carries BPRUN into the next line; Agnus drops it with the vertical flop on the DIWSTOP.V line, which Copperline did not, painting one phantom row below the display. A new ddfprobe-vspill golden pins it (45 goldens now).
• 68030 and 68040 timing calibrated on a real A4000. A new bootable accelprobe measured exception round trips, jsr/rts, movem, cpushl, chip and fast RAM read/write rates and the SetPatch MMU table walk on a BFG9060, an A3640 and a Commodore 68030 board against the CIA E-clock. The scaled-68000 approximation over-billed plain 68040 execution about 2-2.5x while the real 68030's core figures matched the A1200's 68020; m68k 0.12.1 moves the 68030 onto the MC68020UM tables and gives the 68040 a single-issue pipeline model. The fast-RAM speed-class and CPU-slot bridge billing the probe also exposed remain open.
• Toccata: the AD1848 mixer fallback held the last DAC sample forever after the codec stopped (a permanent DC offset), and disabling playback while capture stayed enabled left playback active; both fixed by Simon Dick.
• Bundled AROS ROM refreshed to upstream master a3cfa659ed: the open cd32mpeg.device and CDXL work (PR 1089, carrying Copperline's sector-ordering fix), the CD32 chip-memory savings and CDXL presentation series (PRs 1109 and 1125), exec spinlocks, and a smaller ROM footprint. One local patch keeps the DOS process-stack floor at 8 KiB, because upstream's new 4 KiB floor overflowed the shell under --run.

Desktop, tooling and platform

• Save-state persistence. A failed or interrupted save no longer truncates the previous snapshot, and expansion boards serialize with permanent wire IDs instead of feature-dependent enum indices.
• Headless debugging is timeline-transparent. A release test now proves that arming any COPPERLINE_DBG_* breakpoint, watch, trace or dump leaves the emulated timeline byte-identical, so instruments can be layered onto one run; the one exception, [cpu] jit, logs a warning when it falls back to precise timing.
• CI builds a lot faster. A ci cargo profile drops fat LTO for the test binaries (macOS CI from about 40 minutes to about 4), packaging caches are isolated per job, and the derived fuzz lockfile and Flatpak cargo-sources list are generated on demand instead of tracked.
• Documentation. New chapters for VS Code, the Bartman fork, the DAP adapter, profiling and WinUAE state import; the custom-register reference; a full refresh of the guide, debugger and internals chapters against the current implementation.
• Guest code builds with the amiga-gcc:gcc-v16.2 image; m68k 0.12.1, toml_edit 0.25, syn 3 and routine dependency updates.

External contributions

• Simon Dick (@sidick) built copperhf.device, Copperline's emulator-native autoboot hard-disk controller, from the Zorro board and guest ROM through the launcher page and copperline-import-uae mapping, and fixed the Toccata's stopped-codec DC offset.
• Lee Hobson (@hobbo91) added the launcher's auto-launch and moved host data out of the hidden config tree into Documents.
• Bartman (@BartmanAbyss) wrote the Amiga C/C++ extension whose Copperline backend is proposed in vscode-amiga-debug PR 307; the fork used in the docs is public and pinned.

Installation

Browser (no install): copperline.dev/try

macOS (Homebrew):

brew tap copperlinehq/copperline https://github.com/CopperlineHQ/Copperline
brew install copperline

macOS (DMG): download Copperline-0.19.0-macos-universal.dmg below, open it, and drag Copperline.app to Applications. The app is ad-hoc signed but not notarized, so first launch may require right-clicking the app and choosing Open.

Linux (AppImage): download Copperline-0.19.0-x86_64.AppImage below, then:

chmod +x Copperline-0.19.0-*.AppImage
./Copperline-0.19.0-*.AppImage

Windows: download and extract the portable Copperline-0.19.0-win-x64.zip (or Copperline-0.19.0-win-arm64.zip on ARM) below.

From source:

cargo build --release
./target/release/copperline

VS Code: build copperline and copperline-ctl from this tag, then package the extension from tools/vscode-copperline (docs/debugger/vscode.md); the Bartman fork install is in docs/debugger/vscode-bartman.md.

The bundled AROS boot ROM lets Copperline run out of the box, CD32 discs and the FMV cartridge included, and the A2091 and lide.device boards autoboot with their bundled open ROMs. A real Kickstart ROM and disk, hard-disk, or CD images are still required to run most commercial Amiga software; these are not included. The MT-32 ROMs are likewise yours to supply.

Full changelog: v0.18.0...v0.19.0