Publish VCC Plus OSS source distribution for 3.6.2 build 60

This commit is contained in:
Brian Holman committed 2026-11-13 00:14:03 -07:00
commit c652a5276d
1192 files changed
+272368

No files matched your search

+85
View File
@@ -0,0 +1,85 @@
# Native debugger
> 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.
## Execution semantics
Explicit instruction stepping retains the Windows CPU engines' behavior: execute the opcode before servicing pending interrupts. Continue uses normal interrupt dispatch and temporarily bypasses a breakpoint just reached, so an interrupt-handler breakpoint can still stop execution.
HD6309 **Step** completes an entire TFM block-transfer instruction. Event timing continues during the transfer and completed video frames are counted/published at their actual raster boundaries. Continue from a breakpoint on TFM can stop again at the same address after one transfer byte, following the retained core's breakpoint checks. This differs from the whole-instruction Step action.
The 6309 stepping loop now clears stale TFM continuation after PC changes, reset and invalid-instruction traps, preventing it from following arbitrary code indefinitely. Regression programs cover both native and emulation modes, interrupted transfers, invalid operands and transfers spanning multiple frames.
The last completed video frame remains visible while paused; a few instruction steps need not complete a new raster frame. Single-step audio is discarded so resuming does not play a delayed burst.
## Implementation boundaries
`MachineSession` owns debug execution and breakpoints. The Objective-C++ controller captures CPU state, memory and machine/media status on its existing serial queue. No live core pointers cross into Swift. A window-owned `DebuggerModel` requests snapshots at most five times per second while visible; only one inspection is pending at a time. Closing cancels polling. Edits retain focus and text drafts and wait for a fresh authoritative capture before allowing another mutation.
Disassembly reuses upstream VCC opcode tables with portable formatting over captured bytes. It supports both CPU instruction sets, signed offsets, indexed forms, address wrapping and HD6309 register/bit/TFM forms. Invalid encodings produce bounded `FCB` rows. VCC's optional HALT/BREAK pseudo-opcodes are not enabled in this baseline and are not presented as active instructions. A capture is bounded to 64 KiB of logical memory, 48 decoded rows and an additional 256 physical RAM bytes only when physical inspection is selected. MMU data and both memory spaces belong to the same execution boundary. No work is added to normal frame polling when the debugger is closed.
## Validation
Authored programs and private, isolated app preferences are used throughout. No ROM or personal media is required by the debugger tests. Verified on November 3, 2026 with Xcode 27.2 on Apple Silicon:
- All **202 background XCTest checks passed on arm64 and x86_64 under Rosetta**, with zero failures. The full suite contains 203 tests; the unrelated foreground Metal presentation case was excluded from the background runs.
- Nineteen added debugger tests cover both CPU engines, snapshots and async commands, exact stepping, pending interrupts, repeat breakpoint stops, reset preservation, mapped-memory protection, strict input, focus/drafts, decoder forms and long/interrupted/invalid TFM transfers.
- The targeted native XCUITest passed: live opening, Pause/Set PC/Step, memory edit, breakpoint hit/removal, Continue, resizing, typing across refresh and close/reopen. Session generation and authored mounted media were retained. The native window was visually inspected.
- Universal Release app built and its executable verified to contain both arm64 and x86_64. This is a build check, not a newly signed/notarized distribution release.
- No new test requires private ROMs. Existing unsigned/local development products and test results stay outside Git. The previously published local signed app/DMG were not replaced.
The captured workspace uses the authored diagnostic loop and a test RAM edit. Tests under Rosetta are not physical Intel validation. The native UI check ran on the current Mac, not macOS 14, and does not certify comprehensive VoiceOver usability or Windows debugger parity.
## MMU and physical RAM increment — November 3, 2026
Eight new core/bridge/model tests cover both processors and all four RAM capacities; task switching and disabled mappings; ROM overlays and all-RAM mode; FE00 overrides and fixed ROM vectors; high 8 MB banks, latched prefixes and mirrored RAM; immutable snapshots, end bounds and recovery after a smaller RAM configuration. Physical capture has no device-read side effects and does not advance guest clocks or mutate the machine.
All **210 background tests passed on arm64 and x86_64 under Rosetta**. The full suite now contains 211 tests; the unrelated foreground Metal presentation case was excluded from these background runs. The existing debugger stepping/breakpoint/edit/focus UI case and the new live MMU/physical-memory UI case passed. Native inspection caught an accessibility-label recursion crash in selectable physical bytes; replacing them with plain labeled text fixed the crash, and the same test passed again. Final screenshot review corrected the segmented-picker label layout. The final universal Release app built successfully with both architectures. The signed distribution app and DMG were not replaced.
Both captures use the authored diagnostic in the isolated test app. The memory and MMU areas scroll independently; the divider can be dragged to give either more space. The normal emulator and personal media were untouched. Rosetta is not a substitute for physical Intel testing, and these UI checks do not certify macOS 14 or comprehensive VoiceOver behavior.
At the time of the MMU increment, physical export/disassembly, source/listing association and execution tracing were outside its scope; the following increment implements them. Physical editing remains excluded. Inspecting MMU controls does not change them; guest software remains responsible for programming the MMU.
### Source listings
Use **Source → Open Listing…** to select a LWASM `.lst` or text listing. Generate an absolute listing with the [LWTOOLS assembler](https://www.lwtools.ca/manual/manual.html), for example:
```sh
lwasm --6809 --format=decb --list=program.lst --output=program.bin program.asm
```
The listing does not load its program. Load the corresponding binary separately, then use exact logical CPU addresses for source following and breakpoints. The importer does not assert that listing bytes match current memory, and it does not read filenames embedded in the listing. Source locations retain LWASM's sometimes-truncated filename and original line number; the left-hand row number identifies the listing itself.
- Click a circle to add/remove a shared address breakpoint. Dashed circles identify disabled breakpoints. Their context menus offer Enable/Disable, Show Disassembly, Show in Memory, Set PC Here while paused, and Copy Source Line.
- **Follow PC** selects an exact addressed line, never a guessed nearby line. If several source lines share an address, a selected matching line is preferred; all share the same logical breakpoint. An unmatched PC is reported explicitly.
- **Find Next** searches source text and source locations, ignores case and wraps at the end. Searching or selecting a line turns off source PC following, allowing inspection without losing the selected location to live polling.
- **Close** unloads debugging information and retains all shared breakpoints. Failed imports preserve the previously loaded listing. Neither action changes guest execution.
- Imports are bounded to 8 MB, 50,000 lines and 4,096 characters per line. UTF-8 and BOM-marked UTF-16, standard filename/line metadata, `--list-nofiles`, cycle annotations, duplicate addresses and address zero are supported. Comments, directives, continuation bytes and non-code offsets remain visible without invented instruction associations.
CMOC uses LWASM to produce relocatable object files and LWLINK to assign final addresses. Its intermediate `.lst` is not a final logical-address listing. This standalone listing importer still rejects `SECTION`/`ENDSECTION` with a linker-map explanation. The separate **Develop → C Development** workspace now builds CMOC projects, resolves object sections through the matching linker map, verifies the linked executable bytes and supports C-source breakpoints across translation units. It retains exact build/source identity and does not treat a raw relocatable listing as an executable address map. See the workspace implementation and validation. The workspace now also provides [C source-line Into/Over/Out, variables and read-only watches](../development/CMOC_SOURCE_DEBUGGING.md). These use verified compiler metadata and the same machine; they are separate from importing an arbitrary assembler listing. Multiple statements on one source line are not separately mapped. See the C development roadmap for remaining work.
### Memory tools and tracing
See [Memory Tools](DEBUGGER_MEMORY_TOOLS.md) for bounded physical disassembly, explicit logical origin, raw range export and optional OS-9 interpretation. See [Trace](DEBUGGER_TRACING.md) for start/stop addresses, historical before/after registers, real interrupt/video events, native scheduler events, timing marks and ranged CSV export. CSV formatting runs off the emulator queue after capturing an immutable bounded range.
The original authored assembly and actual LWASM-generated listing are safe to retain in Git and correspond to the test diagnostic's two-instruction loop. Personal ROMs, games, compiler builds and generated test exports remain outside the repository.
### Completion validation
The checks below record completion of the original Windows-parity debugger milestone. Later CMOC workspace qualification is recorded separately in the workspace guide.
The final background suite passed **233 tests with zero failures on arm64 and x86_64 under Rosetta**, run separately on November 3, 2026. The full scheme contains 234 tests (61 shared and 173 Mac); the unrelated foreground Metal presentation case was excluded from these background runs. Twenty-three new tests cover listing parsing and failure recovery, disabled breakpoints, memory bounds/export, OS-9 interpretation, trace triggers and immutable samples, both CPU register sets, range export and asynchronous file-save success/failure.
Four targeted native UI cases passed during this increment: the existing execution/edit/focus case, MMU/physical inspection, source listings/disabled breakpoints, and memory/trace export. The final two-case run verified the corrected compact Source layout and background saves through actual native file panels. It read back the exact five-byte raw export and trace CSV, checked field focus and retained drafts, and checked continued execution, audio and mounted media where no explicit execution command was issued. The full unrelated UI suite was not rerun.
Native screenshot review exposed a Source minimum-height conflict in a restored compact window. The source and memory panes now share a stable combined minimum height, keeping execution controls below the title bar. A regression assertion guards that layout. An earlier overlapping test run contended for the audio device; the final architecture suites ran separately and both passed. All three final window captures were visually inspected. The final universal Release build succeeded, and its executable was verified to contain both arm64 and x86_64. This is a local build check; the signed distribution app and DMG were not replaced.
These captures use only the isolated authored diagnostic. Source lines and memory panes scroll independently; the splitter can give either more room. See the Windows source-level parity review for remaining differences. Fresh side-by-side Windows runtime comparison, physical Intel hardware, macOS 14 and comprehensive VoiceOver certification remain validation gaps. The CMOC workspace and SDC baseline are now implemented and qualified within their documented scope.