@celox-sim/celox 0.1.5 → 0.1.6

package/dist/types.d.ts

@@ -47,6 +47,10 @@ export interface SignalLayout {
     /** If true, an equal-sized mask follows immediately after the value. */
     readonly is4state: boolean;
     readonly direction: "input" | "output" | "inout";
+    /** The Veryl type kind (e.g. "clock", "reset_async_high", "logic"). */
+    readonly typeKind?: string;
+    /** For reset signals, the name of the associated clock (from FfDeclaration). */
+    readonly associatedClock?: string;
 }
 /**
  * Opaque handle returned by NAPI for event-based simulation.
@@ -69,6 +73,7 @@ export interface NativeSimulationHandle {
     runUntil(endTime: number): void;
     step(): number | null;
     time(): number;
+    nextEventTime(): number | null;
     evalComb(): void;
     dump(timestamp: number): void;
     dispose(): void;
@@ -91,12 +96,24 @@ export interface CreateResult<H extends NativeHandle = NativeHandle> {
     readonly events: Record<string, number>;
     /** Native control handle. */
     readonly handle: H;
+    /** Full instance hierarchy (optional — present when NAPI provides it). */
+    readonly hierarchy?: import("./napi-helpers.js").HierarchyNode;
 }
 export interface SimulatorOptions {
     /** Enable 4-state (X/Z) simulation. Default: false. */
     fourState?: boolean;
     /** Path to write VCD waveform output. */
     vcd?: string;
+    /** Enable Cranelift optimization passes. */
+    optimize?: boolean;
+    /** False-loop declarations to ignore during compilation. */
+    falseLoops?: LoopBreak[];
+    /** True-loop declarations with convergence limits. */
+    trueLoops?: TrueLoopSpec[];
+    /** Clock polarity. Default: "posedge". */
+    clockType?: "posedge" | "negedge";
+    /** Reset type. Default: "async_low". */
+    resetType?: "async_high" | "async_low" | "sync_high" | "sync_low";
 }
 /** A resolved event reference for use with `tick()`. */
 export interface EventHandle {
@@ -114,4 +131,21 @@ export interface FourStateValue {
 /** Construct a 4-state value. Mask bits set to 1 indicate X. */
 export declare function FourState(value: number | bigint, mask: number | bigint): FourStateValue;
 export declare function isFourStateValue(v: unknown): v is FourStateValue;
+/**
+ * Thrown when a simulation helper exceeds its step budget.
+ */
+export declare class SimulationTimeoutError extends Error {
+    readonly time: number;
+    readonly steps: number;
+    constructor(message: string, time: number, steps: number);
+}
+/** Specifies a false-loop to ignore during compilation. */
+export interface LoopBreak {
+    from: string;
+    to: string;
+}
+/** Specifies a true-loop with a convergence iteration limit. */
+export interface TrueLoopSpec extends LoopBreak {
+    maxIter: number;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -20,4 +20,20 @@ export function isFourStateValue(v) {
         v !== null &&
         v.__fourState === true);
 }
+// ---------------------------------------------------------------------------
+// Simulation timeout error
+// ---------------------------------------------------------------------------
+/**
+ * Thrown when a simulation helper exceeds its step budget.
+ */
+export class SimulationTimeoutError extends Error {
+    time;
+    steps;
+    constructor(message, time, steps) {
+        super(message);
+        this.name = "SimulationTimeoutError";
+        this.time = time;
+        this.steps = steps;
+    }
+}
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgIH,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E,mCAAmC;AACnC,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AASvC,gEAAgE;AAChE,MAAM,UAAU,SAAS,CACvB,KAAsB,EACtB,IAAqB;IAErB,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,CAAU;IACzC,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,IAAI;QACT,CAAoB,CAAC,WAAW,KAAK,IAAI,CAC3C,CAAC;AACJ,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiJH,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E,mCAAmC;AACnC,MAAM,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;AASvC,gEAAgE;AAChE,MAAM,UAAU,SAAS,CACvB,KAAsB,EACtB,IAAqB;IAErB,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,CAAU;IACzC,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,IAAI;QACT,CAAoB,CAAC,WAAW,KAAK,IAAI,CAC3C,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;GAEG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IACtC,IAAI,CAAS;IACb,KAAK,CAAS;IAEvB,YAAY,OAAe,EAAE,IAAY,EAAE,KAAa;QACtD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celox-sim/celox",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "TypeScript runtime for Celox HDL simulation",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,7 +29,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@celox-sim/celox-napi": "0.1.5"
+    "@celox-sim/celox-napi": "0.1.6"
   },
   "peerDependencies": {
     "vitest": ">=1.0.0"

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";
 
 // ---------------------------------------------------------------------------
@@ -183,11 +184,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 +197,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 +246,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;
 }
 

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,
@@ -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: number;
+    en: number;
+    readonly count: number;
+  }
+
+  // waitForCycles benchmark
+  const simWait = Simulation.fromSource<CounterPorts>(COUNTER_CODE, "Counter");
+  simWait.addClock("clk", { period: 10 });
+  simWait.dut.rst = 1;
+  simWait.runUntil(20);
+  simWait.dut.rst = 0;
+  simWait.dut.en = 1;
+
+  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 = 1;
+  simRun.runUntil(20);
+  simRun.dut.rst = 0;
+  simRun.dut.en = 1;
+
+  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 = 1;
+  simNoOpt.tick();
+  simNoOpt.dut.rst = 0;
+  simNoOpt.tick();
+
+  const simOpt = Simulator.fromSource<TopPorts>(CODE, "Top", {
+    optimize: true,
+  });
+  simOpt.dut.rst = 1;
+  simOpt.tick();
+  simOpt.dut.rst = 0;
+  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 },
+  );
+});