@celox-sim/celox 0.1.5 → 0.1.7

package/src/dut.ts

@@ -13,6 +13,7 @@ import type {
   SignalLayout,
   FourStateValue,
 } from "./types.js";
+import type { HierarchyNode } from "./napi-helpers.js";
 import { isFourStateValue } from "./types.js";
 
 // ---------------------------------------------------------------------------
@@ -115,27 +116,27 @@ function writeBigInt(
   }
 }
 
-/** Read a signal value from the DataView. Returns number or bigint. */
+/** Read a signal value from the DataView. Always returns bigint. */
 function readSignal(
   view: DataView,
   sig: SignalLayout,
-): number | bigint {
+): bigint {
   if (sig.width <= 53) {
-    return readNumber(view, sig.offset, sig.width);
+    return BigInt(readNumber(view, sig.offset, sig.width));
   }
   return readBigInt(view, sig.offset, sig.byteSize);
 }
 
-/** Write a signal value to the DataView. Accepts number or bigint. */
+/** Write a signal value to the DataView. Accepts bigint (number accepted for compat). */
 function writeSignal(
   view: DataView,
   sig: SignalLayout,
-  value: number | bigint,
+  value: bigint | number,
 ): void {
-  if (sig.width <= 53 && typeof value === "number") {
-    writeNumber(view, sig.offset, sig.width, value);
+  const bigVal = typeof value === "bigint" ? value : BigInt(value);
+  if (sig.width <= 53) {
+    writeNumber(view, sig.offset, sig.width, Number(bigVal));
   } else {
-    const bigVal = typeof value === "bigint" ? value : BigInt(value);
     writeBigInt(view, sig.offset, sig.byteSize, bigVal);
   }
 }
@@ -161,11 +162,8 @@ function writeFourState(
 /** Write all-X mask for a signal. */
 function writeAllX(view: DataView, sig: SignalLayout): void {
   // Value = 0, mask = all 1s
-  writeSignal(view, sig, sig.width <= 53 ? 0 : 0n);
-  const allOnes =
-    sig.width <= 53
-      ? (sig.width === 53 ? Number.MAX_SAFE_INTEGER : (1 << sig.width) - 1)
-      : (1n << BigInt(sig.width)) - 1n;
+  writeSignal(view, sig, 0n);
+  const allOnes = (1n << BigInt(sig.width)) - 1n;
   const maskLayout: SignalLayout = {
     offset: sig.offset + sig.byteSize,
     width: sig.width,
@@ -183,11 +181,12 @@ function writeAllX(view: DataView, sig: SignalLayout): void {
 /**
  * Create a DUT accessor object with defineProperty-based getters/setters.
  *
- * @param buffer   SharedArrayBuffer from NAPI create()
- * @param layout   Per-signal byte layout within the buffer
- * @param portDefs Port metadata from the ModuleDefinition
- * @param handle   Native handle (for evalComb calls)
- * @param state    Shared dirty-tracking state
+ * @param buffer    SharedArrayBuffer from NAPI create()
+ * @param layout    Per-signal byte layout within the buffer
+ * @param portDefs  Port metadata from the ModuleDefinition
+ * @param handle    Native handle (for evalComb calls)
+ * @param state     Shared dirty-tracking state
+ * @param hierarchy Optional hierarchy node for child instance access
  */
 export function createDut<P>(
   buffer: ArrayBuffer | SharedArrayBuffer,
@@ -195,6 +194,7 @@ export function createDut<P>(
   portDefs: Record<string, PortInfo>,
   handle: NativeHandle,
   state: DirtyState,
+  hierarchy?: HierarchyNode,
 ): P {
   const view = new DataView(buffer);
   const obj = Object.create(null) as P;
@@ -243,6 +243,91 @@ export function createDut<P>(
     defineSignalProperty(obj as object, name, view, sig, port, handle, state);
   }
 
+  // Attach child instance accessors from hierarchy
+  if (hierarchy) {
+    for (const [childName, instances] of Object.entries(hierarchy.children)) {
+      if (instances.length === 1) {
+        const childDut = createChildDut(buffer, instances[0]!, handle, state);
+        Object.defineProperty(obj, childName, {
+          value: childDut,
+          enumerable: true,
+          configurable: false,
+          writable: false,
+        });
+      } else if (instances.length > 1) {
+        const childDuts = instances.map((inst) =>
+          createChildDut(buffer, inst, handle, state),
+        );
+        Object.defineProperty(obj, childName, {
+          value: childDuts,
+          enumerable: true,
+          configurable: false,
+          writable: false,
+        });
+      }
+    }
+  }
+
+  return obj;
+}
+
+/**
+ * Create a child instance DUT accessor from a HierarchyNode.
+ * Recursively creates accessors for the child's signals and its own children.
+ */
+export function createChildDut(
+  buffer: ArrayBuffer | SharedArrayBuffer,
+  hierarchy: HierarchyNode,
+  handle: NativeHandle,
+  state: DirtyState,
+): object {
+  const view = new DataView(buffer);
+  const obj = Object.create(null);
+
+  // Define signal properties for this child instance
+  for (const [name, port] of Object.entries(hierarchy.ports)) {
+    if (port.type === "clock") continue;
+
+    const sig = hierarchy.forDut[name];
+    if (!sig) continue;
+
+    if (port.arrayDims && port.arrayDims.length > 0) {
+      const arrayObj = createArrayDut(view, sig, port, handle, state);
+      Object.defineProperty(obj, name, {
+        value: arrayObj,
+        enumerable: true,
+        configurable: false,
+        writable: false,
+      });
+      continue;
+    }
+
+    defineSignalProperty(obj, name, view, sig, port, handle, state);
+  }
+
+  // Recursively attach children
+  for (const [childName, instances] of Object.entries(hierarchy.children)) {
+    if (instances.length === 1) {
+      const childDut = createChildDut(buffer, instances[0]!, handle, state);
+      Object.defineProperty(obj, childName, {
+        value: childDut,
+        enumerable: true,
+        configurable: false,
+        writable: false,
+      });
+    } else if (instances.length > 1) {
+      const childDuts = instances.map((inst) =>
+        createChildDut(buffer, inst, handle, state),
+      );
+      Object.defineProperty(obj, childName, {
+        value: childDuts,
+        enumerable: true,
+        configurable: false,
+        writable: false,
+      });
+    }
+  }
+
   return obj;
 }
 
@@ -260,7 +345,7 @@ function defineSignalProperty(
   const isInput = port?.direction === "input";
 
   Object.defineProperty(target, name, {
-    get(): number | bigint {
+    get(): bigint {
       // Output reads: lazy evalComb if dirty
       if (state.dirty && !isInput) {
         handle.evalComb();
@@ -269,7 +354,7 @@ function defineSignalProperty(
       return readSignal(view, sig);
     },
 
-    set(value: number | bigint | symbol | FourStateValue) {
+    set(value: bigint | number | symbol | FourStateValue) {
       if (isOutput) {
         throw new Error(`Cannot write to output port '${name}'`);
       }
@@ -285,7 +370,8 @@ function defineSignalProperty(
         }
         writeFourState(view, sig, value);
       } else {
-        writeSignal(view, sig, value as number | bigint);
+        const bigVal = typeof value === "bigint" ? value : BigInt(value as number);
+        writeSignal(view, sig, bigVal);
         // Clear mask when writing a defined value to a 4-state signal
         if (sig.is4state) {
           const maskLayout: SignalLayout = {
@@ -295,7 +381,7 @@ function defineSignalProperty(
             is4state: false,
             direction: sig.direction,
           };
-          writeSignal(view, maskLayout, sig.width <= 53 ? 0 : 0n);
+          writeSignal(view, maskLayout, 0n);
         }
       }
 
@@ -372,19 +458,19 @@ function createArrayDut(
   return {
     length: totalElements,
 
-    at(i: number): number | bigint {
+    at(i: number): bigint {
       if (state.dirty && !isInput) {
         handle.evalComb();
         state.dirty = false;
       }
       const offset = baseOffset + i * elementByteSize;
       if (elementWidth <= 53) {
-        return readNumber(view, offset, elementWidth);
+        return BigInt(readNumber(view, offset, elementWidth));
       }
       return readBigInt(view, offset, elementByteSize);
     },
 
-    set(i: number, value: number | bigint | symbol | FourStateValue): void {
+    set(i: number, value: bigint | number | symbol | FourStateValue): void {
       if (isOutput) {
         throw new Error("Cannot write to output array port");
       }
@@ -407,13 +493,20 @@ function createArrayDut(
           is4state, direction: baseSig.direction,
         };
         writeFourState(view, elemSig, value);
-      } else if (elementWidth <= 53 && typeof value === "number") {
-        writeNumber(view, offset, elementWidth, value);
-        if (is4state) writeNumber(view, offset + elementByteSize, elementWidth, 0);
       } else {
         const bigVal = typeof value === "bigint" ? value : BigInt(value as number);
-        writeBigInt(view, offset, elementByteSize, bigVal);
-        if (is4state) writeBigInt(view, offset + elementByteSize, elementByteSize, 0n);
+        const elemSig: SignalLayout = {
+          offset, width: elementWidth, byteSize: elementByteSize,
+          is4state, direction: baseSig.direction,
+        };
+        writeSignal(view, elemSig, bigVal);
+        if (is4state) {
+          const maskSig: SignalLayout = {
+            offset: offset + elementByteSize, width: elementWidth,
+            byteSize: elementByteSize, is4state: false, direction: baseSig.direction,
+          };
+          writeSignal(view, maskSig, 0n);
+        }
       }
       state.dirty = true;
     },
@@ -431,7 +524,7 @@ function createArrayDut(
 export function readFourState(
   buffer: ArrayBuffer | SharedArrayBuffer,
   sig: SignalLayout,
-): [value: number | bigint, mask: number | bigint] {
+): [value: bigint, mask: bigint] {
   if (!sig.is4state) {
     throw new Error("Signal is not 4-state");
   }

package/src/e2e.bench.ts

@@ -12,7 +12,7 @@
 import { bench, describe, afterAll } from "vitest";
 import { Simulator } from "./simulator.js";
 import { Simulation } from "./simulation.js";
-import type { ModuleDefinition } from "./types.js";
+import type { ModuleDefinition, SimulationTimeoutError } from "./types.js";
 import {
   loadNativeAddon,
   createSimulatorBridge,
@@ -39,8 +39,8 @@ const CODE = `
 `;
 
 interface TopPorts {
-  rst: number;
-  readonly cnt: { at(i: number): number; readonly length: number };
+  rst: bigint;
+  readonly cnt: { at(i: number): bigint; readonly length: number };
 }
 
 describe("simulation", () => {
@@ -56,9 +56,9 @@ describe("simulation", () => {
   const sim = Simulator.fromSource<TopPorts>(CODE, "Top");
 
   // Reset sequence
-  sim.dut.rst = 1;
+  sim.dut.rst = 1n;
   sim.tick();
-  sim.dut.rst = 0;
+  sim.dut.rst = 0n;
   sim.tick();
 
   afterAll(() => {
@@ -81,7 +81,7 @@ describe("simulation", () => {
 
   // Testbench pattern: write input + tick + read back
   bench("testbench_tick_top_n1000_x1", () => {
-    sim.dut.rst = 0;
+    sim.dut.rst = 0n;
     sim.tick();
     // biome-ignore lint: read to measure full testbench cycle
     sim.dut.rst;
@@ -91,7 +91,7 @@ describe("simulation", () => {
     "testbench_tick_top_n1000_x1000000",
     () => {
       for (let i = 0; i < 1_000_000; i++) {
-        sim.dut.rst = 0;
+        sim.dut.rst = 0n;
         sim.tick();
         // biome-ignore lint: read to measure full testbench cycle
         sim.dut.rst;
@@ -116,9 +116,9 @@ describe("simulation", () => {
   const simArr = Simulator.create<TopPorts>(TopModule, {
     __nativeCreate: createSimulatorBridge(addon),
   });
-  simArr.dut.rst = 1;
+  simArr.dut.rst = 1n;
   simArr.tick();
-  simArr.dut.rst = 0;
+  simArr.dut.rst = 0n;
   simArr.tick();
 
   afterAll(() => {
@@ -126,7 +126,7 @@ describe("simulation", () => {
   });
 
   bench("testbench_array_tick_top_n1000_x1", () => {
-    simArr.dut.rst = 0;
+    simArr.dut.rst = 0n;
     simArr.tick();
     // biome-ignore lint: read array element to measure .at() overhead
     simArr.dut.cnt.at(0);
@@ -136,7 +136,7 @@ describe("simulation", () => {
     "testbench_array_tick_top_n1000_x1000000",
     () => {
       for (let i = 0; i < 1_000_000; i++) {
-        simArr.dut.rst = 0;
+        simArr.dut.rst = 0n;
         simArr.tick();
         // biome-ignore lint: read array element to measure .at() overhead
         simArr.dut.cnt.at(0);
@@ -155,9 +155,9 @@ describe("simulation", () => {
 describe("overhead", () => {
   // Simulator.tick — same as Rust simulator_tick_x10000
   const simTick = Simulator.fromSource<TopPorts>(CODE, "Top");
-  simTick.dut.rst = 1;
+  simTick.dut.rst = 1n;
   simTick.tick();
-  simTick.dut.rst = 0;
+  simTick.dut.rst = 0n;
   simTick.tick();
 
   afterAll(() => {
@@ -238,3 +238,166 @@ describe("simulation-time-based", () => {
     { iterations: 3, time: 0 },
   );
 });
+
+/**
+ * Phase 3b: Testbench helpers benchmarks.
+ *
+ * Compares waitForCycles vs manual step loop, and runUntil with/without
+ * maxSteps guard to measure overhead.
+ */
+describe("testbench-helpers", () => {
+  const COUNTER_CODE = `
+    module Counter (
+        clk: input clock,
+        rst: input reset,
+        en: input logic,
+        count: output logic<8>,
+    ) {
+        var count_r: logic<8>;
+
+        always_ff (clk, rst) {
+            if_reset {
+                count_r = 0;
+            } else if en {
+                count_r = count_r + 1;
+            }
+        }
+
+        always_comb {
+            count = count_r;
+        }
+    }
+  `;
+
+  interface CounterPorts {
+    rst: bigint;
+    en: bigint;
+    readonly count: bigint;
+  }
+
+  // waitForCycles benchmark
+  const simWait = Simulation.fromSource<CounterPorts>(COUNTER_CODE, "Counter");
+  simWait.addClock("clk", { period: 10 });
+  simWait.dut.rst = 1n;
+  simWait.runUntil(20);
+  simWait.dut.rst = 0n;
+  simWait.dut.en = 1n;
+
+  afterAll(() => {
+    simWait.dispose();
+  });
+
+  bench(
+    "waitForCycles_x1000",
+    () => {
+      simWait.waitForCycles("clk", 1000);
+    },
+    { iterations: 3, time: 0 },
+  );
+
+  bench(
+    "manual_step_loop_x2000",
+    () => {
+      for (let i = 0; i < 2000; i++) {
+        simWait.step();
+      }
+    },
+    { iterations: 3, time: 0 },
+  );
+
+  // runUntil: fast Rust path vs guarded TS path
+  const simRun = Simulation.fromSource<CounterPorts>(COUNTER_CODE, "Counter");
+  simRun.addClock("clk", { period: 10 });
+  simRun.dut.rst = 1n;
+  simRun.runUntil(20);
+  simRun.dut.rst = 0n;
+  simRun.dut.en = 1n;
+
+  afterAll(() => {
+    simRun.dispose();
+  });
+
+  bench(
+    "runUntil_fast_path_100000",
+    () => {
+      const base = simRun.time();
+      simRun.runUntil(base + 100_000);
+    },
+    { iterations: 3, time: 0 },
+  );
+
+  bench(
+    "runUntil_guarded_100000",
+    () => {
+      const base = simRun.time();
+      simRun.runUntil(base + 100_000, { maxSteps: 1_000_000 });
+    },
+    { iterations: 3, time: 0 },
+  );
+});
+
+/**
+ * Phase 3c: Optimize flag benchmarks.
+ *
+ * Compares build time and tick performance with and without optimization.
+ */
+describe("optimize-flag", () => {
+  bench(
+    "build_without_optimize",
+    () => {
+      const sim = Simulator.fromSource<TopPorts>(CODE, "Top");
+      sim.dispose();
+    },
+    { iterations: 3, time: 0 },
+  );
+
+  bench(
+    "build_with_optimize",
+    () => {
+      const sim = Simulator.fromSource<TopPorts>(CODE, "Top", {
+        optimize: true,
+      });
+      sim.dispose();
+    },
+    { iterations: 3, time: 0 },
+  );
+
+  const simNoOpt = Simulator.fromSource<TopPorts>(CODE, "Top");
+  simNoOpt.dut.rst = 1n;
+  simNoOpt.tick();
+  simNoOpt.dut.rst = 0n;
+  simNoOpt.tick();
+
+  const simOpt = Simulator.fromSource<TopPorts>(CODE, "Top", {
+    optimize: true,
+  });
+  simOpt.dut.rst = 1n;
+  simOpt.tick();
+  simOpt.dut.rst = 0n;
+  simOpt.tick();
+
+  afterAll(() => {
+    simNoOpt.dispose();
+    simOpt.dispose();
+  });
+
+  bench(
+    "tick_x10000_without_optimize",
+    () => {
+      for (let i = 0; i < 10_000; i++) {
+        simNoOpt.tick();
+      }
+    },
+    { iterations: 3, time: 0 },
+  );
+
+  bench(
+    "tick_x10000_with_optimize",
+    () => {
+      for (let i = 0; i < 10_000; i++) {
+        simOpt.tick();
+      }
+    },
+    { iterations: 3, time: 0 },
+  );
+});