Waveform export (VCD logic analyzer)

Copperline can record internal chipset signals -- beam counters, chip-bus owner, CPU bus accesses, Copper and blitter state, custom register writes, interrupt levels, and DMA activity -- into a standard VCD file. The resulting trace can be viewed in GTKWave or any compatible logic analyzer trace viewer.

Because bus arbitration in Copperline is evaluated per colour clock, exported traces show exact cycle interleaving between CPU, Copper, Blitter, and DMA channels.

Traces are bounded and trigger-based: the recorder arms, waits for a trigger condition, captures for a specified duration, and writes the output file.

Capturing waveforms¶

Command line¶

copperline --config game.toml --noaudio \
  --waveform out.vcd \
  --wave-trigger pc=0x00C033C2 \
  --wave-duration 20000cck \
  --wave-signals cpu,bus,copper,blitter \
  --screenshot-after 30 /tmp/shot.png

Debugger console (Cmd+K / Alt+K)¶

WAVE START out.vcd pc=C033C2 20000cck cpu,bus,copper,blitter
WAVE                # Display capture status
WAVE STOP           # Finish capture immediately

Control protocol (CCP)¶

waveform.start {"path":"out.vcd","trigger":"pc=0x00C033C2","duration":"20000cck","signals":"cpu,bus,copper,blitter"}
waveform.status
waveform.stop

Debugger window (Cmd+B / Alt+B)¶

In the Wave tab, enter trigger and duration parameters, then click Arm.

Default values:

• Trigger: now (immediately upon arming)

• Duration: 1f (one video frame; accepts f or frames suffix)

• Signals: all

• Default output filename: copperline-wave-<timestamp>.vcd

Trigger specifications¶

Duration formats¶

• 20000cck (or bare integer): duration in colour-clock cycles

• 2f or 2frames: duration in video frames

• 50ms, 1.5s: duration in emulated time

A 10-second safety cap limits maximum capture length, and files are automatically closed if size exceeds 512 MB.

Signal groups¶

Select groups with --wave-signals (comma-separated list, default all):

Viewing in GTKWave¶

gtkwave out.vcd
# Optional: convert to GTKWave fast binary format:
vcd2fst out.vcd out.fst

In GTKWave:

1. Expand the copperline scope in the signal tree.

2. Add desired signals to the display.

3. Set owner_name, state, and slot display format to ASCII.

4. Use markers to measure timing intervals in colour clocks.