debug: show mutable urust globals in the debug tree

This commit is contained in:
Steven Hugg committed 2026-11-03 10:08:07 +01:00
1 parent 5e5ee9e4bb
commit 6cc2eef2dd
8 files changed
+184 -21

No files matched your search

+2
View File
@@ -25,6 +25,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.
- urust's mutable `static` and `reg!` globals show in a **Globals** node in the Debug Tree. The compiler's `--debug-out` now lists them with their type, home address and declaration, separate from the locals that have a live range; the same values appear when hovering a global symbol in the editor. Read-only globals (`mutable: false`, such as a `const` or non-`mut` static) stay out of the node, as do compiler-made cells without a source type; both remain in the symbol table.
- 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
+17 -3
View File
@@ -17,7 +17,7 @@ import { _MOS6502 } from "./cpu/MOS6502";
import { AcceptsBIOS, AcceptsJoyInput, AcceptsKeyInput, AcceptsPaddleInput, AcceptsROM, Bus, FrameBased, HasCPU, HasSerialIO, Probeable, RasterFrameBased, Resettable, SampledAudioSource, SavesInputState, SavesState, SerialIOInterface, VideoSource } from "./devices";
import { ProbeRecorder } from "./probe";
import { BaseWASMMachine } from "./wasmplatform";
import { formatSourceVariableLine, liveSourceVariables, readSourceByte, sourceVariablesOf, sourceVariableTree } from "./sourcevars";
import { formatSourceVariableLine, globalVariablesOf, globalVariableTree, liveSourceVariables, readSourceByte, sourceVariablesOf, sourceVariableTree, writableGlobalVariablesOf } from "./sourcevars";
///
@@ -258,10 +258,11 @@ export abstract class BasePlatform {
var o: any = {};
o.state = this.saveState();
if (this.debugSymbols?.debuginfo) {
// source variables have their own live view; listing the raw records
// here would only show where they are, not what they hold
// source variables and globals have their own value views; listing the
// raw records here would only show where they are, not what they hold
const info = { ...this.debugSymbols.debuginfo };
delete info['sourceVariables'];
delete info['globalVariables'];
if (Object.keys(info).length) o.debuginfo = info;
}
return o;
@@ -434,11 +435,22 @@ export abstract class BaseDebugPlatform extends BasePlatform {
this.debugSymbols.symbolsizes, a => readSourceByte(this, a)) || {};
}
/** The writable source-declared globals (`static`, `reg!`) and their
* values, keyed `name:type`; constants in ROM are left out. */
getGlobalVariables(): { [name: string]: any } {
const vars = writableGlobalVariablesOf(this.debugSymbols?.debuginfo);
if (!vars.length) return {};
return globalVariableTree(vars, a => readSourceByte(this, a)) || {};
}
getDebugTree(): {} {
const tree: any = super.getDebugTree();
if (sourceVariablesOf(this.debugSymbols?.debuginfo).length) {
tree.Locals = { $$: () => this.getSourceVariables() };
}
if (writableGlobalVariablesOf(this.debugSymbols?.debuginfo).length) {
tree.Globals = { $$: () => this.getGlobalVariables() };
}
return tree;
}
@@ -449,6 +461,8 @@ export abstract class BaseDebugPlatform extends BasePlatform {
this.debugSymbols.symbolsizes).find(v => v.name === sym);
if (v) return formatSourceVariableLine(v, a => readSourceByte(this, a));
}
const g = globalVariablesOf(this.debugSymbols?.debuginfo).find(g => g.name === sym);
if (g) return formatSourceVariableLine(g, a => readSourceByte(this, a));
return super.inspect(sym);
}
+78 -12
View File
@@ -9,6 +9,8 @@
//
// A debugger shows only the definitions whose range contains the PC, plus the
// ones the optimizer folded away (reported as "optimized out", never guessed).
// Globals (`static`, `const`, `reg!`) are always live, so urust lists them
// separately in `globalVariables`, with their type and home address.
import { hex } from "./util";
@@ -41,12 +43,60 @@ export interface SourceVariable {
location?: string;
}
/** A source-declared global: always live, so it has no function or range. */
export interface GlobalVariable {
name: string;
/** the type as written in the source: `u8`, `bool`, `[u8; 4]` */
type: string;
/** its size in bytes */
size: number;
/** the address of its home */
addr: number;
/** true when it lives in RAM, false for data in ROM */
ram?: boolean;
/** false when the program cannot write it (`const`, non-`mut` static) */
mutable?: boolean;
bank?: number | null;
/** the name of the ROM region at `bank`, when the target names one */
bankName?: string | null;
file?: string | null;
/** 1-based declaration position */
line?: number | null;
col?: number | null;
/** an array, whose elements can be read from `addr` */
expandable?: boolean;
}
/** The part of a variable that says where its value is. */
export interface VariableStorage {
type?: string;
size?: number;
addr?: number | null;
/** a zero-page pointer that `addr` is relative to */
baseAddr?: number | null;
}
/** The source variables a build put in `DebugSymbols.debuginfo`, if any. */
export function sourceVariablesOf(debuginfo: any): SourceVariable[] {
const vars = debuginfo && debuginfo.sourceVariables;
return Array.isArray(vars) ? vars : [];
}
/** The source-declared globals a build put in `DebugSymbols.debuginfo`, if any. */
export function globalVariablesOf(debuginfo: any): GlobalVariable[] {
const vars = debuginfo && debuginfo.globalVariables;
return Array.isArray(vars) ? vars : [];
}
/**
* The globals the program can write: `mutable` is false for a read-only
* global (`const`, non-`mut` static), which the debugger leaves out. Older
* output without the flag keeps the global rather than hiding all of them.
*/
export function writableGlobalVariablesOf(debuginfo: any): GlobalVariable[] {
return globalVariablesOf(debuginfo).filter(v => v.mutable !== false);
}
/** Read a byte through the platform's bus, as the debugger sees it. */
export function readSourceByte(platform: any, addr: number): number {
try {
@@ -97,7 +147,7 @@ export function liveSourceVariables(vars: SourceVariable[], pc: number,
* 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 {
export function sourceVariableAddress(v: VariableStorage, 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);
@@ -126,7 +176,7 @@ function formatBytes(bytes: Uint8Array): string {
* A source value as a tree leaf: a string for scalars, or a Uint8Array for an
* 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 {
export function formatSourceValue(v: VariableStorage, read: (addr: number) => number): string | Uint8Array {
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
@@ -153,7 +203,7 @@ export function formatSourceValue(v: SourceVariable, read: (addr: number) => num
}
/** One live variable as `name: type = value` (for the editor's hover text). */
export function formatSourceVariableLine(v: SourceVariable, read: (addr: number) => number): string {
export function formatSourceVariableLine(v: VariableStorage & { name: string }, read: (addr: number) => number): string {
const val = formatSourceValue(v, read);
let text = `${v.name}: ${v.type} = ${typeof val === 'string' ? val : formatBytes(val)}`;
if (text.length > 72) text = text.substring(0, 69) + '...';
@@ -161,17 +211,14 @@ export function formatSourceVariableLine(v: SourceVariable, read: (addr: number)
}
/**
* The live variables as a Debug Tree object, keyed `name:type` (the type
* without spaces, so a CLI path can name one). Null when none are live.
* The variables as a Debug Tree object, keyed `name:type` (the type without
* spaces, so a CLI path can name one).
*/
export function sourceVariableTree(vars: SourceVariable[], pc: number,
symbolmap: { [name: string]: number }, symbolsizes: { [name: string]: number } | undefined,
read: (addr: number) => number): { [name: string]: any } | null {
const live = liveSourceVariables(vars, pc, symbolmap, symbolsizes);
if (!live.length) return null;
function variablesToTree(vars: (SourceVariable | GlobalVariable)[],
read: (addr: number) => number): { [name: string]: any } {
const tree: { [name: string]: any } = {};
live.sort((a, b) => a.name.localeCompare(b.name) || a.type.localeCompare(b.type));
for (const v of live) {
const sorted = vars.slice().sort((a, b) => a.name.localeCompare(b.name) || a.type.localeCompare(b.type));
for (const v of sorted) {
const type = (v.type || '').replace(/\s+/g, '');
let key = type ? `${v.name}:${type}` : v.name;
let n = 2;
@@ -180,3 +227,22 @@ export function sourceVariableTree(vars: SourceVariable[], pc: number,
}
return tree;
}
/**
* The live variables as a Debug Tree object. Null when none are live.
*/
export function sourceVariableTree(vars: SourceVariable[], pc: number,
symbolmap: { [name: string]: number }, symbolsizes: { [name: string]: number } | undefined,
read: (addr: number) => number): { [name: string]: any } | null {
const live = liveSourceVariables(vars, pc, symbolmap, symbolsizes);
return live.length ? variablesToTree(live, read) : null;
}
/**
* The globals as a Debug Tree object. Unlike locals they have no live range,
* so every one is shown. Null when the build has none.
*/
export function globalVariableTree(vars: GlobalVariable[],
read: (addr: number) => number): { [name: string]: any } | null {
return vars.length ? variablesToTree(vars, read) : null;
}
+9 -1
View File
@@ -41,5 +41,13 @@ 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.
urust also lists the source-declared globals (`static`, `const`, `reg!`) in
its debug output, with their type and home address. They are always live, so
the tree shows a **Globals** node next to **Locals**. Only mutable globals are
listed: a read-only global (`mutable: false`, such as a `const` or a non-`mut`
static) stays out. Compiler-made cells (length cells, wide-array lanes) have
no source type and stay out too; they are still visible as symbols.
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.
and `8bws run ... -e "tree Locals"` or `tree Globals` prints the node from the
CLI.
+9 -3
View File
@@ -3,7 +3,7 @@
// (src/worker/tools/urust.ts); kept free of worker imports so tests can use it.
import { CodeListingMap, Segment, SourceLine, WorkerError } from "../../common/workertypes";
import { SourceVariable } from "../../common/sourcevars";
import { GlobalVariable, SourceVariable } from "../../common/sourcevars";
import { urustPlatformName } from "../../common/toolmeta";
export { urustPlatformName };
@@ -34,6 +34,8 @@ export interface UrustDebug {
lines: { addr: number, size: number, bank: number | null, file: string, line: number, col: number, endLine: number, endCol: number, func: string | null }[];
segments: { name: string, start: number, size: number, bank: number | null, type: 'rom' | 'ram' }[];
variables?: SourceVariable[];
/** source-declared data symbols (`static`, `const`, `reg!`); always live */
globalVariables?: GlobalVariable[];
}
export interface UrustDebugResult {
@@ -44,7 +46,7 @@ export interface UrustDebugResult {
/** source variables and the code ranges they are live over */
variables: SourceVariable[];
/** extra info for DebugSymbols.debuginfo (the debug tree reads it) */
debuginfo: { sourceVariables: SourceVariable[] };
debuginfo: { sourceVariables: SourceVariable[], globalVariables: GlobalVariable[] };
/** true if anything lives in a switchable bank: addresses there are
* ambiguous to the debugger, which has no bank in its line/symbol tables */
banked: boolean;
@@ -122,6 +124,10 @@ export function urustDebugToResult(dbg: UrustDebug, paths: string[]): UrustDebug
}));
if (dbg.segments.some(g => g.bank != null)) banked = true;
const variables = dbg.variables || [];
return { listings, symbolmap, symbolsizes, segments, variables, debuginfo: { sourceVariables: variables }, banked };
const globalVariables = dbg.globalVariables || [];
return {
listings, symbolmap, symbolsizes, segments, variables, banked,
debuginfo: { sourceVariables: variables, globalVariables },
};
}
+26
View File
@@ -502,6 +502,8 @@ describe('BaseDebugPlatform', function () {
getSP(): number { return 0x100; }
getPC(): number { return 0x1000; }
isStable(): boolean { return true; }
mem: { [addr: number]: number } = {};
readAddress(addr: number): number { return this.mem[addr] || 0; }
}
it('should manage breakpoints', function () {
@@ -546,6 +548,30 @@ describe('BaseDebugPlatform', function () {
platform.debugBreakState = { c: { PC: 0 } };
assert.ok(platform.wasBreakpointHit());
});
it('should show source locals and globals in the debug tree', function () {
const platform = new TestDebugPlatform();
platform.mem[0x20] = 0x78;
platform.mem[0x21] = 0x56;
platform.mem[0x30] = 0x34;
platform.mem[0x31] = 0x12;
platform.debugSymbols = new DebugSymbols({ main: 0x1000, hiscore: 0x20 }, {
extra: 'kept',
sourceVariables: [
{ name: 'score', type: 'u16', size: 2, function: 'main', addr: 0x30, range: [0x1000, 0x1010] },
],
globalVariables: [
{ name: 'hiscore', type: 'u16', size: 2, addr: 0x20, ram: true, mutable: true },
{ name: 'PALETTE', type: '[u8; 3]', size: 3, addr: 0x40, ram: false, mutable: false },
],
});
const tree: any = platform.getDebugTree();
assert.deepStrictEqual(tree.debuginfo, { extra: 'kept' });
assert.deepStrictEqual(tree.Locals.$$(), { 'score:u16': '$1234 (4660)' });
assert.deepStrictEqual(tree.Globals.$$(), { 'hiscore:u16': '$5678 (22136)' });
assert.strictEqual(platform.inspect('hiscore'), 'hiscore: u16 = $5678 (22136)');
});
});
describe('Base6502Platform', function () {
+32 -2
View File
@@ -1,8 +1,9 @@
import assert from "assert";
import { describe, it } from "mocha";
import {
SourceVariable, formatSourceValue, formatSourceVariableLine, functionAtPC,
liveSourceVariables, sourceVariableTree, sourceVariablesOf
GlobalVariable, SourceVariable, formatSourceValue, formatSourceVariableLine, functionAtPC,
globalVariablesOf, globalVariableTree, liveSourceVariables, sourceVariableTree, sourceVariablesOf,
writableGlobalVariablesOf
} from "../../src/common/sourcevars";
describe('Source variables', function () {
@@ -11,6 +12,8 @@ describe('Source variables', function () {
0x12: 0xff, // i8 delta = -1
0x13: 0x01, // bool running = true
0x14: 0x01, 0x15: 0x02, 0x16: 0x03, // [u8; 3]
0x30: 0x78, 0x31: 0x56, // global u16 SCORE = 0x5678
0x40: 0xaa, 0x41: 0xbb, 0x42: 0xcc, // global [u8; 3] PALETTE
};
const read = (a: number) => mem[a] || 0;
const symbolmap = { main: 0x8000, helper: 0x8100 };
@@ -27,10 +30,28 @@ describe('Source variables', function () {
{ name: 'other', type: 'u8', size: 1, function: 'helper', addr: 0x10, range: null },
];
const globals: GlobalVariable[] = [
{ name: 'SCORE', type: 'u16', size: 2, addr: 0x30, ram: true, mutable: true, file: 'main.rs', line: 12, col: 1 },
{ name: 'PALETTE', type: '[u8; 3]', size: 3, addr: 0x40, ram: false, mutable: false, file: 'main.rs', line: 16, col: 1, expandable: true },
];
it('reads the variables out of debuginfo', function () {
assert.deepStrictEqual(sourceVariablesOf({ sourceVariables: vars }), vars);
assert.deepStrictEqual(sourceVariablesOf({}), []);
assert.deepStrictEqual(sourceVariablesOf(null), []);
assert.deepStrictEqual(globalVariablesOf({ globalVariables: globals }), globals);
assert.deepStrictEqual(globalVariablesOf({}), []);
assert.deepStrictEqual(globalVariablesOf(null), []);
// mutable says whether the program can write it, regardless of where it lives
const readonlyRam = { ...globals[0], name: 'LOCKED', mutable: false };
const writableRom = { ...globals[1], name: 'ROMVAR', mutable: true };
assert.deepStrictEqual(
writableGlobalVariablesOf({ globalVariables: [globals[0], globals[1], readonlyRam, writableRom] }),
[globals[0], writableRom]);
assert.deepStrictEqual(writableGlobalVariablesOf({}), []);
// older output has no mutable flag; keep it rather than hide every global
const unmarked = { ...globals[1], ram: false, mutable: undefined };
assert.deepStrictEqual(writableGlobalVariablesOf({ globalVariables: [unmarked] }), [unmarked]);
});
it('finds the function whose code contains the PC', function () {
@@ -71,4 +92,13 @@ describe('Source variables', function () {
});
assert.strictEqual(sourceVariableTree(vars, 0x8200, symbolmap, symbolsizes, read), null);
});
it('shows every global, with no live range to filter on', function () {
assert.deepStrictEqual(globalVariableTree(globals, read), {
'PALETTE:[u8;3]': 'AA BB CC',
'SCORE:u16': '$5678 (22136)',
});
assert.strictEqual(globalVariableTree([], read), null);
assert.strictEqual(formatSourceVariableLine(globals[0], read), 'SCORE: u16 = $5678 (22136)');
});
});
+11
View File
@@ -157,6 +157,9 @@ describe('urust tool', function () {
variables: [
{ name: 'score', type: 'u16', size: 2, function: 'main', addr: 0x10, range: [0x8000, 0x8014], codeBank: null, file: 'main.rs', line: 1, col: 1 },
],
globalVariables: [
{ name: 'hiscore', type: 'u16', size: 2, addr: 0x20, ram: true, mutable: true, bank: null, bankName: null, file: 'main.rs', line: 8, col: 1, expandable: false },
],
};
it('converts debug info for the debugger and memory map', function () {
@@ -170,6 +173,14 @@ describe('urust tool', function () {
assert.strictEqual(r.banked, false);
assert.deepStrictEqual(r.variables, dbg.variables);
assert.deepStrictEqual(r.debuginfo.sourceVariables, dbg.variables);
assert.deepStrictEqual(r.debuginfo.globalVariables, dbg.globalVariables);
});
it('accepts debug output from a build without globals', function () {
const old = { ...dbg };
delete old.globalVariables;
const r = urustDebugToResult(old, ['main.rs']);
assert.deepStrictEqual(r.debuginfo.globalVariables, []);
});
it('flags banked output', function () {