44 lines
5.4 KiB
Markdown
44 lines
5.4 KiB
Markdown
# Native execution tracing
|
||
|
||
> 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.
|
||
|
||
## Capture
|
||
|
||
- Capture options and trigger edits apply on **Start New**, not to a capture already in progress.
|
||
|
||
- Choose **1–100,000 samples**. **Start New** replaces the previous capture and arms the trace. The bound counts instruction and optional event rows together. At the limit, capture stops and the machine continues in its existing state.
|
||
|
||
- **Start at** accepts up to 32 logical hexadecimal addresses separated by spaces or commas; `$` and `0x` prefixes are accepted. Blank means the next executed instruction. Matching any start address begins capture immediately before that instruction.
|
||
|
||
- **Stop before** accepts the same syntax. Matching any stop address stops capture before that instruction, while the instruction still executes normally. This is a trace trigger, not a breakpoint. Identical start/stop addresses produce an empty capture. With no stop addresses, use the limit or **Stop**.
|
||
|
||
- **Clear** stops capture and removes its samples. Soft/cold reset and processor/RAM changes stop capture and retain already collected samples. Loading a different machine/profile or quitting clears it.
|
||
|
||
- Instructions store their own pre-execution bytes and before/after register states. Self-modifying code, subsequent edits, and MMU changes do not rewrite historical samples. Inspection does not re-read device ports; an instruction whose encoding crosses unavailable I/O is explicitly unavailable rather than decoded from invented bytes.
|
||
|
||
Instruction tracing uses the retained CPU engines' before/after hooks. Ordinary HD6309 TFM tracing follows their per-transfer-byte execution loop; an explicit debugger Step captures the whole TFM instruction, consistent with the existing Step operation. A partially filled capture remains armed when a breakpoint pauses execution, and continues when the user continues or steps.
|
||
|
||
## Events and timing
|
||
|
||
IRQ request, servicing and vector-entry rows come directly from the CPU hooks. IRQ/FIRQ/NMI names identify the line. A request does not imply that the CPU serviced it; separate rows establish that. The retained CPU engines do not emit a separate masked-interrupt callback, so the Mac does not invent masked events from the CC register.
|
||
|
||
**Screen events** records real HSYNC/VSYNC transitions and guest video-register changes from the existing GPU/register hooks. **Scheduler events** records entry and return of the native bounded frame-execution call. The Mac uses the event-driven timing engine; it does not fabricate the old Windows scheduler's state-switch variables, drift or nanosecond budgets. Screen events are timing/register events, not screenshots.
|
||
|
||
Rows expose the frame number and absolute emulated **master clock** within the current machine timeline. The native raster period is 263 × 912 master clocks; the frame-relative event clock supplies the remainder. Master clocks remain comparable across normal guest CPU speed/overclock changes. Instruction-cycle counts are measured by the CPU engines and are distinct from master clocks.
|
||
|
||
Select two rows and choose **Mark A** and **Mark B** to compare their master-clock difference and nominal emulated milliseconds (14.31818 MHz master crystal). This is guest time, not wall-clock capture duration or playback timing. A new capture or Clear resets marks.
|
||
|
||
## Inspection and export
|
||
|
||
The viewer fetches immutable pages of at most 256 rows at 2.5 Hz only while visible. Previous/Next and a decimal sample-number field navigate the capture. Select a row for its complete CPU before/after registers, event detail and instruction-cycle count. Both CPU register sets are supported.
|
||
|
||
**Export CSV** uses a decimal inclusive first/last sample range; a blank end means the current last sample. The range is copied on the machine's serial queue, then CSV formatting runs on a background queue before opening a native save panel. The emulator can continue during formatting. Cancellation or write failure leaves the trace and emulator unchanged. Export uses the retained historical samples, including instruction bytes. Numeric CSV addresses, clocks, cycles and register values are decimal; instruction operands remain assembler-style hexadecimal. Event numbers correspond to `TraceEvent` in `MachineDefs.h`.
|
||
|
||
The maximum capture is deliberately finite. It is not an unbounded profiler or a host-performance measurement. Trace capture and export consume extra CPU/memory while enabled; normal disabled execution uses the already-existing false debug-hook checks.
|
||
|
||
## Regression coverage
|
||
|
||
`DebuggerTraceTests` checks both processors, bounded capture without pausing or resetting, multiple start/stop addresses, stepping, immutable snapshots, ranged export, real screen/scheduler events and monotonic clocks across frame boundaries. It checks actual CPU IRQ request/service/vector callbacks, plus capture retention across reset. It also covers authoritative enabled/disabled breakpoint state and atomic rejection of conflicting states.
|
||
|
||
`DebuggerTraceBridgeTests` checks immutable decoded samples, before/after register text for both CPUs, range export, rejected triggers without losing a previous capture, strict trigger parsing and enabled/disabled breakpoint bridge state. Native UI validation and final build results are recorded in the main [debugger guide](DEBUGGER.md).
|