Ultimate Tool C64 Protocols #

Ultimate Tool currently uses three independent fixed-memory protocols:

• UTD2: C64-to-host diagnostic events plus cooperative liveness in 256 bytes
• UTX2: C64-to-host cooperative crash context and optional exact site in 32 bytes
• UTC1: one host-to-C64 startup command in 64 bytes

The project manifest declares their addresses. The Rust-MOS fixture reserves $C000-$C0FF, $C100-$C13F, and $C140-$C15F as NOLOAD linker regions. All multibyte integers are little-endian.

Diagnostic mailbox (UTD2 version 2) #

The host continues to parse legacy UTD1 version 1 mailboxes. UTD1 has no heartbeat or crash terminal/event, so it cannot support opt-in hang detection.

Header #

Offset	Size	Meaning
0	4	ASCII magic UTD2
4	1	Protocol version, 2
5	1	Header size, 16
6	1	Record size, 60
7	1	Record count, 4
8	2	Latest published sequence; zero means no event
10	1	Terminal state: 0 running, 1 pass, 2 fail, 3 crash
11	2	Wrapping cooperative heartbeat counter
13	3	Reserved and zero

Event records #

Four records begin at offset 16.

Record offset	Size	Meaning
0	2	Event sequence
2	1	Event kind
3	1	Flags
4	2	Project-defined numeric code
6	1	Payload length, at most 52
7	1	Reserved and zero
8	52	Printable ASCII payload

Event kinds are ready, log, assertion pass, assertion fail, test pass, test fail, and crash (1 through 7 respectively). A crash terminal requires exactly one crash event and no pass/fail terminal event; every other terminal rejects crash events.

Sequences use 1…65535, skip reserved sequence zero, and wrap to 1. The C64 advances the ring slot independently from the numeric sequence so all four records remain available across that wrap.

The publisher clears a selected record sequence, writes its metadata and payload, publishes the record sequence, writes a terminal state when applicable, and publishes the header sequence last. No event may follow a terminal event.

DeveloperSession::heartbeat() advances the 16-bit heartbeat independently of event publication and wraps through zero. The host begins monitoring only after ready and startup-command acknowledgement. A heartbeat may advance between the two stability reads without invalidating an otherwise stable event publication; the host uses the heartbeat from the second read.

DeveloperSession::crash(code, label) publishes an explicit terminal crash without an exact origin. The panic_halt helper reclaims an initialized UTD2 mailbox on the terminal panic path, publishes code 0x0001 and the stable label panic, then halts. crash_here!(&mut session, code, label) is the opt-in exact-site path described below.

The host reads the complete 256-byte mailbox twice and compares all publication state. UTD2 heartbeat bytes are excluded from that equality check because they are independently published liveness state. A stable snapshot must expose a contiguous ring ending at the published sequence. The host accumulates and deduplicates events, but any missing sequence is a hard protocol failure. After the first valid mailbox, three consecutive malformed stable reads fail the run and preserve the raw read pair.

Crash context (UTX2 version 2) #

Manifest schema 4 may opt into a fixed crash context plus bounded memory captures. The SDK clears the 32-byte context during initialization. A cooperative crash records the context before publishing its terminal event. The host continues to accept UTX1; those contexts have no exact site.

Offset	Size	Meaning
0	4	ASCII magic UTX2
4	1	Protocol version, 2
5	1	Context size, 32
6	1	Publication state: 1 writing, 2 complete
7	1	Register semantics: 1 capture-helper entry
8	1	Accumulator
9	1	X register
10	1	Y register
11	1	Processor status as pushed by PHP
12	1	Hardware stack pointer before the capture helper call
13	2	Crash code, which must match the crash event
15	1	Site semantics: 0 unavailable, 1 instrumented callsite
16	2	Runtime address after the instrumentation helper call, or zero
18	14	Reserved and zero

The register values are the values available on entry to the SDK's assembly capture helper. They are deliberately labeled capture_entry; they are not represented as an exact snapshot of the instruction that caused a Rust panic. As on a 6510, PHP forces the break and unused bits in the saved status representation.

crash_here! invokes a dedicated 6510 assembly helper directly from the instrumented function. The helper reads only its own JSR return slot, adds one to normalize the 6510 return address to the following instruction, and records that address before normal crash publication. It never scans arbitrary stack words. DeveloperSession::crash and panic_halt publish UTX2 with site semantics zero and address zero.

UTX1 uses the same bytes through offset 14 and requires bytes 15–31 to be zero.

After a valid crash terminal/event, the host reads the context twice and requires identical, complete publications. It then reads only:

• The configured number of hardware-stack bytes beginning at $0100 + SP + 1, truncated at the end of the stack page
• Explicit manifest-declared zero-page ranges
• Explicit manifest-declared global ranges

Configuration limits the stack to 64 bytes, each named range to 64 bytes, eight ranges of each kind, and 256 captured bytes in total. Zero-page ranges must remain below $0100; selected globals cannot overlap C64 I/O or protocol regions. This slice does not perform arbitrary memory reads, source-address resolution, stack walking, or register reconstruction.

Raw context, stack, zero-page, and global bytes are preserved alongside schema-2 crash-state.json. Schema-1 crash-state evidence remains readable. Each memory record includes its address, length, evidence filename, and SHA-256.

Startup command (UTC1 version 1) #

The one-shot command slot has a 12-byte header followed by 52 combined bytes of command name and payload.

Offset	Size	Meaning
0	4	ASCII magic UTC1
4	1	Protocol version, 1
5	1	Slot size, 64
6	1	State: 1 waiting, 2 submitted, 3 accepted, 4 rejected
7	1	Reserved and zero
8	2	Request sequence
10	1	Command-name length; nonzero when submitted
11	1	Payload length
12	52	Printable ASCII command name followed by payload

The device initializes the slot and publishes waiting after the diagnostic mailbox is ready. The host requires both the ready event and two identical waiting-slot reads before writing.

For VICE, the binary monitor stops execution while Memory Set writes the full slot. For an Ultimate, the runner pauses the CPU at the advertised application safe point, posts the 64 bytes through DMA, and resumes even when the write fails. Neither adapter retries an ambiguously accepted write.

The SDK validates the complete submitted slot, changes its state to accepted, and returns an owned command to the application. Unknown application-level commands are reported through normal diagnostic failure events. The current fixture accepts command name scenario with payload pass, fail, crash, panic, hang, timeout, or malformed.

Timeout classification #

Manifest schema 3 adds optional per-test heartbeat_timeout_ms. It must be positive, shorter than the overall timeout, and at least three times the largest configured target polling interval.

• A valid crash terminal/event is classified crash.
• A configured heartbeat that stops advancing is classified hang.
• An advancing heartbeat whose overall deadline expires is classified timeout.
• A missing ready event remains a readiness-stage timeout.

Without heartbeat_timeout_ms, the runner retains generic deadline behavior and never relabels an uninstrumented program as hung.

DMA boundary #

The fixture performs no UCI transfers. The ready/waiting state is therefore a valid quiescent checkpoint for the single coordinated write. Future transports must add explicit application-level safe-point negotiation before mixing UCI activity with host DMA.