@celox-sim/celox 0.1.5 → 0.1.7

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. */
@@ -221,12 +234,16 @@ export class Simulator<P = Record<string, unknown>> {
       ticks = 1;
     }
 
+    if (this._state.dirty) {
+      this._handle.evalComb();
+      this._state.dirty = false;
+    }
+
     if (ticks === 1) {
       this._handle.tick(eventId);
     } else if (ticks > 1) {
       this._handle.tickN(eventId, ticks);
     }
-    this._state.dirty = false;
   }
 
   /** Resolve an event name to a handle for use with `tick()`. */
@@ -240,6 +257,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";
 }
 
 // ---------------------------------------------------------------------------
@@ -143,8 +160,8 @@ export const X = Symbol.for("veryl:X");
 /** A 4-state value with explicit bit-level mask. */
 export interface FourStateValue {
   readonly __fourState: true;
-  readonly value: number | bigint;
-  readonly mask: number | bigint;
+  readonly value: bigint;
+  readonly mask: bigint;
 }
 
 /** Construct a 4-state value. Mask bits set to 1 indicate X. */
@@ -152,7 +169,7 @@ export function FourState(
   value: number | bigint,
   mask: number | bigint,
 ): FourStateValue {
-  return { __fourState: true, value, mask };
+  return { __fourState: true, value: BigInt(value), mask: BigInt(mask) };
 }
 
 export function isFourStateValue(v: unknown): v is FourStateValue {
@@ -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;
+}