oscar64: parse locals in debug info

This commit is contained in:
Steven Hugg committed 2026-10-30 16:06:08 +01:00
1 parent 95ea920415
commit a30ac8bf07
9 files changed
+334 -19

No files matched your search

+2
View File
@@ -20,6 +20,8 @@ See [extension/CHANGELOG.md](extension/CHANGELOG.md).
- urust programs show their source variables while debugging. The compiler's `--debug-out` JSON already gives each variable's home and the `[from, to)` code range it is live over; the Debug Tree now has a **Locals** node with the values at the current PC (only the live definition is shown, and variables the optimizer kept no storage for say `<optimized out>`). Selecting a variable in the editor shows the same value, and `8bws run ... -e "tree Locals"` prints it from the CLI. The build's debug info now reaches the VS Code debugger too, so its Machine scope has the same node.
- oscar64 C and C++ programs show their source variables too. The compiler's `-g` output includes a `.dbj` with function locals, their types, and the source lines where they are in scope; the build turns that into the same **Locals** node, mapping the scope lines to code ranges and reading stack/frame-relative variables through oscar64's zero-page pointers. Because the default `-O1` build usually keeps locals in registers, add `//#flag c -O0` to a program when you want to inspect them.
### Emulators
- A urust program that panics reaches its `__trap_spin` stub and runs forever, which looks like a working program. The emulator now notices ten frames on that symbol, reads the trapping `jsr`/`call` site from the stack, stops with `Program trapped at $xxxx`, and points the editor's PC arrow at that source line. This covers the 6502/Z80 machine platforms (devel, NES, C64, VIC-20, ZX, ...) and the CLI.
+1 -1
View File
@@ -424,7 +424,7 @@ export abstract class BaseDebugPlatform extends BasePlatform {
}
/** The source variables live at the current PC, from the build's debug
* info (urust), keyed `name:type`; empty when there are none. */
* info (urust, oscar64), keyed `name:type`; empty when there are none. */
getSourceVariables(): { [name: string]: any } {
const vars = sourceVariablesOf(this.debugSymbols?.debuginfo);
if (!vars.length) return {};
+28 -4
View File
@@ -2,7 +2,10 @@
// hold at a stop. urust writes them to its `--debug-out` JSON as a `variables`
// array: each definition records its home address and the [from, to) code
// range it is live over (cells are overlaid over time, so one address can hold
// different variables at different points of a function).
// different variables at different points of a function). oscar64's `.dbj`
// gives locals enter/leave source lines instead, which its parser turns into
// one or more code ranges; a stack- or frame-relative home is an offset from
// a zero-page pointer that is read at each stop.
//
// A debugger shows only the definitions whose range contains the PC, plus the
// ones the optimizer folded away (reported as "optimized out", never guessed).
@@ -18,10 +21,17 @@ export interface SourceVariable {
size: number;
/** the function it belongs to */
function: string;
/** the address of its home, null when it has no storage */
/** the address of its home, null when it has no storage. When `baseAddr`
* is set this is an offset from the pointer stored there. */
addr?: number | null;
/** the zero-page address of a pointer that `addr` is relative to, for
* variables on a call stack or in a frame */
baseAddr?: number | null;
/** the [from, to) code range it is live over, null when not known */
range?: [number, number] | null;
/** several disjoint live ranges, when the compiler only reports source
* line visibility (oscar64); `range` is the single-range urust form */
ranges?: [number, number][] | null;
codeBank?: number | null;
file?: string | null;
/** 1-based declaration position */
@@ -76,11 +86,24 @@ export function liveSourceVariables(vars: SourceVariable[], pc: number,
symbolmap: { [name: string]: number }, symbolsizes?: { [name: string]: number }): SourceVariable[] {
const fn = functionAtPC(pc, symbolmap, symbolsizes);
return vars.filter(v => {
if (v.ranges && v.ranges.length) return v.ranges.some(r => pc >= r[0] && pc < r[1]);
if (v.range) return pc >= v.range[0] && pc < v.range[1];
return fn != null && v.function === fn;
});
}
/**
* The address a variable's value is at right now. A stack- or frame-relative
* variable (`baseAddr` set) moves as the program calls functions, so the
* pointer has to be read at every stop instead of being baked into the var.
*/
export function sourceVariableAddress(v: SourceVariable, read: (addr: number) => number): number | null {
if (v.addr == null) return null;
if (v.baseAddr == null) return v.addr;
const addr = (read(v.baseAddr) & 0xff) | ((read(v.baseAddr + 1) & 0xff) << 8);
return addr + v.addr;
}
function isIntegerType(type: string): boolean {
return /^[ui](8|16|32|64|size)$/.test(type);
}
@@ -104,11 +127,12 @@ function formatBytes(bytes: Uint8Array): string {
* array or struct too big to show inline (the Debug Tree splits it into rows).
*/
export function formatSourceValue(v: SourceVariable, read: (addr: number) => number): string | Uint8Array {
if (v.addr == null) return '<optimized out>';
const addr = sourceVariableAddress(v, read);
if (addr == null) return '<optimized out>';
// big arrays are shown by their first rows; the tree can chunk the rest
const size = Math.max(1, Math.min(v.size || 1, 1024));
const bytes = new Uint8Array(size);
for (let i = 0; i < size; i++) bytes[i] = read(v.addr + i) & 0xff;
for (let i = 0; i < size; i++) bytes[i] = read(addr + i) & 0xff;
const type = (v.type || '').trim();
if (type === 'bool') return bytes[0] ? 'true' : 'false';
if (isIntegerType(type)) {
+15 -6
View File
@@ -25,12 +25,21 @@ while debugging.
## Source variables
A build can carry source-level variables with their home addresses and
live ranges. urust reports them in its `--debug-out` JSON, and the tree
then shows a **Locals** node: the variables whose code range contains the
current PC, with their values read from memory. A reassigned variable
appears once, at the definition that is live at the PC; cells overlaid by
other variables are not shown. Values the optimizer kept no storage for
appear as `<optimized out>`, never as a guess.
live ranges. urust reports them in its `--debug-out` JSON, and oscar64 in
the `.dbj` file it writes with `-g`; the tree then shows a **Locals** node:
the variables whose code range contains the current PC, with their values
read from memory. A reassigned variable appears once, at the definition
that is live at the PC; cells overlaid by other variables are not shown.
Values the optimizer kept no storage for appear as `<optimized out>`,
never as a guess.
oscar64 reports a local's visibility as the source lines where it is in
scope, not as code addresses, so its parser maps those lines through the
function's line table. Locals on the call stack or in a frame are read
through oscar64's zero-page stack or frame pointer at each stop. Its
default `-O1` build folds most locals into registers or temporaries, and
those cannot be shown; add `//#flag c -O0` to a program that you want to
inspect in the debugger.
Selecting a variable in the editor shows its live value in the same way,
and `8bws run ... -e "tree Locals"` prints the node from the CLI.
+8 -1
View File
@@ -5,7 +5,7 @@ import { spawn } from 'child_process';
import { CodeListing, CodeListingMap, Segment, WorkerBuildStep, WorkerErrorResult, WorkerFileUpdate, WorkerResult, isOutputResult } from '../../common/workertypes';
import { getFilenamePrefix, getRootBasePlatform, replaceAll } from '../../common/util';
import { parseObjDump } from './clang';
import { parseOscar64Listing, parseOscar64Lbl, parseOscar64Map } from '../tools/oscar64parse';
import { parseOscar64Dbj, parseOscar64Listing, parseOscar64Lbl, parseOscar64Map } from '../tools/oscar64parse';
import { BuildStep } from '../builder';
import { makeErrorMatcher } from '../listingutils';
@@ -157,6 +157,13 @@ async function oscar64ProcessOutput(step: WorkerBuildStep, outpath: string): Pro
text: txt,
};
}
// parse .dbj for source-level variables
try {
let txt = await fs.promises.readFile(prefix_path + '.dbj', { encoding: 'utf-8' });
debuginfo = parseOscar64Dbj(txt);
} catch (e) {
// -g writes it, but an old toolchain or a failed compile may not
}
return { output, listings, symbolmap, symbolsizes, segments, debuginfo };
}
+14 -1
View File
@@ -2,7 +2,7 @@ import { WASIFilesystem, WASIRunner } from "../../common/wasi/wasishim";
import { defineArgs, extraArgsFor } from "../../common/toolmeta";
import { BuildStep, BuildStepResult, gatherFiles, staleFiles, store, putWorkFile } from "../builder";
import { makeErrorMatcher } from "../listingutils";
import { parseOscar64Listing, parseOscar64Lbl, parseOscar64Map } from "./oscar64parse";
import { parseOscar64Dbj, parseOscar64Listing, parseOscar64Lbl, parseOscar64Map } from "./oscar64parse";
import { loadWASIFilesystemZip } from "../wasiutils";
import { loadWASMBinary } from "../wasmutils";
@@ -94,6 +94,7 @@ export async function compileOscar64(step: BuildStep): Promise<BuildStepResult>
// banked targets (NES) emit a Mesen label file (.mlb) instead of a VICE .lbl
let mlbout = getWasiFileAsString(wasi, prefix + ".mlb") || getWasiFileAsString(wasi, ".mlb");
let asmout = getWasiFileAsString(wasi, prefix + ".asm") || getWasiFileAsString(wasi, ".asm");
let dbjout = getWasiFileAsString(wasi, prefix + ".dbj") || getWasiFileAsString(wasi, ".dbj");
let segments = [];
let symbolmap = {};
let symbolsizes = {};
@@ -123,6 +124,17 @@ export async function compileOscar64(step: BuildStep): Promise<BuildStepResult>
text: asmout,
};
}
let debuginfo = {};
if (dbjout) {
putWorkFile(prefix + ".dbj", dbjout);
try {
debuginfo = parseOscar64Dbj(dbjout);
} catch (e) {
// the ROM and listing are still usable if the debug JSON is
// malformed; don't turn a successful build into a failure
console.log('could not parse oscar64 debug info', e);
}
}
return {
output,
errors,
@@ -130,6 +142,7 @@ export async function compileOscar64(step: BuildStep): Promise<BuildStepResult>
symbolmap,
symbolsizes,
segments,
debuginfo,
};
}
}
+167 -3
View File
@@ -1,9 +1,11 @@
// Parser for the oscar64 compiler's auxiliary output files.
// oscar64 writes a .map (memory map), .lbl (label file) and .asm
// (assembly listing with C source line markers) next to the output.
// oscar64 writes a .map (memory map), .lbl (label file), .asm (assembly
// listing with C source line markers) and, with -g, a .dbj (source-level
// debug JSON) next to the output.
// This module is shared by the browser/WASM tool (src/worker/tools/oscar64.ts)
// and the native server tool (src/worker/server/buildenv.ts).
import { SourceVariable } from "../../common/sourcevars";
import { CodeListingMap, Segment, SourceLine } from "../../common/workertypes";
export interface Oscar64ParseResult {
@@ -145,4 +147,166 @@ export function parseOscar64Listing(asmout: string, asmfn: string) {
}
}
return { srclines, asmlines };
}
}
// The .dbj is oscar64's source-level debug JSON (written by -g). Functions
// carry code-address ranges for their source lines and variables with a type
// id; a variable's home is either an absolute address or an offset from a
// zero-page pointer (`base`), because locals can live on the frame or stack.
// See "Complete debug information .dbj" in the oscar64 manual.
export interface Oscar64Type {
name?: string;
typeid: number;
size: number;
type?: string;
eid?: number;
members?: { name: string, offset: number, typeid: number }[];
}
export interface Oscar64Reference {
source: string;
line: number;
column?: number;
}
export interface Oscar64Variable {
name: string;
start: number;
end: number;
base?: number;
enter?: number;
leave?: number;
typeid: number;
references?: Oscar64Reference[];
}
export interface Oscar64Function {
name: string;
start: number;
end: number;
source?: string;
line?: number;
lines?: { start: number, end: number, source: string, line: number }[];
variables?: Oscar64Variable[];
}
export interface Oscar64Debug {
variables?: Oscar64Variable[];
functions?: Oscar64Function[];
types?: Oscar64Type[];
}
function oscar64Basename(path: string): string {
return path.split(/[\\/]/).pop() || path;
}
function sameOscar64Source(a: string | undefined, b: string | undefined): boolean {
if (!a || !b) return true;
return a === b || oscar64Basename(a) === oscar64Basename(b);
}
function oscar64TypeName(type: Oscar64Type | undefined, types: Map<number, Oscar64Type>,
seen = new Set<number>()): string {
if (!type) return 'u8';
if (type.name) return type.name;
if (seen.has(type.typeid)) return type.type || 'u8';
seen.add(type.typeid);
switch (type.type) {
case 'uint': return 'u' + Math.max(8, type.size * 8);
case 'int': return 'i' + Math.max(8, type.size * 8);
case 'bool': return 'bool';
case 'float': return type.size === 8 ? 'f64' : 'f32';
case 'ptr':
case 'ref':
return '&' + oscar64TypeName(type.eid == null ? undefined : types.get(type.eid), types, seen);
case 'array': {
const elem = type.eid == null ? undefined : types.get(type.eid);
const count = elem && elem.size > 0 ? Math.floor(type.size / elem.size) : type.size;
return `[${oscar64TypeName(elem, types, seen)}; ${count}]`;
}
case 'struct': return 'struct';
case 'union': return 'union';
case 'enum': return 'enum';
}
return type.type || 'u8';
}
function mergeOscar64Ranges(ranges: [number, number][]): [number, number][] {
ranges.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
const merged: [number, number][] = [];
for (const r of ranges) {
if (r[1] <= r[0]) continue;
const last = merged[merged.length - 1];
if (last && r[0] <= last[1]) last[1] = Math.max(last[1], r[1]);
else merged.push([r[0], r[1]]);
}
return merged;
}
/** The code ranges where oscar64 says a local is visible. The compiler
* records enter/leave source lines, not code addresses, so map those lines
* through the function's line table. */
function oscar64VariableRanges(fn: Oscar64Function, v: Oscar64Variable, source: string | undefined): [number, number][] | null {
if (v.enter == null || v.leave == null || !fn.lines) return null;
const enter = v.enter, leave = v.leave;
// Inlined helpers add their own source lines to the table; the variable's
// scope belongs to the function's source file, so ignore those.
const sameSource = fn.lines.filter(l => sameOscar64Source(l.source, source || fn.source));
const sourceLines = sameSource.length ? sameSource : fn.lines;
let minLine = Infinity, maxLine = -Infinity;
for (const l of sourceLines) {
if (l.line < minLine) minLine = l.line;
if (l.line > maxLine) maxLine = l.line;
}
// A variable declared before the first generated line and still visible on
// the last one lives in the frame for the whole function. Using the line
// ranges alone would lose it on branch tails and other instructions the
// compiler did not attribute to a source line.
if (minLine <= maxLine && enter <= minLine && leave >= maxLine) {
return [[fn.start, fn.end]];
}
const line = (l: { line: number, source: string }) =>
l.line >= enter && l.line <= leave && sameOscar64Source(l.source, source);
let lines = fn.lines.filter(line);
if (!lines.length) {
// the declaration may be in an included file whose path is spelled
// differently in the two tables; fall back to the line numbers alone
lines = fn.lines.filter(l => l.line >= enter && l.line <= leave);
}
const ranges = mergeOscar64Ranges(lines.map(l => [l.start, l.end] as [number, number]));
return ranges.length ? ranges : null;
}
/**
* Turn the .dbj into the source variables the Debug Tree shows. Only function
* locals and parameters are included: globals are live everywhere, but the
* Locals node is about the frame a stop is in.
*/
export function parseOscar64Dbj(dbjout: string): { sourceVariables: SourceVariable[] } {
const dbj = JSON.parse(dbjout) as Oscar64Debug;
const types = new Map<number, Oscar64Type>();
for (const t of dbj.types || []) types.set(t.typeid, t);
const sourceVariables: SourceVariable[] = [];
for (const fn of dbj.functions || []) {
for (const v of fn.variables || []) {
const type = types.get(v.typeid);
const ref = v.references && v.references[0];
const file = ref && ref.source ? oscar64Basename(ref.source) :
fn.source ? oscar64Basename(fn.source) : null;
const ranges = oscar64VariableRanges(fn, v, ref && ref.source);
sourceVariables.push({
name: v.name,
type: oscar64TypeName(type, types),
size: type && type.size ? type.size : Math.max(0, v.end - v.start),
function: fn.name,
addr: v.start,
baseAddr: v.base ?? null,
ranges,
file,
line: ref ? ref.line : v.enter ?? null,
col: ref && ref.column != null ? ref.column : null,
});
}
}
return { sourceVariables };
}
+91
View File
@@ -0,0 +1,91 @@
import assert from "assert";
import { describe, it } from "mocha";
import {
formatSourceValue, liveSourceVariables, sourceVariableAddress, sourceVariableTree, sourceVariablesOf
} from "../../src/common/sourcevars";
import { parseOscar64Dbj } from "../../src/worker/tools/oscar64parse";
describe('Oscar64 debug info', function () {
const dbj = {
types: [
{ name: '', typeid: 0, size: 1, type: 'uint' },
{ name: '', typeid: 1, size: 2, type: 'int' },
{ name: '', typeid: 2, size: 1, type: 'bool' },
{ name: '', typeid: 3, size: 4, type: 'array', eid: 0 },
{ name: '', typeid: 4, size: 2, type: 'ptr', eid: 0 },
{ name: 'point', typeid: 5, size: 4, type: 'struct' },
],
functions: [{
name: 'main', start: 0x8000, end: 0x8020, source: '/proj/main.c', line: 1,
lines: [
{ start: 0x8000, end: 0x8004, source: '/proj/main.c', line: 10 },
{ start: 0x8004, end: 0x8008, source: '/proj/main.c', line: 12 },
{ start: 0x8010, end: 0x8018, source: '/proj/main.c', line: 14 },
{ start: 0x8018, end: 0x8020, source: '/proj/main.c', line: 18 },
],
variables: [
{ name: 'score', start: 0x9000, end: 0x9002, enter: 10, leave: 14, typeid: 1,
references: [{ source: '/proj/main.c', line: 10, column: 5 }] },
{ name: 'i', start: 2, end: 3, base: 0x23, enter: 12, leave: 14, typeid: 0,
references: [{ source: '/proj/main.c', line: 12, column: 7 }] },
{ name: 'arr', start: 0x9000, end: 0x9004, enter: 10, leave: 18, typeid: 3,
references: [{ source: '/proj/main.c', line: 10, column: 11 }] },
{ name: 'p', start: 0x9004, end: 0x9006, enter: 10, leave: 18, typeid: 4,
references: [{ source: '/proj/main.c', line: 10, column: 15 }] },
{ name: 'pt', start: 0x9006, end: 0x900a, enter: 10, leave: 18, typeid: 5,
references: [{ source: '/proj/main.c', line: 10, column: 18 }] },
{ name: 'n', start: 0x0d, end: 0x0e, typeid: 0,
references: [{ source: '/proj/main.c', line: 1, column: 13 }] },
],
}],
};
const parsed = parseOscar64Dbj(JSON.stringify(dbj));
const vars = parsed.sourceVariables;
const byName = (name: string) => vars.find(v => v.name === name);
it('maps types and stack-relative homes', function () {
assert.deepStrictEqual(sourceVariablesOf({ sourceVariables: vars }), vars);
assert.strictEqual(byName('score').type, 'i16');
assert.strictEqual(byName('arr').type, '[u8; 4]');
assert.strictEqual(byName('p').type, '&u8');
assert.strictEqual(byName('pt').type, 'point');
assert.strictEqual(byName('i').baseAddr, 0x23);
assert.strictEqual(byName('i').addr, 2);
assert.strictEqual(byName('score').file, 'main.c');
assert.strictEqual(byName('score').line, 10);
assert.strictEqual(byName('score').col, 5);
});
it('turns enter/leave lines into code ranges', function () {
assert.deepStrictEqual(byName('score').ranges, [[0x8000, 0x8008], [0x8010, 0x8018]]);
// a variable visible on the first and last generated line is live over
// the whole function, including branch tails with no line entry
assert.deepStrictEqual(byName('arr').ranges, [[0x8000, 0x8020]]);
assert.deepStrictEqual(byName('i').ranges, [[0x8004, 0x8008], [0x8010, 0x8018]]);
assert.strictEqual(byName('n').ranges, null);
});
it('shows only the variables live at the PC', function () {
const atI = liveSourceVariables(vars, 0x8005, { main: 0x8000 }, { main: 0x20 }).map(v => v.name);
assert.deepStrictEqual(atI, ['score', 'i', 'arr', 'p', 'pt', 'n']);
const atScore = liveSourceVariables(vars, 0x8019, { main: 0x8000 }, { main: 0x20 }).map(v => v.name);
assert.deepStrictEqual(atScore, ['arr', 'p', 'pt', 'n']);
// a parameter without enter/leave falls back to the current function
assert.ok(liveSourceVariables(vars, 0x8019, { main: 0x8000 }, { main: 0x20 }).some(v => v.name == 'n'));
});
it('reads values through the stack pointer', function () {
const mem: { [addr: number]: number } = { 0x9002: 0x34, 0x9003: 0x12 };
const read = (addr: number) => {
if (addr == 0x23) return 0x00;
if (addr == 0x24) return 0x90;
return mem[addr] || 0;
};
assert.strictEqual(sourceVariableAddress(byName('i'), read), 0x9002);
assert.strictEqual(formatSourceValue(byName('i'), read), '$34 (52)');
const tree = sourceVariableTree(vars, 0x8005, { main: 0x8000 }, { main: 0x20 }, read);
assert.strictEqual(tree['i:u8'], '$34 (52)');
assert.strictEqual(tree['score:i16'], '$0000 (0)');
});
});
+8 -3
View File
@@ -2,7 +2,7 @@ import assert from "assert";
import { WASIRunner, WASIMemoryFilesystem, WASIErrors, FDOpenFlags, normalizeWASIPath } from "../../src/common/wasi/wasishim";
import * as fs from "fs";
import { loadWASIFilesystemZip, unzipWASIFilesystem } from "../../src/worker/wasiutils";
import { parseOscar64Listing, parseOscar64Lbl, parseOscar64Map } from "../../src/worker/tools/oscar64parse";
import { parseOscar64Dbj, parseOscar64Listing, parseOscar64Lbl, parseOscar64Map } from "../../src/worker/tools/oscar64parse";
async function loadWASM(filename: string) {
const wasmdata = fs.readFileSync(`./src/worker/wasm/${filename}.wasm`);
@@ -128,10 +128,10 @@ describe('test WASI oscar64', function () {
const zipdata = fs.readFileSync(`./src/worker/fs/oscar64-fs.zip`);
let oscar64_fs = await unzipWASIFilesystem(zipdata, "./");
shim.fs.setParent(oscar64_fs);
shim.fs.putFile("./main.c", `#include <stdio.h>\nint main() { printf("FOO"); return 0; }`);
shim.fs.putFile("./main.c", `#include <stdio.h>\nint main() { unsigned char x = 42; printf("FOO%d", x); return 0; }`);
shim.addPreopenDirectory("include");
shim.addPreopenDirectory(".");
shim.setArgs(["oscar64", '-v', '-gp', '-ii=include', '-o=./foo.prg', 'main.c']);
shim.setArgs(["oscar64", '-v', '-O0', '-gp', '-ii=include', '-o=./foo.prg', 'main.c']);
let errno = shim.run();
const stdout = shim.fds[1].getBytesAsString();
const stderr = shim.fds[2].getBytesAsString();
@@ -142,6 +142,7 @@ describe('test WASI oscar64', function () {
assert.ok(shim.fs.getFile("./foo.map"), "foo.map not written");
assert.ok(shim.fs.getFile("./foo.lbl"), "foo.lbl not written");
assert.ok(shim.fs.getFile("./foo.asm"), "foo.asm not written");
assert.ok(shim.fs.getFile("./foo.dbj"), "foo.dbj not written");
// parse the map file for segments and symbols
let mapout = shim.fs.getFile("./foo.map").getBytesAsString();
let parsed = parseOscar64Map(mapout);
@@ -157,6 +158,10 @@ describe('test WASI oscar64', function () {
assert.ok(listing.asmlines.length > 0);
assert.ok(listing.srclines.length > 0);
assert.ok(listing.srclines[0].offset > 0);
// parse the source-level debug JSON
let dbjout = shim.fs.getFile("./foo.dbj").getBytesAsString();
let dbj = parseOscar64Dbj(dbjout);
assert.ok(dbj.sourceVariables.some(v => v.name == 'x'), JSON.stringify(dbj.sourceVariables));
});
});