mirror of
https://github.com/sehugg/8bitworkshop.git
synced 2026-11-22 04:28:05 +00:00
249 lines
9.8 KiB
TypeScript
249 lines
9.8 KiB
TypeScript
// Source-level variables from a compiler's debug output, and the values they
|
|
// 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). 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).
|
|
// Globals (`static`, `const`, `reg!`) are always live, so urust lists them
|
|
// separately in `globalVariables`, with their type and home address.
|
|
|
|
import { hex } from "./util";
|
|
|
|
/** One source variable and where it lives for part of a function. */
|
|
export interface SourceVariable {
|
|
name: string;
|
|
/** the type as written in the source: `u8`, `bool`, `[u8; 4]` */
|
|
type: string;
|
|
/** its size in bytes */
|
|
size: number;
|
|
/** the function it belongs to */
|
|
function: string;
|
|
/** 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 */
|
|
line?: number | null;
|
|
col?: number | null;
|
|
/** `optimized out` when the compiler kept no storage for it */
|
|
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 {
|
|
let v: number;
|
|
if (typeof platform.readAddress === "function") v = platform.readAddress(addr);
|
|
else if (platform.machine && typeof platform.machine.read === "function") v = platform.machine.read(addr);
|
|
return typeof v === "number" ? v & 0xff : 0;
|
|
} catch (e) {
|
|
return 0;
|
|
}
|
|
}
|
|
|
|
/** The function symbol whose code contains `pc`, if the build knows one. */
|
|
export function functionAtPC(pc: number, symbolmap: { [name: string]: number },
|
|
symbolsizes?: { [name: string]: number }): string | null {
|
|
if (!symbolmap) return null;
|
|
let best: string | null = null;
|
|
let bestAddr = -1;
|
|
for (const name of Object.keys(symbolmap)) {
|
|
const addr = symbolmap[name];
|
|
const size = (symbolsizes && symbolsizes[name]) || 0;
|
|
if (typeof addr === "number" && size > 0 && pc >= addr && pc < addr + size && addr >= bestAddr) {
|
|
best = name;
|
|
bestAddr = addr;
|
|
}
|
|
}
|
|
return best;
|
|
}
|
|
|
|
/**
|
|
* The variables that are live at `pc`: the definition whose code range
|
|
* contains it, or, when the range is unknown, one belonging to the function
|
|
* at `pc`. A variable with an unknown range from another function is not
|
|
* shown, because its overlaid cell could name anything.
|
|
*/
|
|
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: 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);
|
|
return addr + v.addr;
|
|
}
|
|
|
|
function isIntegerType(type: string): boolean {
|
|
return /^[ui](8|16|32|64|size)$/.test(type);
|
|
}
|
|
|
|
function readInteger(bytes: Uint8Array, signed: boolean): number {
|
|
let n = 0;
|
|
for (let i = bytes.length - 1; i >= 0; i--) n = n * 256 + bytes[i];
|
|
if (signed) {
|
|
const sign = Math.pow(2, bytes.length * 8 - 1);
|
|
if (n >= sign) n -= sign * 2;
|
|
}
|
|
return n;
|
|
}
|
|
|
|
function formatBytes(bytes: Uint8Array): string {
|
|
return Array.from(bytes).map(b => hex(b, 2)).join(' ');
|
|
}
|
|
|
|
/**
|
|
* 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: 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
|
|
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(addr + i) & 0xff;
|
|
const type = (v.type || '').trim();
|
|
if (type === 'bool') return bytes[0] ? 'true' : 'false';
|
|
if (isIntegerType(type)) {
|
|
const val = readInteger(bytes, type[0] === 'i');
|
|
const raw = val < 0 ? Math.pow(2, size * 8) + val : val;
|
|
return `$${hex(raw, size * 2)} (${val})`;
|
|
}
|
|
if ((type === 'f32' || type === 'f64') && (size === 4 || size === 8)) {
|
|
const view = new DataView(bytes.buffer);
|
|
return String(type === 'f32' ? view.getFloat32(0, true) : view.getFloat64(0, true));
|
|
}
|
|
// a pointer is its home contents; dereferencing it here would be a guess
|
|
if (type.startsWith('&') || type.startsWith('*')) {
|
|
return `$${hex(readInteger(bytes, false) >>> 0, size * 2)}`;
|
|
}
|
|
if (bytes.length > 16) return bytes;
|
|
return formatBytes(bytes);
|
|
}
|
|
|
|
/** One live variable as `name: type = value` (for the editor's hover text). */
|
|
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) + '...';
|
|
return text;
|
|
}
|
|
|
|
/**
|
|
* The variables as a Debug Tree object, keyed `name:type` (the type without
|
|
* spaces, so a CLI path can name one).
|
|
*/
|
|
function variablesToTree(vars: (SourceVariable | GlobalVariable)[],
|
|
read: (addr: number) => number): { [name: string]: any } {
|
|
const tree: { [name: string]: any } = {};
|
|
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;
|
|
while (key in tree) key = `${v.name}#${n++}${type ? ':' + type : ''}`;
|
|
tree[key] = formatSourceValue(v, read);
|
|
}
|
|
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;
|
|
}
|