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,137 @@
|
||||
# Verified custom-Make debugging through MCP
|
||||
|
||||
> 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.
|
||||
|
||||
## Read the build evidence first
|
||||
|
||||
Every completed executable build now reports `source_debugging` in `get_build`,
|
||||
including ordinary custom-Make builds without a banked manifest. Successful
|
||||
compilation and verified debugging are separate results:
|
||||
|
||||
- `verified` means the executable/source map and compiler type metadata passed
|
||||
verification. `source_only` means executable evidence passed but typed C
|
||||
metadata is unavailable; `reason` explains why. `unavailable` identifies an
|
||||
executable, map, object, listing or source verification failure.
|
||||
|
||||
- `c_line_stops` lists actual compiler-mapped statements, with shared source path,
|
||||
line, logical address and declared bank identity where applicable. `functions`
|
||||
names only unique functions with a verified C statement inside their body.
|
||||
|
||||
- `function_entries` names verified executable entries, including supported
|
||||
assembly/prologue entries. An entry stop does not establish a C statement or
|
||||
stack-frame layout. `function_details` distinguishes a declaration from an
|
||||
available C stop and explains missing C statements.
|
||||
|
||||
- `globals` lists shared file/global declarations, their verified type/storage
|
||||
and module identity. These are declarations, not guessed runtime values.
|
||||
Unsupported storage/type layouts are explicitly unavailable.
|
||||
|
||||
- Binary/link-map hashes, load entry, module page assignments and
|
||||
`owned_stop_evidence` identify the exact build. Every catalog includes total
|
||||
and truncation fields and is bounded by its encoded size.
|
||||
|
||||
Ordinary flat custom Makefiles must retain the matching binary, linker `.map`,
|
||||
linked project `.o`, assembler `.lst` and source snapshots. Keep CMOC
|
||||
`--intermediate` enabled when compiling and linking. The bundled compiler emits
|
||||
its `VCCDBG1` type/storage records; retaining compiler-generated `.s` permits
|
||||
verification of records too long for an assembler listing row. A useful Debug
|
||||
compile uses `-O0 -fno-omit-frame-pointer`; optimized builds can legitimately
|
||||
have fewer C statements or unavailable locals. No user Makefile is rewritten
|
||||
merely to provide debugger metadata.
|
||||
|
||||
For example, a normal recipe can compile and link with:
|
||||
|
||||
```make
|
||||
obj/main.o: main.c
|
||||
@mkdir -p obj
|
||||
"$(CMOC)" --coco -O0 -fno-omit-frame-pointer --intermediate --intdir=obj -c -o $@ $<
|
||||
program.bin: obj/main.o
|
||||
"$(CMOC)" --coco --intermediate --org=2800 -o $@ obj/main.o
|
||||
```
|
||||
|
||||
This fragment only illustrates retained evidence; disk construction and launch
|
||||
commands remain the project's declared recipe. Packed, relocated or bank-switched
|
||||
programs must supply the public version-1 [banked debug manifest](MCP_BANKED_PLAYTEST.md).
|
||||
Its hashes, unpacked images, section ownership and actual physical page identities
|
||||
are required. It never falls back to a flat interpretation after verification
|
||||
fails.
|
||||
|
||||
## Stop and inspect the owned guest
|
||||
|
||||
With an approved disposable-playtest connection, build the current revision and
|
||||
use an advertised `functions` name as `stop_function` in `start_playtest`, or
|
||||
`function_entries` with `stop_kind: "function_entry"`. Poll asynchronous startup
|
||||
with `get_run`. Later `playtest_debug` with `action: "stop_at"` accepts the same
|
||||
verified name/stop kind. Neither call accepts an arbitrary stop address.
|
||||
|
||||
Ordinary flat builds use the existing native guarded-breakpoint path. Complete
|
||||
object-relocated executable bytes must match before the first named stop can
|
||||
attach; the actual worker's mapping fingerprint is retained. No assumed stock
|
||||
physical pages are substituted. Continuing can remove selected stops while
|
||||
retaining the exact same code/mapping identity. A changed mapping or executable
|
||||
byte makes the old attachment unavailable. An empty inspection selection alone
|
||||
cannot establish an initial attachment.
|
||||
|
||||
At the verified paused state, `get_debug_snapshot` reports registers, honest
|
||||
stop kind, source/function entry where known, actual physical pages/mapping
|
||||
fingerprint and bounded `globals` values from the same safe memory capture.
|
||||
A global outside the readable stopped mapping has an `unavailable` reason.
|
||||
Unshared declarations are omitted. C frame locals remain unavailable at owned
|
||||
entry/instruction stops; no frame is inferred from U or a guessed prologue.
|
||||
Locally configured watches retain their existing rules.
|
||||
|
||||
`read_debug_memory` accepts only ranges advertised by that immutable snapshot,
|
||||
up to 256 bytes. Resume, input, step, restart, source/artifact changes and
|
||||
connection revocation invalidate the applicable observation. Inspection performs
|
||||
no guest expressions, register writes, memory writes or side-effecting I/O reads.
|
||||
A mismatched binary, object relocation, source identity or bank cannot produce a
|
||||
verified snapshot merely because a requested function name exists.
|
||||
|
||||
For diagnostics and paged compiler output, use `get_build` and `get_build_log`;
|
||||
those receipts are independent of whether source debugging is available.
|
||||
|
||||
## Diagnose the selected build
|
||||
|
||||
A newly exported toolset 7 C grant has `projectDiagnostics: true` and advertises
|
||||
`get_build_log`. Build receipts retain action, configuration, revision and final
|
||||
status. Both successful and failed builds report structured `diagnostics`, with
|
||||
severity, source path/line/column when shared and known, stage, message and raw
|
||||
diagnostic text. `first_error` selects an error even when warnings precede it or
|
||||
fill the visible diagnostic list. `diagnostics_total` and
|
||||
`diagnostics_truncated` explain bounded previews.
|
||||
|
||||
`exit_code` is the actual Make process status when one exists; it is null for a
|
||||
preparation failure. A post-Make validation failure can correctly report exit 0
|
||||
and `failure_kind: "validation"`: the command succeeded but its output was
|
||||
unacceptable. `failure_stage` distinguishes compiler, assembler, linker, Make,
|
||||
preparation or validation when the evidence identifies it. `invocation` records
|
||||
the top-level command. `failing_command` is available only when a recognized
|
||||
echoed command precedes the first retained error; hidden recipe commands remain
|
||||
unavailable. Raw diagnostics stay in the redacted combined log, including lines
|
||||
without source locations. Separate stdout/stderr are not fabricated.
|
||||
|
||||
```json
|
||||
{"name":"get_build_log","arguments":{"build_id":"<build>","offset":0,"limit":16384}}
|
||||
```
|
||||
|
||||
Follow `next_offset` until null to retrieve every retained UTF-8 byte. Offsets
|
||||
refer to the frozen redacted log; they never read a host file or rerun a tool.
|
||||
Each page accepts 1–32,768 bytes, preserving complete Unicode scalars (a scalar
|
||||
can exceed an unusually small requested limit). The SHA-256 covers the complete
|
||||
retained log. Only this connection's build IDs are accepted.
|
||||
|
||||
The process log retains at most 512 KiB, preserving its beginning and end when
|
||||
clipped; the normal receipt shows a smaller preview. `process_output_bytes`,
|
||||
`process_output_truncated`, `log_retained_bytes`, `log_truncated` and
|
||||
`first_error_scope` distinguish complete evidence from a retained subset.
|
||||
Pagination recovers the complete retained log, not bytes already dropped at the
|
||||
process-output limit. The interface reports that limitation explicitly.
|
||||
|
||||
## Bounded owned call context
|
||||
|
||||
Fresh toolset-10 C playtest grants add `get_call_context(run_id, snapshot_id)`.
|
||||
It exposes only a fixed 64-byte RAM window at actual S from the same immutable
|
||||
verified pause. Proven normal CMOC calls can include caller and integer argument
|
||||
locations; optimized, indirect or unknown frames retain explicit unavailability.
|
||||
It does not enlarge ordinary memory-read ranges or shared-run access. See the
|
||||
[call-context contract and qualification](MCP_CALL_CONTEXT.md).
|
||||
Reference in new issue
Block a user