mirror of
https://github.com/sehugg/8bitworkshop.git
synced 2026-11-21 09:25:43 +00:00
debug: show mutable urust globals in the debug tree
This commit is contained in:
1 parent
5e5ee9e4bb
commit
6cc2eef2dd
8 files changed
+184
-21
No files matched your search
@@ -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,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
@@ -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;
|
||||
}
|
||||
@@ -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.
|
||||
@@ -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 },
|
||||
};
|
||||
}
|
||||
|
||||
@@ -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 () {
|
||||
|
||||
@@ -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)');
|
||||
});
|
||||
});
|
||||
@@ -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 () {
|
||||
|
||||
Reference in new issue
Block a user