@celox-sim/celox 0.1.5 → 0.1.7

package/src/simulation.test.ts

@@ -5,15 +5,16 @@ import type {
   ModuleDefinition,
   NativeSimulationHandle,
 } from "./types.js";
+import { SimulationTimeoutError } from "./types.js";
 
 // ---------------------------------------------------------------------------
 // Mock helpers
 // ---------------------------------------------------------------------------
 
 interface TopPorts {
-  rst: number;
-  d: number;
-  readonly q: number;
+  rst: bigint;
+  d: bigint;
+  readonly q: bigint;
 }
 
 const TopModule: ModuleDefinition<TopPorts> = {
@@ -29,7 +30,10 @@ const TopModule: ModuleDefinition<TopPorts> = {
   events: ["clk"],
 };
 
-function createMockNative(): {
+function createMockNative(opts?: {
+  resetTypeKind?: string;
+  associatedClock?: string;
+}): {
   create: NativeCreateSimulationFn;
   handle: NativeSimulationHandle;
   buffer: SharedArrayBuffer;
@@ -50,9 +54,12 @@ function createMockNative(): {
       currentTime += 5;
       const view = new DataView(buffer);
       view.setUint8(4, view.getUint8(2));
+      // Toggle clock (offset 6) on each step to simulate half-period=5
+      view.setUint8(6, view.getUint8(6) === 0 ? 1 : 0);
       return currentTime;
     }),
     time: vi.fn().mockImplementation(() => currentTime),
+    nextEventTime: vi.fn().mockReturnValue(null),
     evalComb: vi.fn().mockImplementation(() => {
       const view = new DataView(buffer);
       view.setUint8(4, view.getUint8(2));
@@ -61,13 +68,16 @@ function createMockNative(): {
     dispose: vi.fn(),
   };
 
+  const resetTypeKind = opts?.resetTypeKind ?? "reset_async_high";
+  const associatedClock = opts?.associatedClock;
+
   const create: NativeCreateSimulationFn = vi.fn().mockReturnValue({
     buffer,
     layout: {
-      clk: { offset: 6, width: 1, byteSize: 1, is4state: false, direction: "input" },
-      rst: { offset: 0, width: 1, byteSize: 1, is4state: false, direction: "input" },
-      d:   { offset: 2, width: 8, byteSize: 1, is4state: false, direction: "input" },
-      q:   { offset: 4, width: 8, byteSize: 1, is4state: false, direction: "output" },
+      clk: { offset: 6, width: 1, byteSize: 1, is4state: false, direction: "input", typeKind: "clock" },
+      rst: { offset: 0, width: 1, byteSize: 1, is4state: false, direction: "input", typeKind: resetTypeKind, ...(associatedClock ? { associatedClock } : {}) },
+      d:   { offset: 2, width: 8, byteSize: 1, is4state: false, direction: "input", typeKind: "logic" },
+      q:   { offset: 4, width: 8, byteSize: 1, is4state: false, direction: "output", typeKind: "logic" },
     },
     events: { clk: 0 },
     handle,
@@ -117,11 +127,11 @@ describe("Simulation", () => {
       __nativeCreate: mock.create,
     });
 
-    sim.dut.d = 42;
+    sim.dut.d = 42n;
     sim.runUntil(100);
 
     expect(mock.handle.runUntil).toHaveBeenCalledWith(100);
-    expect(sim.dut.q).toBe(42);
+    expect(sim.dut.q).toBe(42n);
   });
 
   test("step", () => {
@@ -130,11 +140,11 @@ describe("Simulation", () => {
       __nativeCreate: mock.create,
     });
 
-    sim.dut.d = 0xAB;
+    sim.dut.d = 0xABn;
     const t = sim.step();
 
     expect(t).toBe(5);
-    expect(sim.dut.q).toBe(0xAB);
+    expect(sim.dut.q).toBe(0xABn);
   });
 
   test("time", () => {
@@ -182,4 +192,202 @@ describe("Simulation", () => {
       Simulation.create(TopModule);
     }).toThrow("Native simulator binding not loaded");
   });
+
+  test("runUntil with maxSteps: fast path when omitted", () => {
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.runUntil(100);
+    // Without maxSteps, the Rust fast-path should be used
+    expect(mock.handle.runUntil).toHaveBeenCalledWith(100);
+  });
+
+  test("runUntil with maxSteps: throws SimulationTimeoutError", () => {
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    // step mock increments time by 5 each call, so reaching 10000 requires 2000 steps
+    // With maxSteps=10 we'll exhaust before getting there
+    expect(() => sim.runUntil(10000, { maxSteps: 10 })).toThrow(
+      SimulationTimeoutError,
+    );
+  });
+
+  test("runUntil with maxSteps: timeout error has correct properties", () => {
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    try {
+      sim.runUntil(10000, { maxSteps: 5 });
+      expect.unreachable();
+    } catch (e) {
+      expect(e).toBeInstanceOf(SimulationTimeoutError);
+      const err = e as SimulationTimeoutError;
+      expect(err.steps).toBe(5);
+      expect(err.time).toBeGreaterThan(0);
+    }
+  });
+
+  test("waitUntil: returns time when condition is met", () => {
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.dut.d = 42n;
+    let callCount = 0;
+    const t = sim.waitUntil(() => {
+      callCount++;
+      return callCount >= 3;
+    });
+
+    expect(t).toBeGreaterThan(0);
+    expect(callCount).toBe(3);
+  });
+
+  test("waitUntil: throws on timeout", () => {
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    expect(() =>
+      sim.waitUntil(() => false, { maxSteps: 5 }),
+    ).toThrow(SimulationTimeoutError);
+  });
+
+  test("waitForCycles: counts rising edges", () => {
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.addClock("clk", { period: 10 });
+    const t = sim.waitForCycles("clk", 3);
+    // clk toggles each step: 0→1→0→1→0→1 (5 steps for 3 rising edges)
+    expect(mock.handle.step).toHaveBeenCalledTimes(5);
+    expect(t).toBe(25);
+  });
+
+  test("waitForCycles: throws without addClock", () => {
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    expect(() => sim.waitForCycles("clk", 3)).toThrow("No clock registered");
+  });
+
+  test("reset: active-high with associatedClock steps until target time", () => {
+    const mock = createMockNative({ associatedClock: "clk" });
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.addClock("clk", { period: 10 });
+    sim.reset("rst");
+    // Default activeCycles=2: 3 steps for 2 rising edges (0→1→0→1)
+    expect(mock.handle.step).toHaveBeenCalledTimes(3);
+    // Released to inactive value (0 for active-high)
+    const view = new DataView(mock.buffer);
+    expect(view.getUint8(0)).toBe(0);
+  });
+
+  test("reset: custom activeCycles with associatedClock", () => {
+    const mock = createMockNative({ associatedClock: "clk" });
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.addClock("clk", { period: 10 });
+    sim.reset("rst", { activeCycles: 3 });
+    // 3 cycles: 5 steps for 3 rising edges (0→1→0→1→0→1)
+    expect(mock.handle.step).toHaveBeenCalledTimes(5);
+  });
+
+  test("reset: explicit duration overrides cycle calculation", () => {
+    const mock = createMockNative({ associatedClock: "clk" });
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.addClock("clk", { period: 10 });
+    sim.reset("rst", { duration: 50 });
+    // Explicit duration → runUntil(0 + 50 = 50)
+    expect(mock.handle.runUntil).toHaveBeenCalledWith(50);
+  });
+
+  test("reset: active-low with associatedClock asserts 0 then releases to 1", () => {
+    const mock = createMockNative({
+      resetTypeKind: "reset_async_low",
+      associatedClock: "clk",
+    });
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.addClock("clk", { period: 10 });
+    sim.reset("rst");
+    // active-low: releases to 1
+    const view = new DataView(mock.buffer);
+    expect(view.getUint8(0)).toBe(1);
+    // activeCycles=2: 3 steps for 2 rising edges
+    expect(mock.handle.step).toHaveBeenCalledTimes(3);
+  });
+
+  test("reset: throws when no associatedClock and no duration", () => {
+    // No associatedClock in layout
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    expect(() => sim.reset("rst")).toThrow("has no associated clock");
+  });
+
+  test("reset: no associatedClock but duration specified works", () => {
+    // No associatedClock in layout, but duration is given
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.reset("rst", { duration: 100 });
+    expect(mock.handle.runUntil).toHaveBeenCalledWith(100);
+  });
+
+  test("reset: throws when associatedClock not registered via addClock", () => {
+    const mock = createMockNative({ associatedClock: "clk" });
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+    // addClock not called
+    expect(() => sim.reset("rst")).toThrow(
+      "No clock registered for 'clk'",
+    );
+  });
+
+  test("reset: throws on non-reset port", () => {
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    expect(() => sim.reset("d")).toThrow("not a reset signal");
+  });
+
+  test("reset: throws on unknown port", () => {
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    expect(() => sim.reset("nonexistent")).toThrow("Unknown port");
+  });
 });

package/src/simulation.ts

@@ -7,16 +7,21 @@
 
 import type {
   CreateResult,
+  FourStateValue,
   ModuleDefinition,
   NativeSimulationHandle,
+  SignalLayout,
   SimulatorOptions,
 } from "./types.js";
-import { createDut, type DirtyState } from "./dut.js";
+import { SimulationTimeoutError } from "./types.js";
+import { createDut, readFourState, type DirtyState } from "./dut.js";
 import {
   loadNativeAddon,
   parseNapiLayout,
+  parseHierarchyLayout,
   buildPortsFromLayout,
   wrapDirectSimulationHandle,
+  buildNapiOpts,
 } from "./napi-helpers.js";
 
 /**
@@ -49,6 +54,9 @@ export class Simulation<P = Record<string, unknown>> {
   private readonly _dut: P;
   private readonly _events: Record<string, number>;
   private readonly _state: DirtyState;
+  private readonly _buffer: ArrayBuffer | SharedArrayBuffer;
+  private readonly _layout: Record<string, SignalLayout & { typeKind?: string; associatedClock?: string }>;
+  private readonly _clocks = new Map<string, { period: number; eventId: number }>();
   private _disposed = false;
 
   private constructor(
@@ -56,11 +64,15 @@ export class Simulation<P = Record<string, unknown>> {
     dut: P,
     events: Record<string, number>,
     state: DirtyState,
+    buffer: ArrayBuffer | SharedArrayBuffer,
+    layout: Record<string, SignalLayout & { typeKind?: string; associatedClock?: string }>,
   ) {
     this._handle = handle;
     this._dut = dut;
     this._events = events;
     this._state = state;
+    this._buffer = buffer;
+    this._layout = layout;
   }
 
   /**
@@ -91,8 +103,8 @@ export class Simulation<P = Record<string, unknown>> {
       );
     }
 
-    const { fourState, vcd } = options ?? {};
-    const result = createFn(module.source, module.name, { fourState, vcd });
+    const { fourState, vcd, optimize, falseLoops, trueLoops, clockType, resetType } = options ?? {};
+    const result = createFn(module.source, module.name, { fourState, vcd, optimize, falseLoops, trueLoops, clockType, resetType });
     const state: DirtyState = { dirty: false };
 
     const dut = createDut<P>(
@@ -101,9 +113,10 @@ export class Simulation<P = Record<string, unknown>> {
       module.ports,
       result.handle,
       state,
+      result.hierarchy,
     );
 
-    return new Simulation<P>(result.handle, dut, result.events, state);
+    return new Simulation<P>(result.handle, dut, result.events, state, result.buffer, result.layout);
   }
 
   /**
@@ -124,11 +137,12 @@ export class Simulation<P = Record<string, unknown>> {
     options?: SimulatorOptions & { nativeAddonPath?: string },
   ): Simulation<P> {
     const addon = loadNativeAddon(options?.nativeAddonPath);
-    const napiOpts = options?.fourState ? { fourState: options.fourState } : undefined;
+    const napiOpts = buildNapiOpts(options);
     const raw = new addon.NativeSimulationHandle(source, top, napiOpts);
 
     const layout = parseNapiLayout(raw.layoutJson);
     const events: Record<string, number> = JSON.parse(raw.eventsJson);
+    const hierarchy = parseHierarchyLayout(raw.hierarchyJson, events);
 
     const ports = buildPortsFromLayout(layout.signals, events);
 
@@ -136,9 +150,9 @@ export class Simulation<P = Record<string, unknown>> {
 
     const state: DirtyState = { dirty: false };
     const handle = wrapDirectSimulationHandle(raw);
-    const dut = createDut<P>(buf, layout.forDut, ports, handle, state);
+    const dut = createDut<P>(buf, layout.forDut, ports, handle, state, hierarchy);
 
-    return new Simulation<P>(handle, dut, events, state);
+    return new Simulation<P>(handle, dut, events, state, buf, layout.signals);
   }
 
   /**
@@ -159,11 +173,12 @@ export class Simulation<P = Record<string, unknown>> {
     options?: SimulatorOptions & { nativeAddonPath?: string },
   ): Simulation<P> {
     const addon = loadNativeAddon(options?.nativeAddonPath);
-    const napiOpts = options?.fourState ? { fourState: options.fourState } : undefined;
+    const napiOpts = buildNapiOpts(options);
     const raw = addon.NativeSimulationHandle.fromProject(projectPath, top, napiOpts);
 
     const layout = parseNapiLayout(raw.layoutJson);
     const events: Record<string, number> = JSON.parse(raw.eventsJson);
+    const hierarchy = parseHierarchyLayout(raw.hierarchyJson, events);
 
     const ports = buildPortsFromLayout(layout.signals, events);
 
@@ -171,9 +186,9 @@ export class Simulation<P = Record<string, unknown>> {
 
     const state: DirtyState = { dirty: false };
     const handle = wrapDirectSimulationHandle(raw);
-    const dut = createDut<P>(buf, layout.forDut, ports, handle, state);
+    const dut = createDut<P>(buf, layout.forDut, ports, handle, state, hierarchy);
 
-    return new Simulation<P>(handle, dut, events, state);
+    return new Simulation<P>(handle, dut, events, state, buf, layout.signals);
   }
 
   /** The DUT accessor object — read/write ports as plain properties. */
@@ -194,6 +209,7 @@ export class Simulation<P = Record<string, unknown>> {
     this.ensureAlive();
     const eventId = this.resolveEvent(name);
     this._handle.addClock(eventId, opts.period, opts.initialDelay ?? 0);
+    this._clocks.set(name, { period: opts.period, eventId });
   }
 
   /**
@@ -211,11 +227,33 @@ export class Simulation<P = Record<string, unknown>> {
   /**
    * Run the simulation until the given time.
    * Processes all scheduled events up to and including `endTime`.
-   * evalComb is called internally; dirty is cleared on return.
+   *
+   * When `maxSteps` is provided, steps are counted in TS and a
+   * `SimulationTimeoutError` is thrown if the budget is exhausted before
+   * reaching `endTime`. Without `maxSteps` the fast Rust path is used.
    */
-  runUntil(endTime: number): void {
+  runUntil(endTime: number, opts?: { maxSteps?: number }): void {
     this.ensureAlive();
-    this._handle.runUntil(endTime);
+    if (opts?.maxSteps == null) {
+      this._handle.runUntil(endTime);
+      this._state.dirty = false;
+      return;
+    }
+    const max = opts.maxSteps;
+    let steps = 0;
+    while (this._handle.time() < endTime) {
+      const t = this._handle.step();
+      if (t == null) break;
+      steps++;
+      if (steps >= max) {
+        this._state.dirty = false;
+        throw new SimulationTimeoutError(
+          `runUntil: exceeded ${max} steps at time ${this._handle.time()} (target ${endTime})`,
+          this._handle.time(),
+          steps,
+        );
+      }
+    }
     this._state.dirty = false;
   }
 
@@ -237,6 +275,153 @@ export class Simulation<P = Record<string, unknown>> {
     return this._handle.time();
   }
 
+  /**
+   * Peek at the time of the next scheduled event without advancing.
+   *
+   * @returns The time of the next event, or `null` if no events are scheduled.
+   */
+  nextEventTime(): number | null {
+    this.ensureAlive();
+    return this._handle.nextEventTime();
+  }
+
+  /**
+   * Step until `condition()` returns true.
+   *
+   * @returns The simulation time when the condition became true.
+   * @throws SimulationTimeoutError if `maxSteps` is exceeded.
+   */
+  waitUntil(
+    condition: () => boolean,
+    opts?: { maxSteps?: number },
+  ): number {
+    this.ensureAlive();
+    const max = opts?.maxSteps ?? 100_000;
+    let steps = 0;
+    while (!condition()) {
+      const t = this._handle.step();
+      this._state.dirty = false;
+      if (t == null) break;
+      steps++;
+      if (steps >= max) {
+        throw new SimulationTimeoutError(
+          `waitUntil: condition not met after ${max} steps at time ${this._handle.time()}`,
+          this._handle.time(),
+          steps,
+        );
+      }
+    }
+    return this._handle.time();
+  }
+
+  /**
+   * Wait for `count` rising edges of the given clock.
+   *
+   * Detects actual 0→1 transitions by reading the clock signal directly
+   * from the shared buffer (clock ports are excluded from the DUT proxy).
+   * The clock must have been registered via `addClock`.
+   *
+   * @returns The simulation time after the edges are observed.
+   * @throws SimulationTimeoutError if `maxSteps` is exceeded.
+   */
+  waitForCycles(
+    clock: string,
+    count: number,
+    opts?: { maxSteps?: number },
+  ): number {
+    this.ensureAlive();
+    if (!this._clocks.has(clock)) {
+      throw new Error(
+        `No clock registered for '${clock}'. Call addClock() first.`,
+      );
+    }
+    const sig = this._layout[clock];
+    if (!sig) {
+      throw new Error(`No layout entry for clock '${clock}'.`);
+    }
+    const view = new DataView(this._buffer);
+    const readClk = () => view.getUint8(sig.offset);
+    let prev = readClk();
+    let remaining = count;
+    return this.waitUntil(() => {
+      const curr = readClk();
+      if (prev === 0 && curr !== 0) remaining--;
+      prev = curr;
+      return remaining <= 0;
+    }, opts);
+  }
+
+  /**
+   * Assert and release a reset signal.
+   *
+   * The active level is determined automatically from the Veryl type:
+   * - `reset` / `reset_async_high` / `reset_sync_high` → active-high (1)
+   * - `reset_async_low` / `reset_sync_low` → active-low (0)
+   *
+   * For sync resets (with an associated clock from FfDeclaration), advances
+   * `activeCycles` worth of the associated clock's period using `runUntil`.
+   * For async resets without an associated clock, `duration` must be specified.
+   * An explicit `duration` overrides cycle-based calculation for either type.
+   */
+  reset(
+    signal: string,
+    opts?: { activeCycles?: number; duration?: number },
+  ): void {
+    this.ensureAlive();
+    const sig = this._layout[signal];
+    if (!sig) {
+      throw new Error(
+        `Unknown port '${signal}'. Available: ${Object.keys(this._layout).join(", ")}`,
+      );
+    }
+    const typeKind = sig.typeKind ?? "";
+    if (!typeKind.startsWith("reset")) {
+      throw new Error(
+        `Port '${signal}' is not a reset signal (type_kind: '${typeKind}').`,
+      );
+    }
+    const isActiveLow = typeKind === "reset_async_low" || typeKind === "reset_sync_low";
+    const activeValue = isActiveLow ? 0n : 1n;
+    const inactiveValue = isActiveLow ? 1n : 0n;
+
+    const dut = this._dut as Record<string, unknown>;
+    dut[signal] = activeValue;
+
+    const associatedClock = sig.associatedClock;
+
+    if (opts?.duration != null) {
+      // Explicit duration (works for both sync and async resets)
+      this._handle.runUntil(this._handle.time() + opts.duration);
+    } else if (associatedClock) {
+      // Clock-associated reset → advance by activeCycles
+      const cycles = opts?.activeCycles ?? 2;
+      this.waitForCycles(associatedClock, cycles);
+    } else {
+      // No associated clock and no explicit duration → error
+      throw new Error(
+        `Reset '${signal}' has no associated clock. Specify opts.duration.`,
+      );
+    }
+
+    dut[signal] = inactiveValue;
+    this._state.dirty = false;
+  }
+
+  /**
+   * Read the raw 4-state (value + mask) pair for the named port.
+   */
+  fourState(portName: string): FourStateValue {
+    this.ensureAlive();
+    const sig = this._layout[portName];
+    if (!sig) {
+      throw new Error(
+        `Unknown port '${portName}'. Available: ${Object.keys(this._layout).join(", ")}`,
+      );
+    }
+    const [value, mask] = readFourState(this._buffer, sig);
+    return { __fourState: true, value, mask };
+  }
+
   /** Write current signal values to VCD at the given timestamp. */
   dump(timestamp: number): void {
     this.ensureAlive();

package/src/simulator.test.ts

@@ -11,10 +11,10 @@ import type {
 // ---------------------------------------------------------------------------
 
 interface AdderPorts {
-  rst: number;
-  a: number;
-  b: number;
-  readonly sum: number;
+  rst: bigint;
+  a: bigint;
+  b: bigint;
+  readonly sum: bigint;
 }
 
 const AdderModule: ModuleDefinition<AdderPorts> = {
@@ -80,11 +80,11 @@ describe("Simulator", () => {
       __nativeCreate: mock.create,
     });
 
-    sim.dut.a = 100;
-    sim.dut.b = 200;
+    sim.dut.a = 100n;
+    sim.dut.b = 200n;
     sim.tick();
 
-    expect(sim.dut.sum).toBe(300);
+    expect(sim.dut.sum).toBe(300n);
     expect(mock.handle.tick).toHaveBeenCalledTimes(1);
   });
 
@@ -176,7 +176,7 @@ describe("Simulator", () => {
       __nativeCreate: mock.create,
     });
 
-    sim.dut.a = 100;
+    sim.dut.a = 100n;
     sim.tick();
 
     // After tick, reading output should NOT trigger evalComb