@celox-sim/celox 0.1.5 → 0.1.6

package/src/napi-helpers.ts

@@ -11,11 +11,13 @@
 
 import type {
   CreateResult,
+  LoopBreak,
   NativeSimulatorHandle,
   NativeSimulationHandle,
   PortInfo,
   SignalLayout,
   SimulatorOptions,
+  TrueLoopSpec,
 } from "./types.js";
 import type { NativeCreateFn } from "./simulator.js";
 import type { NativeCreateSimulationFn } from "./simulation.js";
@@ -27,6 +29,7 @@ import type { NativeCreateSimulationFn } from "./simulation.js";
 export interface RawNapiSimulatorHandle {
   readonly layoutJson: string;
   readonly eventsJson: string;
+  readonly hierarchyJson: string;
   readonly stableSize: number;
   readonly totalSize: number;
   tick(eventId: number): void;
@@ -40,6 +43,7 @@ export interface RawNapiSimulatorHandle {
 export interface RawNapiSimulationHandle {
   readonly layoutJson: string;
   readonly eventsJson: string;
+  readonly hierarchyJson: string;
   readonly stableSize: number;
   readonly totalSize: number;
   addClock(eventId: number, period: number, initialDelay: number): void;
@@ -47,14 +51,42 @@ export interface RawNapiSimulationHandle {
   runUntil(endTime: number): void;
   step(): number | null;
   time(): number;
+  nextEventTime(): number | null;
   evalComb(): void;
   dump(timestamp: number): void;
   sharedMemory(): Uint8Array;
   dispose(): void;
 }
 
+export interface NapiFalseLoop {
+  from: NapiSignalPath;
+  to: NapiSignalPath;
+}
+
+export interface NapiTrueLoop {
+  from: NapiSignalPath;
+  to: NapiSignalPath;
+  maxIter: number;
+}
+
+export interface NapiSignalPath {
+  instancePath: NapiInstanceSegment[];
+  varPath: string[];
+}
+
+export interface NapiInstanceSegment {
+  name: string;
+  index: number;
+}
+
 export interface NapiOptions {
   fourState?: boolean;
+  vcd?: string;
+  optimize?: boolean;
+  falseLoops?: NapiFalseLoop[];
+  trueLoops?: NapiTrueLoop[];
+  clockType?: string;
+  resetType?: string;
 }
 
 export interface RawNapiAddon {
@@ -102,6 +134,98 @@ export function loadNativeAddon(addonPath?: string): RawNapiAddon {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Signal path parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a signal path string into instance-path + var-path components.
+ *
+ * Format: `instanceSeg1.instanceSeg2:varSeg1.varSeg2`
+ *   - `:` separates instance path from variable path
+ *   - Without `:`, the whole string is the variable path
+ *   - Instance segments may include `[N]` array indices
+ *
+ * Examples:
+ *   - `"v"` → { instancePath: [], varPath: ["v"] }
+ *   - `"p2:i"` → { instancePath: [{name:"p2",index:0}], varPath: ["i"] }
+ *   - `"a.b[3]:x.y"` → { instancePath: [{name:"a",index:0},{name:"b",index:3}], varPath: ["x","y"] }
+ */
+export function parseSignalPath(path: string): NapiSignalPath {
+  const colonIdx = path.indexOf(":");
+  if (colonIdx < 0) {
+    return { instancePath: [], varPath: path.split(".") };
+  }
+
+  const instPart = path.slice(0, colonIdx);
+  const varPart = path.slice(colonIdx + 1);
+
+  const instancePath: NapiInstanceSegment[] = [];
+  if (instPart.length > 0) {
+    for (const seg of instPart.split(".")) {
+      const bracketIdx = seg.indexOf("[");
+      if (bracketIdx >= 0) {
+        const name = seg.slice(0, bracketIdx);
+        const index = Number.parseInt(seg.slice(bracketIdx + 1, -1), 10);
+        instancePath.push({ name, index });
+      } else {
+        instancePath.push({ name: seg, index: 0 });
+      }
+    }
+  }
+
+  return { instancePath, varPath: varPart.split(".") };
+}
+
+/**
+ * Build NapiOptions from SimulatorOptions.
+ * Returns `undefined` when no options are set (to skip the NAPI options arg).
+ */
+export function buildNapiOpts(options?: SimulatorOptions): NapiOptions | undefined {
+  if (!options) return undefined;
+
+  const napiOpts: NapiOptions = {};
+  let hasOpt = false;
+
+  if (options.fourState) {
+    napiOpts.fourState = options.fourState;
+    hasOpt = true;
+  }
+  if (options.vcd) {
+    napiOpts.vcd = options.vcd;
+    hasOpt = true;
+  }
+  if (options.optimize != null) {
+    napiOpts.optimize = options.optimize;
+    hasOpt = true;
+  }
+  if (options.falseLoops && options.falseLoops.length > 0) {
+    napiOpts.falseLoops = options.falseLoops.map((lb: LoopBreak) => ({
+      from: parseSignalPath(lb.from),
+      to: parseSignalPath(lb.to),
+    }));
+    hasOpt = true;
+  }
+  if (options.trueLoops && options.trueLoops.length > 0) {
+    napiOpts.trueLoops = options.trueLoops.map((tl: TrueLoopSpec) => ({
+      from: parseSignalPath(tl.from),
+      to: parseSignalPath(tl.to),
+      maxIter: tl.maxIter,
+    }));
+    hasOpt = true;
+  }
+  if (options.clockType) {
+    napiOpts.clockType = options.clockType;
+    hasOpt = true;
+  }
+  if (options.resetType) {
+    napiOpts.resetType = options.resetType;
+    hasOpt = true;
+  }
+
+  return hasOpt ? napiOpts : undefined;
+}
+
 // ---------------------------------------------------------------------------
 // Layout parsing helpers
 // ---------------------------------------------------------------------------
@@ -114,6 +238,7 @@ interface RawSignalLayout {
   direction: string;
   type_kind: string;
   array_dims?: number[];
+  associated_clock?: string;
 }
 
 /**
@@ -122,11 +247,11 @@ interface RawSignalLayout {
  * the DUT-compatible layout (without type_kind).
  */
 export function parseNapiLayout(json: string): {
-  signals: Record<string, SignalLayout & { typeKind: string; arrayDims?: number[] }>;
+  signals: Record<string, SignalLayout & { typeKind: string; arrayDims?: number[]; associatedClock?: string }>;
   forDut: Record<string, SignalLayout>;
 } {
   const raw: Record<string, RawSignalLayout> = JSON.parse(json);
-  const signals: Record<string, SignalLayout & { typeKind: string; arrayDims?: number[] }> = {};
+  const signals: Record<string, SignalLayout & { typeKind: string; arrayDims?: number[]; associatedClock?: string }> = {};
   const forDut: Record<string, SignalLayout> = {};
 
   for (const [name, r] of Object.entries(raw)) {
@@ -137,13 +262,16 @@ export function parseNapiLayout(json: string): {
       is4state: r.is_4state,
       direction: r.direction as "input" | "output" | "inout",
     };
-    const entry: SignalLayout & { typeKind: string; arrayDims?: number[] } = {
+    const entry: SignalLayout & { typeKind: string; arrayDims?: number[]; associatedClock?: string } = {
       ...sl,
       typeKind: r.type_kind,
     };
     if (r.array_dims && r.array_dims.length > 0) {
       entry.arrayDims = r.array_dims;
     }
+    if (r.associated_clock) {
+      entry.associatedClock = r.associated_clock;
+    }
     signals[name] = entry;
     forDut[name] = sl;
   }
@@ -164,19 +292,14 @@ export function buildPortsFromLayout(
   for (const [name, sig] of Object.entries(signals)) {
     const typeKind = sig.typeKind;
     let portType: "clock" | "reset" | "logic" | "bit";
-    switch (typeKind) {
-      case "clock":
-        portType = "clock";
-        break;
-      case "reset":
-        portType = "reset";
-        break;
-      case "bit":
-        portType = "bit";
-        break;
-      default:
-        portType = "logic";
-        break;
+    if (typeKind === "clock") {
+      portType = "clock";
+    } else if (typeKind.startsWith("reset")) {
+      portType = "reset";
+    } else if (typeKind === "bit") {
+      portType = "bit";
+    } else {
+      portType = "logic";
     }
 
     const port: PortInfo = {
@@ -194,6 +317,78 @@ export function buildPortsFromLayout(
   return ports;
 }
 
+// ---------------------------------------------------------------------------
+// Hierarchy layout
+// ---------------------------------------------------------------------------
+
+export interface HierarchyNode {
+  moduleName: string;
+  signals: Record<string, SignalLayout & { typeKind: string; arrayDims?: number[] }>;
+  forDut: Record<string, SignalLayout>;
+  ports: Record<string, PortInfo>;
+  children: Record<string, HierarchyNode[]>;
+}
+
+interface RawHierarchyNode {
+  module_name: string;
+  signals: Record<string, RawSignalLayout>;
+  children: Record<string, RawHierarchyNode[]>;
+}
+
+/**
+ * Parse the hierarchy JSON from NAPI into a HierarchyNode tree.
+ * Converts snake_case keys to camelCase and auto-detects ports.
+ */
+export function parseHierarchyLayout(
+  json: string,
+  events: Record<string, number>,
+): HierarchyNode {
+  const raw: RawHierarchyNode = JSON.parse(json);
+  return convertHierarchyNode(raw, events);
+}
+
+function convertHierarchyNode(
+  raw: RawHierarchyNode,
+  events: Record<string, number>,
+): HierarchyNode {
+  const signals: Record<string, SignalLayout & { typeKind: string; arrayDims?: number[] }> = {};
+  const forDut: Record<string, SignalLayout> = {};
+
+  for (const [name, r] of Object.entries(raw.signals)) {
+    const sl: SignalLayout = {
+      offset: r.offset,
+      width: r.width,
+      byteSize: r.byte_size > 0 ? r.byte_size : Math.ceil(r.width / 8),
+      is4state: r.is_4state,
+      direction: r.direction as "input" | "output" | "inout",
+    };
+    const entry: SignalLayout & { typeKind: string; arrayDims?: number[] } = {
+      ...sl,
+      typeKind: r.type_kind,
+    };
+    if (r.array_dims && r.array_dims.length > 0) {
+      entry.arrayDims = r.array_dims;
+    }
+    signals[name] = entry;
+    forDut[name] = sl;
+  }
+
+  const ports = buildPortsFromLayout(signals, events);
+
+  const children: Record<string, HierarchyNode[]> = {};
+  for (const [name, instances] of Object.entries(raw.children)) {
+    children[name] = instances.map((inst) => convertHierarchyNode(inst, events));
+  }
+
+  return {
+    moduleName: raw.module_name,
+    signals,
+    forDut,
+    ports,
+    children,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Handle wrapping — zero-copy direct operations
 // ---------------------------------------------------------------------------
@@ -246,6 +441,9 @@ export function wrapDirectSimulationHandle(
     time(): number {
       return raw.time();
     },
+    nextEventTime(): number | null {
+      return raw.nextEventTime();
+    },
     evalComb(): void {
       raw.evalComb();
     },
@@ -289,17 +487,19 @@ export function createSimulatorBridge(addon: RawNapiAddon): NativeCreateFn {
   return (
     source: string,
     moduleName: string,
-    _options: SimulatorOptions,
+    options: SimulatorOptions,
   ): CreateResult<NativeSimulatorHandle> => {
-    const raw = new addon.NativeSimulatorHandle(source, moduleName);
+    const napiOpts = buildNapiOpts(options);
+    const raw = new addon.NativeSimulatorHandle(source, moduleName, napiOpts);
 
     const layout = parseLegacyLayout(raw.layoutJson);
     const events: Record<string, number> = JSON.parse(raw.eventsJson);
+    const hierarchy = parseHierarchyLayout(raw.hierarchyJson, events);
 
     const buf = raw.sharedMemory().buffer;
     const handle = wrapDirectSimulatorHandle(raw);
 
-    return { buffer: buf, layout, events, handle };
+    return { buffer: buf, layout, events, handle, hierarchy };
   };
 }
 
@@ -311,16 +511,18 @@ export function createSimulationBridge(addon: RawNapiAddon): NativeCreateSimulat
   return (
     source: string,
     moduleName: string,
-    _options: SimulatorOptions,
+    options: SimulatorOptions,
   ): CreateResult<NativeSimulationHandle> => {
-    const raw = new addon.NativeSimulationHandle(source, moduleName);
+    const napiOpts = buildNapiOpts(options);
+    const raw = new addon.NativeSimulationHandle(source, moduleName, napiOpts);
 
     const layout = parseLegacyLayout(raw.layoutJson);
     const events: Record<string, number> = JSON.parse(raw.eventsJson);
+    const hierarchy = parseHierarchyLayout(raw.hierarchyJson, events);
 
     const buf = raw.sharedMemory().buffer;
     const handle = wrapDirectSimulationHandle(raw);
 
-    return { buffer: buf, layout, events, handle };
+    return { buffer: buf, layout, events, handle, hierarchy };
   };
 }

package/src/simulation.test.ts

@@ -5,6 +5,7 @@ import type {
   ModuleDefinition,
   NativeSimulationHandle,
 } from "./types.js";
+import { SimulationTimeoutError } from "./types.js";
 
 // ---------------------------------------------------------------------------
 // Mock helpers
@@ -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,
@@ -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 = 42;
+    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");
+  });
 });