Publish VCC Plus OSS source distribution for 3.6.2 build 60
This commit is contained in:
commit
c652a5276d
1192 files changed
+272368
No files matched your search
@@ -0,0 +1,135 @@
|
||||
# C source debugging
|
||||
|
||||
> 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.
|
||||
|
||||
VCC Plus extends the existing CMOC workspace with source-line stepping, verified C call stacks and read-only variable inspection. The source editor, debugger and live CoCo use the same machine; changing inspector tabs never reloads or resets it.
|
||||
|
||||
## Stepping
|
||||
|
||||
Build a project, then run to a verified source breakpoint. **C Step Into** advances to the next mapped source line, entering functions whose source is available. **Over** completes the current line without stopping inside called functions, except at an existing breakpoint. **Out** finishes the current function and stops at its actual return address; the caller may still be completing the original call expression. **Instruction** remains available for assembly-level work.
|
||||
|
||||
Mapping is by file and line, not individual statements or columns. Several statements on one line cannot be stepped separately. A one-line loop stops on a new iteration. Unmapped library code is executed normally; returning into unmapped code shows the assembly fallback. Existing user breakpoints take precedence. Pause cancels a pending step. Instruction, frame and call-depth limits prevent an unbounded step; the stop reason explains why execution paused. Interrupts and 6309 TFM block transfers retain their normal guest behavior.
|
||||
|
||||
Every step checks the paused machine generation, program revision, MMU mapping, PC and verified instruction bytes on the emulation queue. Flat programs retain their original effective-MMU fingerprint throughout a step. A reset, debugger memory edit, changed source, different build or incompatible mapping requires reconnecting the build. Changed executable bytes are not silently treated as the original C program.
|
||||
|
||||
## Banked programs
|
||||
|
||||
Custom Make projects can supply a verified banked debug manifest alongside their build outputs. This associates the delivered program with its original linker output, source/object/listing identities, complete relocated code sections and explicit logical-to-physical RAM page assignments. See [the MCP banked-development contract](MCP_BANKED_PLAYTEST.md) for the manifest and installed-app workflow. A packed or overlapping binary alone is insufficient to reconstruct those associations.
|
||||
|
||||
Different modules may occupy the same CoCo address at different times. The debugger identifies a module by its actual installed RAM pages and complete expected executable bytes, including assembly code outside mapped C lines. Identical opcodes in a loader or another physical page do not establish source identity. ROM overlays do not count as mapped RAM. Overlapping modules must have mutually exclusive page assignments; ambiguous simultaneous claims are rejected.
|
||||
|
||||
Arming disk-source stops pauses only to configure the debugger; it does not copy code into RAM, change PC or reset the machine. Normal DOS/LOADM execution installs the program. A source stop becomes eligible when its own module is mapped and matches its verified code. Other overlays need not be mapped simultaneously. Manual debugger breakpoints remain independent and can still stop in unmatched code.
|
||||
|
||||
The attachment survives expected bank switches. Each paused source location, call stack and variable view uses the currently mapped modules from the same immutable machine snapshot. A bank-aware source step checks the initial paused fingerprint to reject stale commands, then follows declared page switches and selects the matching module at each mapped instruction. A wrong bank or changed module code stops the step with an explanation. The ordinary flat-program fingerprint rules remain unchanged.
|
||||
|
||||
Bank awareness does not recover optimized locals or create a frame convention. Compiler-described globals can be inspected where their storage is currently mapped and verified; unavailable overlay storage remains unavailable. Caller reconstruction still requires the supported, verified U-frame convention and stops at unsupported assembly, optimized or unmapped boundaries. An address by itself does not identify a module, and the debugger does not switch guest banks merely to inspect a value.
|
||||
|
||||
### Verified function-entry stops over MCP
|
||||
|
||||
For an owned playtest, a banked project can expose executable function symbols
|
||||
in addition to mapped C statements. `get_build.source_debugging.functions`
|
||||
contains unique names with a mapped C body instruction; `function_entries`
|
||||
contains unique compiler symbols whose full entry-to-end range is covered by
|
||||
verified executable guards and physical page assignments. Data/BSS symbols,
|
||||
ambiguous names and incomplete executable ranges do not become entry stops.
|
||||
|
||||
Select `stop_kind: "function_entry"` with the advertised name when starting an
|
||||
owned run or arming `playtest_debug`'s `stop_at` action. This can stop in an
|
||||
assembly input sampler or a verified prologue before its first C statement.
|
||||
At a pure assembly stop, `source_stop` remains null and `function_stop` identifies
|
||||
the actual symbol, entry/current address, module, physical RAM and declaration
|
||||
location. The declaration line is not an executing C statement. Subsequent
|
||||
instruction steps report `assembly_instruction` where no mapped C line exists.
|
||||
A C source stop can also include the enclosing verified function identity.
|
||||
|
||||
The runtime uses the same immutable snapshot and complete module-code checks
|
||||
for these observations. It does not guess locals, unwind an unsupported frame,
|
||||
execute an expression or switch guest banks. Owned MCP snapshots expose
|
||||
registers, verified shared globals, locally configured named watches and bounded
|
||||
readable ranges. Native C source stepping and the native assembly debugger retain
|
||||
their existing controls. See [the owned-playtest contract](MCP_BANKED_PLAYTEST.md)
|
||||
for selection, input and retained-disk behavior.
|
||||
|
||||
## Call stacks and caller inspection
|
||||
|
||||
Choose **Call Stack** in the lower inspector while paused in a verified C build. The innermost function is first; recursive invocations appear as separate frames. Selecting a supported caller opens its source at the call site and makes **Variables** and **Watches** use that invocation's parameters and locals. Return to the first frame to inspect the paused function again.
|
||||
|
||||
Frame selection is inspection only: it does not change PC, registers, guest memory or execution. **Into**, **Over**, **Out** and **Instruction** always operate on the actual paused execution point, even while viewing a caller. The editor distinguishes the selected caller from the execution location. Values come from the current paused memory snapshot, not a historical copy taken when the call occurred; globals and objects reached through pointers can reflect changes made by the callee.
|
||||
|
||||
The unwinder supports the ordinary, unoptimized CMOC calling convention with a preserved U frame. It verifies compiled code, frame layout, readable stack links and the direct call instruction associated with each saved return address. Source scope is the caller's call site, not an arbitrary instruction near its return address. Unavailable or ambiguous links stop the stack with an explanation rather than searching memory for plausible return addresses. Interrupt handlers, assembly/optimized frames, indirect calls, nonstandard prologues and unmapped runtime/library callers can therefore leave a partial stack. A partial stack is not a claim that execution started at the oldest displayed function.
|
||||
|
||||
## Variables and watches
|
||||
|
||||
Choose **Variables** in the lower inspector to see compiler-described globals, parameters and locals in the selected frame's scope. Choose **Watches**, enter an expression and press Return or **Add Watch**. Watch expressions are remembered per project; removing one does not alter guest memory. Values are refreshed from a single paused PC/register/memory snapshot and disappear when the program runs or its source identity becomes invalid.
|
||||
|
||||
Supported values include signed/unsigned integers, pointers, arrays and structures/unions. Expand an array or aggregate in **Variables** or **Watches** to browse its elements and members. Pointers show their address first; expanding one explicitly inspects its pointed-to value. Nested values use the selected call-stack frame and the same paused memory snapshot as their parent. Scope and shadowing come from compiler metadata rather than parsing editor text.
|
||||
|
||||
Expansion is read-only. Variables and container children are shown in pages of up to 32 entries; the visible tree is capped at 255 rows and traversal at 12 levels. Pointer cycles stop with an explanation instead of expanding repeatedly. Unsupported children remain individually unavailable so other members can still be inspected. Null pointers, unavailable memory and unsupported pointed-to types produce explanations; a pointer does not imply an array length or an allocation guarantee. A pointer may refer to readable memory that is no longer a live C object.
|
||||
|
||||
Expressions such as `values[2]`, `player.x`, `pointer->field`, `*pointer` or `&score` remain available when a focused watch is more useful than browsing. Expansion never executes a getter or guest function, writes memory, or reads hardware I/O. Open branches stay stable while the same paused snapshot refreshes. Changing frames, advancing execution or invalidating the build clears expansion state so a previous frame’s tree cannot be mistaken for the new context.
|
||||
|
||||
Expressions support integer literals, arithmetic, comparison, bitwise and logical operators. Calculated results use **checked 64-bit watch integers**, not CMOC's target integer-promotion or overflow rules; stored variables retain their declared target types. Function calls, assignments, increment/decrement, casts, floating-point literals and floating-point watch arithmetic/comparisons are not supported. Stored floating-point values are supported as described below. Hardware I/O and unavailable memory are never read through live device ports. Unsupported values produce an explanation, not a guessed number.
|
||||
|
||||
### Floating-point values
|
||||
|
||||
Variables, array elements, structure/union fields, pointer targets and direct watches now display compiler-described floating-point values, including parameters and locals from a verified caller frame. Rebuild existing projects with the updated bundled compiler: older debug metadata does not identify the format and reports that a rebuild is needed. The app never guesses the format from the current ROM, type name or storage size alone.
|
||||
|
||||
The supported encodings are CoCo BASIC's packed five-byte format (also used by CMOC's native float option) and big-endian IEEE binary32 selected by `--mc6839`. The compiler records the encoding in each floating type, including nested types. Unknown formats and genuine unsupported double-precision layouts remain unavailable. CMOC 0.1.100 treats the C spelling `double` as an alias for `float`; that spelling does not add precision.
|
||||
|
||||
BASIC values retain their 32-bit significand and display up to 11 significant decimal digits; IEEE binary32 displays up to 9. Scientific notation handles very small/large values, and IEEE signed zero, subnormals, infinities and NaNs are recognized. The decimal display reflects the stored approximation: for example, CMOC's BASIC-format `0.1f` displays as `0.099999999977`. This is not evidence of a failed calculation. Inspection uses only the existing paused memory snapshot and never calls guest floating-point routines. Arithmetic in watches remains integer-only.
|
||||
|
||||
This decoder does not install additional float runtimes or bundle Motorola's ROM. The BASIC-backed runtime was qualified by running actual arithmetic on both guest CPUs. The native and MC6839 encodings were qualified from real compiler output and synthetic format-boundary tests; executing those optional math runtimes is outside this change.
|
||||
|
||||
Generated Debug Makefiles and the Hello World/Hello Disk templates preserve the frame pointer. Existing custom Makefiles can opt in with `-O0 -fno-omit-frame-pointer --intermediate` on C compilation. Rebuild with the bundled VCC Plus compiler. Locals require both unoptimized code and the preserved U frame; optimized locals are unavailable. Existing projects are never rewritten automatically. Use Project Settings to preview and explicitly regenerate a generated Makefile when desired.
|
||||
|
||||
The compiler extension is a maintained GPL patch applied to a build copy. Pinned upstream sources remain pristine. Versioned type/storage/scope comments and zero-byte labels are associated with the exact object, listing, linker map, source snapshots and executable. See [the patch contract](../../tools/toolchain/patches/README.md). Ordinary builds without the debug-frame option retain their prior compiler output.
|
||||
|
||||
## Remaining limits
|
||||
|
||||
- No editable C variables or semantic refactoring yet. Identifier completion and parameter hints are available as separate source-based editor assistance.
|
||||
|
||||
- Inline assembly and optimized-away or ambiguous C locations retain the native assembly fallback. Verified executable function entries are separately available for owned MCP playtests; they do not create C statement locations.
|
||||
|
||||
- Caller inspection is limited to verified frame chains. Unsupported links stop reconstruction; there is no speculative stack scanning.
|
||||
|
||||
- Source-line stepping does not imply statement-level precision.
|
||||
|
||||
- API-level documentation and online help remain a separate project.
|
||||
|
||||
## Validation
|
||||
|
||||
Verified November 3, 2026:
|
||||
|
||||
- Full `VCCCoreChecks` suite on Apple Silicon and Intel: **348 tests per architecture, 347 passed, one optional local BASIC-printer ROM test skipped, zero failures**.
|
||||
|
||||
- Universal Debug and Release application builds passed. No source warnings; Xcode emits its existing non-actionable AppIntents metadata notice because this app does not use AppIntents.
|
||||
|
||||
- Core regression coverage includes both guest processors, nested calls/returns, interrupts, one-line loops, permanent breakpoints, cancellation, stale program identity, bounded execution and 6309 TFM transfers.
|
||||
|
||||
- Actual compiled two-file programs verify Into/Over/Out, recursive frames, lexical shadowing, integer/array/pointer/structure values, mutation and I/O rejection, and invalidated executable bytes. Metadata coverage also keeps the incremental build workspace alive to exercise macOS temporary-path aliases.
|
||||
|
||||
- The native app built and ran a two-file C project to a source breakpoint, stepped into its helper, displayed `value = 2`, `local = 7`, `score = 5` and `values = [11, 22, 33]`, evaluated `values[1] + local` to **29**, and returned to the caller. The watch correctly reported `local` unavailable after leaving its scope. Keyboard entry remained in the watch field.
|
||||
|
||||
- Call-stack tests recover six real frames across two source files on both guest processors, including recursive arguments/locals and odd-byte frame alignment. They reject corrupt, unavailable, stale-code, unverified-prologue, optimized and interrupt boundaries and enforce a depth limit.
|
||||
|
||||
- The development-model regression verifies that selecting a caller changes its source navigation and values without changing PC, registers, cycles or memory. Polling preserves the selection; changed source hides stale frames and stepping returns inspection to frame zero.
|
||||
|
||||
- Native Call Stack review showed `recurse` × 4, `wrapper`, and `main`. Selecting `wrapper` displayed `value = 7`, `local = 12`, and `byteLocal = 42`. The recursive caller watch `n + local` evaluated to **12**; stepping advanced the actual leaf and restored frame zero, where the watch was **10**. The frame picker stayed open across refreshes, and controls remained usable at 900 × 650 points.
|
||||
|
||||
- Seven additional tree tests cover typed child paths, two-page arrays, nested structures/unions, explicit pointer traversal, unavailable siblings, null/I/O/cycle/depth errors, stale code, and owned snapshot buffers. The compiled two-file fixture checks current/caller values on both guest processors and proves registers, cycles and memory remain unchanged. The model regression also checks root paging, the visible-row limit and expansion identity across refresh/frame/step changes.
|
||||
|
||||
- Native tree review displayed `local.point = {x: -17, y: 21}` and the same object through `local.pointer`, then caller `bag.point = {x: -7, y: 11}`. Array paging advanced to `bag.samples[32] = 132`; stepping restored frame zero and made caller-only watches unavailable. The compact Watches pane now reserves space for its frame picker, entry field and scrollable values at 900 × 650 points.
|
||||
|
||||
- Eight new floating-point tests cover compiler encoding tags and constant bytes for BASIC/native/MC6839, missing/unknown/inconsistent metadata, precision boundaries, IEEE subnormals/special values, memory/I/O/stale-code rejection and explicit arithmetic rejection. The real two-file program performs BASIC-backed addition and multiplication on both guest processors, then verifies globals, parameters, locals, arrays, members, pointers and caller values without changing guest state.
|
||||
|
||||
- Native floating-point review displayed `input = -6.25`, `local = -5.75`, `globalResult = 3.75`, and caller `measurements.x = 1.25`. Expanded array values and direct pointer watches worked; stepping restored frame zero. The revised compiler is staged for both host architectures, and ordinary optimized object bytes remain unchanged.
|
||||
|
||||
- Pinned upstream source hashes remain unchanged; the compiler extension is reproducible from the committed patch. The normal emulator session and user media were not used for these checks.
|
||||
|
||||
These are captures of the running native application, not mockups:
|
||||
|
||||
Caller watch capture · Compact window capture
|
||||
|
||||
Compact variable-inspector layout
|
||||
|
||||
Expanded floating-point caller watch
|
||||
Reference in new issue
Block a user