Files
VCCPlusOSS/docs/macos/DEBUGGER_MEMORY_TOOLS.md

5.5 KiB
Raw Permalink Blame History

Debugger memory tools

Technical evidence extract for the VCC Plus white paper. Only reviewed contracts, mechanisms, methods, results and limitations are retained. Original validation dates and configuration limits remain historical; this export is not a new test run.

Disassembly

Choose Mapped CPU or Physical RAM, then enter hexadecimal Start and End (inclusive) addresses. Physical RAM uses the installed capacity, up to $7FFFFF for 8 MB. Mapped CPU uses $0000–$FFFF. Reversed, overflowing and wrapping ranges are rejected.

For physical RAM, Assumed CPU origin specifies the 16-bit logical address at which those bytes would execute. This controls relative branch destinations. The Location column always shows the actual RAM location; CPU shows the assumed logical address. Physical RAM is not implicitly mapped into the running processor merely by viewing it.

Disassemble captures up to the first 4,096 bytes and displays at most 128 rows. It takes a new capture only when requested; the caption identifies the processor and capture's cycle count. Changing address fields does not silently replace an existing capture. An incomplete instruction at the end becomes an explicitly marked FCB, with no invented trailing bytes. Unavailable mapped I/O is marked as unavailable and advances one address. Rows provide a native Copy Row context-menu action.

Both MC6809 and HD6309 use the retained VCC opcode tables. HD6309 decoding is available in native and emulation mode. The normal live disassembly view continues to follow the actual CPU PC; this separate area deliberately does not follow PC.

OS-9 interpretation

Interpret OS-9 calls and module headers is opt-in because ordinary software may use SWI2 differently. It consumes the service byte after SWI2, names known OS-9/NitrOS-9 requests, and leaves unknown/private requests numeric. Names follow the NitrOS-9 service definitions. This annotation does not imply that a particular guest OS implements every named service.

A module header is recognized only with $87CD sync and valid nine-byte header parity. Its row reports size, name offset, type/language, and attributes/revision. Program, system and file-manager headers also show execution and storage offsets. Header interpretation is an aid to inspection; it does not validate a module's CRC or load, relocate or execute it.

Raw binary export

Export Binary… captures the entire selected range and opens a native save panel. The immutable captured bytes are saved atomically. The default extension is .raw; this is not a Disk BASIC LOADM file and has no DECB header. Export while running captures one execution boundary and does not stop the session. Export a paused machine when repeatable guest state is important.

A mapped range containing unavailable I/O is rejected before opening the save panel. The app does not substitute zeroes into an exported image. Choose a range excluding that I/O, or export physical RAM instead. This safeguard also applies to a whole-CPU-space export.

File errors remain visible in Memory Tools. Canceling the save panel writes nothing and changes no emulated state. Export does not alter mounted disks or acknowledge their dirty state.

Graphics Preview

Open Debug → Show Debugger → Graphics Preview. Current Video Page follows the active video registers and palette, including the physical page that the video chip sees. While running, the preview samples up to four times per second. Pausing lets you inspect a stable page. A capture reads memory without advancing the emulated beam or changing the program.

At Address interprets a hexadecimal start address as text/SG4, PMODE 0–4, or HSCREEN 1–4. Select Mapped CPU for addresses used by BASIC or assembly instructions. Select Physical RAM for a page elsewhere in installed memory. A manual PMODE preview has its own color-set selector. A range extending beyond its address space produces an error. Unavailable mapped I/O appears as a gray pattern.

Click a pixel or enter X and Y in Pixel Inspector. It shows the stored byte, its address and the bit mask for that pixel. Attributed GIME text also shows the attribute byte. Composite artifact colors can depend on neighboring bits. Show Byte in Memory selects the byte in the matching address space. Preview as Graphics opens a preview from the memory inspector. Fit and 1×–4× zoom use nearest-neighbor scaling. Highlight step changes marks pixels whose displayed color changed across a single debugger instruction on the same page and mapping.

Scope and validation

Regression coverage exercises both CPUs, logical versus physical backing, the final byte of 8 MB RAM, full physical export, invalid and overflowing ranges, immutable captures, unchanged guest cycles/PC/generation, incomplete instructions, unavailable I/O, optional OS-9 calls, unknown services and valid/invalid module headers. Model coverage checks native export data and file bytes, read-error refusal, address parsing and physical decoding at the final byte.

Separate Windows raw ROM/PAK views and adjustable memory-grid widths remain outside these tools. Mapped ROM remains inspectable through the CPU address space. Physical editing, assembly-level Step Over/Out, arbitrary register editing and conditional/watchpoint debugging are not provided by these tools. The separate C workspace implements C source-level Into/Over/Out.