diff --git a/CHANGELOG.md b/CHANGELOG.md index f3851eb9..e7df3c55 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 ``). 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 diff --git a/src/common/baseplatform.ts b/src/common/baseplatform.ts index c58d0bfa..df62c8fc 100644 --- a/src/common/baseplatform.ts +++ b/src/common/baseplatform.ts @@ -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); } diff --git a/src/common/sourcevars.ts b/src/common/sourcevars.ts index fb6cccc5..ba65aa35 100644 --- a/src/common/sourcevars.ts +++ b/src/common/sourcevars.ts @@ -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 ''; // 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; +} diff --git a/src/docs/debugtree.md b/src/docs/debugtree.md index c4bcb6c4..3962f869 100644 --- a/src/docs/debugtree.md +++ b/src/docs/debugtree.md @@ -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. diff --git a/src/worker/tools/urustparse.ts b/src/worker/tools/urustparse.ts index e12a9c4d..8bf2ae40 100644 --- a/src/worker/tools/urustparse.ts +++ b/src/worker/tools/urustparse.ts @@ -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 }, + }; } diff --git a/test/unit/testbaseplatform.ts b/test/unit/testbaseplatform.ts index e6fd66bd..bb8458a5 100644 --- a/test/unit/testbaseplatform.ts +++ b/test/unit/testbaseplatform.ts @@ -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 () { diff --git a/test/unit/testsourcevars.ts b/test/unit/testsourcevars.ts index aebda0b2..43a9e968 100644 --- a/test/unit/testsourcevars.ts +++ b/test/unit/testsourcevars.ts @@ -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)'); + }); }); diff --git a/test/unit/testurust.ts b/test/unit/testurust.ts index 5542b172..672af185 100644 --- a/test/unit/testurust.ts +++ b/test/unit/testurust.ts @@ -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 () {