@celox-sim/celox 0.1.4 → 0.1.6

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 ? 0 : 1;
+    const inactiveValue = isActiveLow ? 1 : 0;
+
+    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.ts

@@ -8,16 +8,20 @@
 import type {
   CreateResult,
   EventHandle,
+  FourStateValue,
   ModuleDefinition,
   NativeSimulatorHandle,
+  SignalLayout,
   SimulatorOptions,
 } from "./types.js";
-import { createDut, type DirtyState } from "./dut.js";
+import { createDut, readFourState, type DirtyState } from "./dut.js";
 import {
   loadNativeAddon,
   parseNapiLayout,
+  parseHierarchyLayout,
   buildPortsFromLayout,
   wrapDirectSimulatorHandle,
+  buildNapiOpts,
 } from "./napi-helpers.js";
 
 /**
@@ -54,6 +58,8 @@ export class Simulator<P = Record<string, unknown>> {
   private readonly _events: Record<string, number>;
   private readonly _defaultEventId: number;
   private readonly _state: DirtyState;
+  private readonly _buffer: ArrayBuffer | SharedArrayBuffer;
+  private readonly _layout: Record<string, SignalLayout>;
   private _disposed = false;
 
   private constructor(
@@ -61,11 +67,15 @@ export class Simulator<P = Record<string, unknown>> {
     dut: P,
     events: Record<string, number>,
     state: DirtyState,
+    buffer: ArrayBuffer | SharedArrayBuffer,
+    layout: Record<string, SignalLayout>,
   ) {
     this._handle = handle;
     this._dut = dut;
     this._events = events;
     this._state = state;
+    this._buffer = buffer;
+    this._layout = layout;
     const keys = Object.keys(events);
     this._defaultEventId = keys.length > 0 ? events[keys[0]!]! : -1;
   }
@@ -98,8 +108,8 @@ export class Simulator<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>(
@@ -108,9 +118,10 @@ export class Simulator<P = Record<string, unknown>> {
       module.ports,
       result.handle,
       state,
+      result.hierarchy,
     );
 
-    return new Simulator<P>(result.handle, dut, result.events, state);
+    return new Simulator<P>(result.handle, dut, result.events, state, result.buffer, result.layout);
   }
 
   /**
@@ -133,11 +144,12 @@ export class Simulator<P = Record<string, unknown>> {
     options?: SimulatorOptions & { nativeAddonPath?: string },
   ): Simulator<P> {
     const addon = loadNativeAddon(options?.nativeAddonPath);
-    const napiOpts = options?.fourState ? { fourState: options.fourState } : undefined;
+    const napiOpts = buildNapiOpts(options);
     const raw = new addon.NativeSimulatorHandle(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);
 
@@ -145,9 +157,9 @@ export class Simulator<P = Record<string, unknown>> {
 
     const state: DirtyState = { dirty: false };
     const handle = wrapDirectSimulatorHandle(raw);
-    const dut = createDut<P>(buf, layout.forDut, ports, handle, state);
+    const dut = createDut<P>(buf, layout.forDut, ports, handle, state, hierarchy);
 
-    return new Simulator<P>(handle, dut, events, state);
+    return new Simulator<P>(handle, dut, events, state, buf, layout.forDut);
   }
 
   /**
@@ -167,11 +179,12 @@ export class Simulator<P = Record<string, unknown>> {
     options?: SimulatorOptions & { nativeAddonPath?: string },
   ): Simulator<P> {
     const addon = loadNativeAddon(options?.nativeAddonPath);
-    const napiOpts = options?.fourState ? { fourState: options.fourState } : undefined;
+    const napiOpts = buildNapiOpts(options);
     const raw = addon.NativeSimulatorHandle.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);
 
@@ -179,9 +192,9 @@ export class Simulator<P = Record<string, unknown>> {
 
     const state: DirtyState = { dirty: false };
     const handle = wrapDirectSimulatorHandle(raw);
-    const dut = createDut<P>(buf, layout.forDut, ports, handle, state);
+    const dut = createDut<P>(buf, layout.forDut, ports, handle, state, hierarchy);
 
-    return new Simulator<P>(handle, dut, events, state);
+    return new Simulator<P>(handle, dut, events, state, buf, layout.forDut);
   }
 
   /** The DUT accessor object — read/write ports as plain properties. */
@@ -240,6 +253,21 @@ export class Simulator<P = Record<string, unknown>> {
     return { name, id };
   }
 
+  /**
+   * 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/types.ts

@@ -58,6 +58,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;
 }
 
 // ---------------------------------------------------------------------------
@@ -86,6 +90,7 @@ export interface NativeSimulationHandle {
   runUntil(endTime: number): void;
   step(): number | null;
   time(): number;
+  nextEventTime(): number | null;
   evalComb(): void;
   dump(timestamp: number): void;
   dispose(): void;
@@ -110,6 +115,8 @@ 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;
 }
 
 // ---------------------------------------------------------------------------
@@ -121,6 +128,16 @@ export interface SimulatorOptions {
   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";
 }
 
 // ---------------------------------------------------------------------------
@@ -162,3 +179,37 @@ export function isFourStateValue(v: unknown): v is FourStateValue {
     (v as FourStateValue).__fourState === true
   );
 }
+
+// ---------------------------------------------------------------------------
+// Simulation timeout error
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown when a simulation helper exceeds its step budget.
+ */
+export class SimulationTimeoutError extends Error {
+  readonly time: number;
+  readonly steps: number;
+
+  constructor(message: string, time: number, steps: number) {
+    super(message);
+    this.name = "SimulationTimeoutError";
+    this.time = time;
+    this.steps = steps;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Loop-break types (for Phase 3c)
+// ---------------------------------------------------------------------------
+
+/** 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;
+}