@specy/x86 2.4.0 → 2.6.0

package/dist/index.mjs

@@ -1112,6 +1112,17 @@ function emptyFpuStateBlock() {
 }
 //#endregion
 //#region src/blink-runtime.ts
+/** The machine's page size: a page is contiguous in the host heap, the next page need not be. */
+const BLINK_PAGE_SIZE = 4096;
+/**
+* The shadow-memory range blink keeps for its own bookkeeping, which the
+* memory bridge refuses to read. Kept in step with `IsShadow` in
+* `blink/blinkenlib.c`, so the fast read path refuses exactly what the bridge
+* refuses.
+*/
+function isShadowAddress(address) {
+	return address >= 2147450880n && address < 17594333528064n;
+}
 const SIGNALS = {
 	SIGTRAP: 5,
 	SIGXCPU: 24
@@ -1191,6 +1202,8 @@ const SIGNAL_INFO = {
 };
 var BlinkRuntime = class BlinkRuntime {
 	module;
+	/** Cached view over the wasm heap, for `spyMemoryBytes`; growth invalidates it. */
+	heapView = null;
 	mode;
 	state = "NOT_READY";
 	stopReason = null;
@@ -1485,6 +1498,47 @@ var BlinkRuntime = class BlinkRuntime {
 		if (!result.ok) throw new Error(`${result.error}: 0x${address.toString(16)}`);
 		return Uint8Array.from(result.bytes);
 	}
+	/**
+	* The bytes at `address` read straight out of the machine's own pages,
+	* or null when the machine cannot answer for the whole range.
+	*
+	* `blinkenlibReadMemoryBytes` looks each byte up and then builds a
+	* JavaScript array inside the bridge, which costs about four times as much
+	* as this does; recording a step reads only addresses the step just wrote,
+	* so it takes this path and falls back to the bridge whenever this one
+	* declines. The two agree byte for byte because they do the same lookup:
+	* `blinkenlib_spy_address` IS the lookup `blinkenlib_read_memory_byte`
+	* makes, and the shadow-memory range the bridge refuses is refused here
+	* too. A page is contiguous in the host heap and the next page need not
+	* be, so the read stops at every page boundary and looks the next one up.
+	*/
+	spyMemoryBytes(address, length) {
+		const spy = this.module._blinkenlib_spy_address;
+		if (!spy || !this.module.wasmExports?.memory) return null;
+		if (!Number.isSafeInteger(length) || length <= 0) return null;
+		if (this.state === "NOT_READY" || this.state === "READY") return null;
+		const bytes = new Uint8Array(length);
+		let offset = 0;
+		while (offset < length) {
+			const target = address + BigInt(offset);
+			if (isShadowAddress(target)) return null;
+			const pointer = spy.call(this.module, target) >>> 0;
+			if (pointer === 0) return null;
+			const take = Math.min(BLINK_PAGE_SIZE - Number(target & 4095n), length - offset);
+			bytes.set(this.heapBytes().subarray(pointer, pointer + take), offset);
+			offset += take;
+		}
+		return bytes;
+	}
+	/**
+	* A view over the wasm heap, rebuilt only when growth has replaced the
+	* buffer the last one was taken from.
+	*/
+	heapBytes() {
+		const buffer = this.module.wasmExports.memory.buffer;
+		if (!this.heapView || this.heapView.buffer !== buffer) this.heapView = new Uint8Array(buffer);
+		return this.heapView;
+	}
 	writeMemoryBytes(address, data) {
 		const result = this.module.blinkenlibWriteMemoryBytes(address, data);
 		if (!result.ok) throw new Error(`${result.error}: 0x${address.toString(16)}`);
@@ -1874,6 +1928,14 @@ var BaseEmulator = class {
 };
 //#endregion
 //#region src/x86-emulator-utils.ts
+/**
+* Whether a native memory write is one a history entry can report in full:
+* the machine captured every byte it replaced. A write that overflowed the
+* native journal keeps its `Other` shape instead and stays out of undo.
+*/
+function isRecordableWrite(write) {
+	return !write.truncated && write.old.length === write.size;
+}
 var CircularHistory = class {
 	capacity;
 	entries;
@@ -1965,12 +2027,14 @@ function cloneCallStack(stack) {
 }
 function stripPrivateHistory(entry) {
 	return {
+		kind: entry.kind,
 		mutations: entry.mutations,
 		pc: entry.pc,
 		old_ccr: entry.old_ccr,
 		new_ccr: entry.new_ccr,
 		line: entry.line,
-		file: entry.file
+		file: entry.file,
+		...entry.writes ? { writes: entry.writes } : {}
 	};
 }
 function toHistoryPc(address) {
@@ -2003,6 +2067,9 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 	lastSourceCode = "";
 	history = new CircularHistory(0);
 	callStack = [];
+	openPoke = null;
+	/** True while an instruction is running, so a Poke cannot open on top of one. */
+	executing = false;
 	constructor(runtime) {
 		super({
 			systemSize: 8,
@@ -2086,8 +2153,15 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 		this.runtime.loadElf(data);
 	}
 	async runUntilBlocked() {
+		this.assertNoOpenPoke("run");
 		if (this.isTracingEnabled()) return this.run();
-		await this.runtime.runUntilBlocked();
+		const wasExecuting = this.executing;
+		this.executing = true;
+		try {
+			await this.runtime.runUntilBlocked();
+		} finally {
+			this.executing = wasExecuting;
+		}
 		return this.getStatus();
 	}
 	provideInput(line) {
@@ -2172,11 +2246,115 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 		const entry = this.history.peekNewest();
 		return Boolean(entry?.reversible);
 	}
+	/**
+	* Opens a Poke: a register or memory value the HOST changes between two
+	* instructions, recorded as one step of this history and undone like an
+	* instruction.
+	*
+	* Everything `setRegisterValue`, `setFpuState` and `writeMemoryBytes`
+	* change until `endPoke()` becomes one entry, however many calls it took.
+	* Outside a transaction those setters stay exactly as direct as they were:
+	* a Testcase presetting its starting values records nothing.
+	*
+	* Throws when a poke is already open, and when an instruction is running -
+	* a step inside a transaction would hand the program's own writes to the
+	* poke, and undoing it would then revert the instruction too.
+	*/
+	beginPoke() {
+		if (this.openPoke) throw new Error("A poke is already open: end it before beginning another");
+		if (this.executing) throw new Error("Cannot begin a poke while an instruction is executing");
+		const snapshot = this.runtime.getRegisterSnapshot();
+		this.openPoke = {
+			registersBefore: cloneRegisterValues(snapshot),
+			flagsBefore: snapshot.flags,
+			fpuBefore: this.runtime.getFpuStateRaw(),
+			callStackBefore: cloneCallStack(this.callStack),
+			memoryWrites: []
+		};
+	}
+	/**
+	* Closes the open Poke and records it, returning whether anything was
+	* recorded: a transaction that changed no value - because it wrote
+	* nothing, or wrote the value that was already there - records nothing and
+	* answers false, so the caller never shows an Undo step that reverts
+	* nothing.
+	*
+	* Nothing here resumes the machine: the poke changed state, not why the
+	* program stopped, and the next step resumes a paused machine itself.
+	*
+	* A poke takes one slot of the history, exactly as an instruction does, so
+	* with `initialize(0)` it applies and answers true while the zero-capacity
+	* history keeps it no more than it keeps an instruction.
+	*
+	* Throws when no poke is open.
+	*/
+	endPoke() {
+		const poke = this.openPoke;
+		if (!poke) throw new Error("No poke is open: begin one before ending it");
+		this.openPoke = null;
+		const after = this.runtime.getRegisterSnapshot();
+		const registersAfter = cloneRegisterValues(after);
+		const mutations = [];
+		const writes = [];
+		for (const register of X86_REGISTER_NAMES) {
+			const old = poke.registersBefore[register];
+			const value = registersAfter[register];
+			if (old === value) continue;
+			mutations.push({
+				type: "WriteRegister",
+				value: {
+					register,
+					old,
+					new: value,
+					size: 8
+				}
+			});
+			writes.push({
+				type: "register",
+				name: register,
+				old,
+				new: value
+			});
+		}
+		this.recordFpuMutations(poke.fpuBefore, this.runtime.getFpuStateRaw(), mutations, writes);
+		const memoryWrites = this.recordPokeMemoryMutations(poke.memoryWrites, mutations, writes);
+		if (writes.length === 0) return false;
+		const location = this.runtime.getSourceLocationForAddress(after.pc);
+		const entry = {
+			kind: "poke",
+			mutations,
+			writes,
+			pc: toHistoryPc(after.pc),
+			old_ccr: { bits: poke.flagsBefore },
+			new_ccr: { bits: after.flags },
+			line: location?.line ?? -1,
+			file: location?.path,
+			registersBefore: poke.registersBefore,
+			flagsBefore: poke.flagsBefore,
+			fpuBefore: poke.fpuBefore,
+			callStackBefore: cloneCallStack(this.callStack),
+			memoryWrites,
+			reversible: true
+		};
+		this.history.push(entry);
+		return true;
+	}
+	/** True between `beginPoke()` and `endPoke()`. */
+	isPokeOpen() {
+		return this.openPoke !== null;
+	}
 	async step() {
-		if (this.isTracingEnabled()) this.captureStep();
-		else {
-			this.prepareOneInstructionRun();
-			this.runtime.step();
+		this.assertNoOpenPoke("step");
+		const wasExecuting = this.executing;
+		this.executing = true;
+		try {
+			if (this.isTracingEnabled()) this.captureStep();
+			else {
+				this.prepareOneInstructionRun();
+				this.runtime.step();
+			}
+		} finally {
+			this.executing = wasExecuting;
 		}
 		return { terminated: this.hasTerminated() };
 	}
@@ -2186,8 +2364,23 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 		if (this.runtime.state === "PROGRAM_STOPPED") return 0;
 		return 1;
 	}
+	/**
+	* Inside an open Poke the bytes this overwrites are journaled first, so
+	* the transaction can put them back; outside one the write goes straight
+	* into the machine and records nothing, as it always has.
+	*/
 	writeMemoryBytes(address, data) {
+		const poke = this.openPoke;
+		if (!poke || data.length === 0) {
+			this.runtime.writeMemoryBytes(address, data);
+			return;
+		}
+		const old = [...this.runtime.readMemoryBytes(address, BigInt(data.length))];
 		this.runtime.writeMemoryBytes(address, data);
+		poke.memoryWrites.push({
+			address,
+			old
+		});
 	}
 	readMemoryBytes(address, length) {
 		return this.runtime.readMemoryBytes(address, length);
@@ -2286,15 +2479,25 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 		return this.runtime.state === "PROGRAM_STOPPED";
 	}
 	async run(limit, breakpoints = []) {
+		this.assertNoOpenPoke("run");
 		this.validateRunLimit(limit);
 		const breakpointAddresses = this.resolveBreakpointAddresses(breakpoints);
-		if (this.isTracingEnabled()) return this.runWithHistory(limit, breakpointAddresses);
-		if (breakpointAddresses.length) return this.runWithBreakpoints(limit, breakpointAddresses);
-		await this.runtime.runUntilBlocked({
-			limit,
-			breakpointAddresses
-		});
-		return this.getStatus();
+		const wasExecuting = this.executing;
+		this.executing = true;
+		try {
+			if (this.isTracingEnabled()) return await this.runWithHistory(limit, breakpointAddresses);
+			if (breakpointAddresses.length) return await this.runWithBreakpoints(limit, breakpointAddresses);
+			await this.runtime.runUntilBlocked({
+				limit,
+				breakpointAddresses
+			});
+			return this.getStatus();
+		} finally {
+			this.executing = wasExecuting;
+		}
+	}
+	assertNoOpenPoke(what) {
+		if (this.openPoke) throw new Error(`Cannot ${what} while a poke is open: end it first`);
 	}
 	validateRunLimit(limit) {
 		if (limit === void 0) return;
@@ -2358,6 +2561,7 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 	clearExecutionTrace() {
 		this.history.clear();
 		this.callStack = [];
+		this.openPoke = null;
 	}
 	prepareOneInstructionRun() {
 		if (this.runtime.state === "PROGRAM_LOADED" || this.runtime.state === "PROGRAM_STOPPED") {
@@ -2393,6 +2597,7 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 				value: {
 					register,
 					old: registersBefore[register],
+					new: registersAfter[register],
 					size: 8
 				}
 			});
@@ -2402,6 +2607,7 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 		if (nativeStep.valid) this.recordControlFlowMutation(nativeStep, instruction, mutations);
 		const location = this.runtime.getSourceLocationForAddress(pcBefore);
 		const entry = {
+			kind: "instruction",
 			mutations,
 			pc: toHistoryPc(pcBefore),
 			old_ccr: { bits: flagsBefore },
@@ -2428,7 +2634,7 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 	* exact either way, because it restores the whole block rather than
 	* replaying the mutations.
 	*/
-	recordFpuMutations(fpuBefore, fpuAfter, mutations) {
+	recordFpuMutations(fpuBefore, fpuAfter, mutations, writes) {
 		if (fpuStateBlocksEqual(fpuBefore, fpuAfter)) return;
 		const stateBefore = decodeFpuState(fpuBefore);
 		const stateAfter = decodeFpuState(fpuAfter);
@@ -2439,18 +2645,34 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 				value: {
 					register: X86_SSE_REGISTERS[index],
 					old: stateBefore.xmm[index],
+					new: stateAfter.xmm[index],
 					size: 16
 				}
 			});
+			writes?.push({
+				type: "register",
+				name: X86_SSE_REGISTERS[index],
+				old: stateBefore.xmm[index],
+				new: stateAfter.xmm[index]
+			});
 		}
-		if (stateBefore.mxcsr !== stateAfter.mxcsr) mutations.push({
-			type: "WriteRegister",
-			value: {
-				register: "mxcsr",
+		if (stateBefore.mxcsr !== stateAfter.mxcsr) {
+			mutations.push({
+				type: "WriteRegister",
+				value: {
+					register: "mxcsr",
+					old: BigInt(stateBefore.mxcsr),
+					new: BigInt(stateAfter.mxcsr),
+					size: 4
+				}
+			});
+			writes?.push({
+				type: "register",
+				name: "mxcsr",
 				old: BigInt(stateBefore.mxcsr),
-				size: 4
-			}
-		});
+				new: BigInt(stateAfter.mxcsr)
+			});
+		}
 		const stBitsBefore = readLogicalStBits(fpuBefore);
 		const stBitsAfter = readLogicalStBits(fpuAfter);
 		for (let index = 0; index < stBitsBefore.length; index += 1) {
@@ -2460,9 +2682,16 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 				value: {
 					register: X86_X87_REGISTERS[index],
 					old: stBitsBefore[index],
+					new: stBitsAfter[index],
 					size: 8
 				}
 			});
+			writes?.push({
+				type: "register",
+				name: X86_X87_REGISTERS[index],
+				old: stBitsBefore[index],
+				new: stBitsAfter[index]
+			});
 		}
 		for (const word of [
 			"fctrl",
@@ -2475,15 +2704,106 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 				value: {
 					register: word,
 					old: BigInt(stateBefore[word]),
+					new: BigInt(stateAfter[word]),
 					size: 2
 				}
 			});
+			writes?.push({
+				type: "register",
+				name: word,
+				old: BigInt(stateBefore[word]),
+				new: BigInt(stateAfter[word])
+			});
 		}
 	}
+	/**
+	* The memory a Poke actually changed. The journal is collapsed per byte
+	* first - the EARLIEST `old` of every address, from the first write that
+	* touched it - and only then compared against what memory holds now, so a
+	* range written twice inside one transaction is diffed against what the
+	* machine held before the poke and not against the intermediate value the
+	* first write left. A range written away and back therefore leaves no
+	* trace at all, and two differing writes to one range leave one entry
+	* carrying the value the machine really had. What survives keeps the old
+	* bytes the way an instruction's writes do, for undo to put back in
+	* reverse order.
+	*/
+	recordPokeMemoryMutations(journaled, mutations, writes) {
+		const earliest = /* @__PURE__ */ new Map();
+		for (const write of journaled) write.old.forEach((byte, index) => {
+			const address = write.address + BigInt(index);
+			if (!earliest.has(address)) earliest.set(address, byte);
+		});
+		const addresses = [...earliest.keys()].sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+		const ranges = [];
+		for (const address of addresses) {
+			const open = ranges[ranges.length - 1];
+			const byte = earliest.get(address);
+			if (open && open.address + BigInt(open.old.length) === address) {
+				open.old.push(byte);
+				continue;
+			}
+			ranges.push({
+				address,
+				old: [byte]
+			});
+		}
+		const undoWrites = [];
+		for (const range of ranges) {
+			const current = [...this.runtime.readMemoryBytes(range.address, BigInt(range.old.length))];
+			if (current.every((byte, index) => byte === range.old[index])) continue;
+			undoWrites.push(range);
+			mutations.push({
+				type: "WriteMemoryBytes",
+				value: {
+					address: range.address,
+					old: [...range.old],
+					new: [...current]
+				}
+			});
+			writes.push({
+				type: "memory",
+				address: range.address,
+				old: [...range.old],
+				new: current
+			});
+		}
+		return undoWrites;
+	}
+	/**
+	* The memory a step wrote. The native journal hands over the bytes each
+	* store REPLACED, captured in the machine at that store; it records
+	* nothing about what a store PUT there. So `old` is the machine's own
+	* capture, taken at the write, while `new` is read out of the machine as
+	* the entry is recorded - the step has finished and nothing has run since,
+	* so those addresses still hold what the step left.
+	*
+	* The read costs one page lookup per store: one for the single store
+	* almost every store-bearing instruction journals, and none at all for the
+	* majority of instructions, which write no memory. It goes through the
+	* machine's own page lookup rather than the byte-by-byte bridge (see
+	* `BlinkRuntime.spyMemoryBytes`), which keeps it far below the cost of
+	* tracing the step around it.
+	*
+	* What reading rather than journaling costs: were one step to store twice
+	* over the same address, both entries would report the bytes the step
+	* ENDED with rather than the bytes each store left. No x86 instruction
+	* reachable here does that - blink coalesces a `rep` into one record, and
+	* push, call, ret, enter, leave, `xchg` with memory and read-modify-write
+	* arithmetic each journal a single store - so nothing observable turns on
+	* it today. Only a post-image in the native journal would close it, and
+	* that needs the wasm rebuilt, which this package does not do.
+	*
+	* A range the machine refuses to read back - a step can unmap what it
+	* wrote - leaves that entry with no new bytes rather than a guess, and the
+	* read never throws out of recording. Truncated writes keep their existing
+	* `Other` shape and stay out of the undo journal.
+	*/
 	recordMemoryMutations(writes, mutations) {
 		const undoWrites = [];
-		for (const write of writes) {
-			if (write.truncated || write.old.length !== write.size) {
+		const written = this.writtenBytes(writes);
+		for (const [index, write] of writes.entries()) {
+			if (!isRecordableWrite(write)) {
 				mutations.push({
 					type: "Other",
 					value: `Wrote ${write.size} bytes to 0x${write.address.toString(16)}`
@@ -2498,12 +2818,37 @@ var X86Emulator = class X86Emulator extends BaseEmulator {
 				type: "WriteMemoryBytes",
 				value: {
 					address: write.address,
-					old: [...write.old]
+					old: [...write.old],
+					new: written[index] ?? []
 				}
 			});
 		}
 		return undoWrites;
 	}
+	/**
+	* The bytes each of a step's stores left, by the index of that store: what
+	* the addresses that store wrote hold now, at the width of the write. One
+	* lookup per store it can account for, and none for a store it cannot.
+	*/
+	writtenBytes(writes) {
+		return writes.map((write) => isRecordableWrite(write) ? this.readBytes(write.address, write.size) : []);
+	}
+	/**
+	* One read of the machine that answers with nothing rather than throwing,
+	* so recording a step can never fail after the instruction already ran.
+	* It takes the machine's own page lookup when that can answer for the
+	* whole range and the byte-by-byte bridge otherwise; the two read the same
+	* memory the same way.
+	*/
+	readBytes(address, length) {
+		const spied = this.runtime.spyMemoryBytes(address, length);
+		if (spied) return Array.from(spied);
+		try {
+			return [...this.runtime.readMemoryBytes(address, BigInt(length))];
+		} catch {
+			return [];
+		}
+	}
 	recordControlFlowMutation(step, instruction, mutations) {
 		if (step.controlFlow === "call") {
 			const returnAddress = instruction ? instruction.address + BigInt(instruction.size) : step.pcBefore;
@@ -2546,6 +2891,6 @@ async function createX86Emulator(options = {}) {
 	return X86Emulator.create(options);
 }
 //#endregion
-export { BaseEmulator, BlinkRuntime, BlinkState, DEFAULT_ASSEMBLER_ID, EmulatorStatus, RegisterSize, X86Emulator, X86_FPU_STATE_CW_OFFSET, X86_FPU_STATE_DP_OFFSET, X86_FPU_STATE_IP_OFFSET, X86_FPU_STATE_MXCSR_OFFSET, X86_FPU_STATE_OP_OFFSET, X86_FPU_STATE_SIZE, X86_FPU_STATE_ST_OFFSET, X86_FPU_STATE_SW_OFFSET, X86_FPU_STATE_TW_OFFSET, X86_FPU_STATE_XMM_OFFSET, X86_PROJECT_ROOT, X86_REGISTER_NAMES, X86_SSE_REGISTERS, X86_X87_REGISTERS, assemblers, createX86Emulator, decodeFpuState, defaultResourceUrl, emptyFpuStateBlock, encodeFpuState, fasmDiagnostics, fpuStateBlocksEqual, gnuDiagnostics, isNodeRuntime, ldDiagnostics, locateDiagnosticColumn, locateDiagnosticSpan, nasmDiagnostics, observeCallbackResult, readLogicalStBits, readLogicalStTags, readResourceBytes, selectX86Source, stageX86Project, toResourceUrl, validateX86Project, x86ProjectSourcePath, x86ProjectText };
+export { BaseEmulator, BlinkRuntime, BlinkState, DEFAULT_ASSEMBLER_ID, EmulatorStatus, RegisterSize, X86Emulator, X86_FPU_STATE_CW_OFFSET, X86_FPU_STATE_DP_OFFSET, X86_FPU_STATE_IP_OFFSET, X86_FPU_STATE_MXCSR_OFFSET, X86_FPU_STATE_OP_OFFSET, X86_FPU_STATE_SIZE, X86_FPU_STATE_ST_OFFSET, X86_FPU_STATE_SW_OFFSET, X86_FPU_STATE_TW_OFFSET, X86_FPU_STATE_XMM_OFFSET, X86_PROJECT_ROOT, X86_REGISTER_NAMES, X86_SSE_REGISTERS, X86_X87_REGISTERS, assemblers, createX86Emulator, decodeFpuState, defaultResourceUrl, emptyFpuStateBlock, encodeFpuState, fasmDiagnostics, fpuStateBlocksEqual, gnuDiagnostics, isNodeRuntime, isShadowAddress, ldDiagnostics, locateDiagnosticColumn, locateDiagnosticSpan, nasmDiagnostics, observeCallbackResult, readLogicalStBits, readLogicalStTags, readResourceBytes, selectX86Source, stageX86Project, toResourceUrl, validateX86Project, x86ProjectSourcePath, x86ProjectText };
 
 //# sourceMappingURL=index.mjs.map