| name | nanovm-opcode-debugging |
| description | Diagnose NanoVM opcode, stack, value, and FFI failures with the optional NANO_VM_TRACE instrumentation. |
NanoVM Opcode Debugging
I keep opcode tracing disabled by default. Enable it only while diagnosing a
specific VM failure; tracing writes one record per retired instruction and can
produce substantial output.
Enable tracing
Build the normal VM, then set the environment variable before starting it:
NANO_VM_TRACE=1 ./bin/nano_vm failing.nvm
The VM reads NANO_VM_TRACE once during vm_init. The instruction dispatch
path checks only the cached boolean. Any non-empty value other than 0 enables
tracing. NANO_VM_TRACE=0 disables it.
To inspect a NanoLang source program through NanoVM:
NANO_VM_TRACE=1 ./bin/nano_virt program.nano --emit-nvm -o /tmp/program.nvm
NANO_VM_TRACE=1 ./bin/nano_vm /tmp/program.nvm
Read the trace
Each record includes the function index, function name, bytecode offset,
opcode, stack depth before and after execution, and the top stack values. Heap
values include their tag, address, length where applicable, and printable
contents. FFI records include the import, C symbol, argument count, return tag,
and marshaled result.
Use the first divergent record, not the last error message, as the starting
point. For string failures compare the PUSH_STR, FFI return, and equality
records. For stack failures compare the stack depth around the first operation
whose declared effect differs from the observed effect.
Tracing is diagnostic evidence, not a correctness proof. Reproduce the failure
with tracing disabled after the fix and run the relevant NanoVM, NanoVirt, and
benchmark quality gates.
Generated C diagnostics
Generated-C timing instrumentation is controlled once at process startup by
NANO_PROFILE. When an executable was built with --profile, use
NANO_PROFILE=1 to collect timing data or NANO_PROFILE=0 to turn the hooks
off without rebuilding. The generated hook checks only its cached boolean on
the hot path.
The generated-C toggle is separate from NANO_VM_TRACE. NANO_PROFILE only
controls timing and flamegraph data emitted by a --profile build; it does not
turn on opcode tracing in NanoVM. Run both variables when a failure crosses the
compiler and VM boundary.
