@celox-sim/celox 0.1.4 → 0.1.6

package/src/e2e.test.ts

@@ -13,11 +13,12 @@ import { describe, test, expect, afterEach } from "vitest";
 import { Simulator } from "./simulator.js";
 import { Simulation } from "./simulation.js";
 import { readFourState } from "./dut.js";
-import { X, FourState } from "./types.js";
+import { X, FourState, SimulationTimeoutError } from "./types.js";
 import {
   createSimulatorBridge,
   loadNativeAddon,
   parseNapiLayout,
+  parseSignalPath,
   type RawNapiAddon,
   type RawNapiSimulatorHandle,
 } from "./napi-helpers.js";
@@ -148,11 +149,11 @@ describe("E2E: Simulator.fromSource (event-based)", () => {
 
     const sim = Simulator.fromSource<CounterPorts>(COUNTER_SOURCE, "Counter");
 
-    // Reset the counter
-    sim.dut.rst = 1;
-    sim.tick();
+    // Reset the counter (default async_low: rst=0 is active)
     sim.dut.rst = 0;
     sim.tick();
+    sim.dut.rst = 1;
+    sim.tick();
     expect(sim.dut.count).toBe(0);
 
     // Enable counting
@@ -229,10 +230,10 @@ describe("E2E: Simulation.fromSource (time-based)", () => {
     sim.addClock("clk", { period: 10 });
     expect(sim.time()).toBe(0);
 
-    // Reset
-    sim.dut.rst = 1;
-    sim.runUntil(20);
+    // Reset (default async_low: rst=0 is active)
     sim.dut.rst = 0;
+    sim.runUntil(20);
+    sim.dut.rst = 1;
     sim.dut.en = 1;
 
     sim.runUntil(100);
@@ -282,11 +283,11 @@ describe("E2E: Simulator.fromProject (event-based)", () => {
 
     const sim = Simulator.fromProject<CounterPorts>(COUNTER_PROJECT, "Counter");
 
-    // Reset the counter
-    sim.dut.rst = 1;
-    sim.tick();
+    // Reset the counter (default async_low: rst=0 is active)
     sim.dut.rst = 0;
     sim.tick();
+    sim.dut.rst = 1;
+    sim.tick();
     expect(sim.dut.count).toBe(0);
 
     // Enable counting
@@ -321,10 +322,10 @@ describe("E2E: Simulation.fromProject (time-based)", () => {
     sim.addClock("clk", { period: 10 });
     expect(sim.time()).toBe(0);
 
-    // Reset
-    sim.dut.rst = 1;
-    sim.runUntil(20);
+    // Reset (default async_low: rst=0 is active)
     sim.dut.rst = 0;
+    sim.runUntil(20);
+    sim.dut.rst = 1;
     sim.dut.en = 1;
 
     sim.runUntil(100);
@@ -646,8 +647,8 @@ module InitTest (
     const sigQ = layout.forDut.q;
     const clkEventId = events.clk;
 
-    // 1. Reset: rst=1, d=X
-    view.setUint8(sigRst.offset, 1);
+    // 1. Assert reset (default async_low: rst=0 is active), d=X
+    view.setUint8(sigRst.offset, 0);
     view.setUint8(sigRst.offset + sigRst.byteSize, 0); // rst is defined
 
     view.setUint8(sigD.offset, 0);
@@ -660,8 +661,8 @@ module InitTest (
     expect(vQ1).toBe(0);
     expect(mQ1).toBe(0);
 
-    // 2. Release reset, d = partial X (value=0xA5, mask=0x0F)
-    view.setUint8(sigRst.offset, 0);
+    // 2. Release reset (rst=1 is inactive), d = partial X (value=0xA5, mask=0x0F)
+    view.setUint8(sigRst.offset, 1);
     view.setUint8(sigRst.offset + sigRst.byteSize, 0);
 
     view.setUint8(sigD.offset, 0xA5);
@@ -673,8 +674,8 @@ module InitTest (
     const [, mQ2] = readFourState(buf, sigQ);
     expect(mQ2).toBe(0x0F);
 
-    // 3. Reset again: should clear X
-    view.setUint8(sigRst.offset, 1);
+    // 3. Assert reset again (rst=0): should clear X
+    view.setUint8(sigRst.offset, 0);
     view.setUint8(sigRst.offset + sigRst.byteSize, 0);
 
     raw.tick(clkEventId);
@@ -773,10 +774,11 @@ describe("E2E: 4-state high-level DUT API", () => {
     );
 
     // In 4-state mode, count starts as X. Reset should clear it.
-    sim.dut.rst = 1;
-    sim.tick();
+    // (default async_low: rst=0 is active)
     sim.dut.rst = 0;
     sim.tick();
+    sim.dut.rst = 1;
+    sim.tick();
     expect(sim.dut.count).toBe(0);
 
     // Enable counting — should work exactly like 2-state
@@ -830,10 +832,10 @@ describe("E2E: 4-state high-level DUT API", () => {
 
     const sim = Simulator.fromSource<FFPorts>(FF_SOURCE, "FF", { fourState: true });
 
-    // Reset to clear initial X
-    sim.dut.rst = 1;
-    sim.tick();
+    // Reset to clear initial X (default async_low: rst=0 is active)
     sim.dut.rst = 0;
+    sim.tick();
+    sim.dut.rst = 1;
     expect(sim.dut.q).toBe(0);
 
     // Write a defined value
@@ -895,10 +897,10 @@ describe("E2E: 4-state Simulation (time-based)", () => {
     sim.addClock("clk", { period: 10 });
     expect(sim.time()).toBe(0);
 
-    // Reset to clear initial X on q
-    sim.dut.rst = 1;
-    sim.runUntil(20);
+    // Reset to clear initial X on q (default async_low: rst=0 is active)
     sim.dut.rst = 0;
+    sim.runUntil(20);
+    sim.dut.rst = 1;
     expect(sim.dut.q).toBe(0);
 
     // Drive d with defined value
@@ -927,10 +929,10 @@ describe("E2E: 4-state Simulation (time-based)", () => {
 
     sim.addClock("clk", { period: 10 });
 
-    // Reset
-    sim.dut.rst = 1;
-    sim.runUntil(20);
+    // Reset (default async_low: rst=0 is active)
     sim.dut.rst = 0;
+    sim.runUntil(20);
+    sim.dut.rst = 1;
     sim.dut.en = 1;
 
     sim.runUntil(100);
@@ -963,3 +965,403 @@ describe("E2E: 4-state Simulation (time-based)", () => {
     sim.dispose();
   });
 });
+
+// ---------------------------------------------------------------------------
+// Phase 3b: testbench helpers — Simulation API
+// ---------------------------------------------------------------------------
+
+describe("E2E: Simulation testbench helpers", () => {
+  test("waitForCycles: advances correct number of clock cycles", () => {
+    interface CounterPorts {
+      rst: number;
+      en: number;
+      readonly count: number;
+    }
+
+    const sim = Simulation.fromSource<CounterPorts>(COUNTER_SOURCE, "Counter");
+    sim.addClock("clk", { period: 10 });
+
+    // Reset (default async_low: rst=0 is active)
+    sim.dut.rst = 0;
+    sim.runUntil(20);
+    sim.dut.rst = 1;
+    sim.dut.en = 1;
+
+    const beforeTime = sim.time();
+    const afterTime = sim.waitForCycles("clk", 5);
+
+    expect(afterTime).toBeGreaterThan(beforeTime);
+    // Each cycle = 2 steps with period 10, so 5 cycles ≈ 50 time units
+    expect(afterTime - beforeTime).toBe(50);
+
+    sim.dispose();
+  });
+
+  test("waitUntil: waits for condition to be met", () => {
+    interface CounterPorts {
+      rst: number;
+      en: number;
+      readonly count: number;
+    }
+
+    const sim = Simulation.fromSource<CounterPorts>(COUNTER_SOURCE, "Counter");
+    sim.addClock("clk", { period: 10 });
+
+    // Reset (default async_low: rst=0 is active)
+    sim.dut.rst = 0;
+    sim.runUntil(20);
+    sim.dut.rst = 1;
+    sim.dut.en = 1;
+
+    const t = sim.waitUntil(() => sim.dut.count >= 3);
+    expect(sim.dut.count).toBeGreaterThanOrEqual(3);
+    expect(t).toBeGreaterThan(20);
+
+    sim.dispose();
+  });
+
+  test("waitUntil: throws SimulationTimeoutError on timeout", () => {
+    interface CounterPorts {
+      rst: number;
+      en: number;
+      readonly count: number;
+    }
+
+    const sim = Simulation.fromSource<CounterPorts>(COUNTER_SOURCE, "Counter");
+    sim.addClock("clk", { period: 10 });
+
+    // Reset (default async_low: rst=0 is active)
+    sim.dut.rst = 0;
+    sim.runUntil(20);
+    sim.dut.rst = 1;
+    sim.dut.en = 0; // disabled — count won't increase
+
+    expect(() =>
+      sim.waitUntil(() => sim.dut.count >= 100, { maxSteps: 20 }),
+    ).toThrow(SimulationTimeoutError);
+
+    sim.dispose();
+  });
+
+  test("reset: asserts and releases reset on counter", () => {
+    interface CounterPorts {
+      rst: number;
+      en: number;
+      readonly count: number;
+    }
+
+    const sim = Simulation.fromSource<CounterPorts>(COUNTER_SOURCE, "Counter");
+    sim.addClock("clk", { period: 10 });
+
+    // Count up a bit (default async_low: rst=0 is active)
+    sim.dut.rst = 0;
+    sim.runUntil(20);
+    sim.dut.rst = 1;
+    sim.dut.en = 1;
+    sim.runUntil(100);
+    expect(sim.dut.count).toBeGreaterThan(0);
+
+    // Reset using the helper
+    sim.reset("rst");
+    expect(sim.dut.count).toBe(0);
+
+    sim.dispose();
+  });
+
+  test("reset: explicit async_low resetType activates with 0", () => {
+    interface CounterPorts {
+      rst: number;
+      en: number;
+      readonly count: number;
+    }
+
+    const sim = Simulation.fromSource<CounterPorts>(COUNTER_SOURCE, "Counter", {
+      resetType: "async_low",
+    });
+    sim.addClock("clk", { period: 10 });
+
+    // With async_low, rst=0 is active, rst=1 is inactive
+    sim.reset("rst");
+
+    sim.dut.en = 1;
+    sim.runUntil(100);
+    expect(sim.dut.count).toBeGreaterThan(0);
+
+    // Reset again using helper, verify it resets the counter
+    sim.reset("rst");
+    expect(sim.dut.count).toBe(0);
+
+    sim.dispose();
+  });
+
+  test("reset: explicit async_high resetType activates with 1", () => {
+    interface CounterPorts {
+      rst: number;
+      en: number;
+      readonly count: number;
+    }
+
+    const sim = Simulation.fromSource<CounterPorts>(COUNTER_SOURCE, "Counter", {
+      resetType: "async_high",
+    });
+    sim.addClock("clk", { period: 10 });
+
+    // With async_high, rst=1 is active, rst=0 is inactive
+    sim.reset("rst");
+
+    sim.dut.en = 1;
+    sim.runUntil(100);
+    expect(sim.dut.count).toBeGreaterThan(0);
+
+    // Reset again
+    sim.reset("rst");
+    expect(sim.dut.count).toBe(0);
+
+    sim.dispose();
+  });
+
+  test("Simulator.fromSource: resetType option works", () => {
+    interface CounterPorts {
+      rst: number;
+      en: number;
+      readonly count: number;
+    }
+
+    const sim = Simulator.fromSource<CounterPorts>(COUNTER_SOURCE, "Counter", {
+      resetType: "async_high",
+    });
+
+    // With async_high, assert reset with 1
+    sim.dut.rst = 1;
+    sim.tick();
+    sim.dut.rst = 0;
+    sim.tick();
+    expect(sim.dut.count).toBe(0);
+
+    // Count up
+    sim.dut.en = 1;
+    sim.tick();
+    expect(sim.dut.count).toBe(1);
+
+    sim.dispose();
+  });
+
+  test("runUntil with maxSteps: succeeds within budget", () => {
+    interface CounterPorts {
+      rst: number;
+      en: number;
+      readonly count: number;
+    }
+
+    const sim = Simulation.fromSource<CounterPorts>(COUNTER_SOURCE, "Counter");
+    sim.addClock("clk", { period: 10 });
+
+    // Reset (default async_low: rst=0 is active)
+    sim.dut.rst = 0;
+    sim.runUntil(20);
+    sim.dut.rst = 1;
+    sim.dut.en = 1;
+
+    // 100 time units with period 10 = 10 events, should fit in 100 steps
+    sim.runUntil(120, { maxSteps: 100 });
+    expect(sim.time()).toBe(120);
+
+    sim.dispose();
+  });
+
+  test("runUntil with maxSteps: throws on exceeded budget", () => {
+    interface CounterPorts {
+      rst: number;
+      en: number;
+      readonly count: number;
+    }
+
+    const sim = Simulation.fromSource<CounterPorts>(COUNTER_SOURCE, "Counter");
+    sim.addClock("clk", { period: 10 });
+
+    // Release reset so counter can count (default async_low: rst=1 is inactive)
+    sim.dut.rst = 1;
+    sim.dut.en = 1;
+
+    // Very small budget for a long run
+    expect(() => sim.runUntil(100000, { maxSteps: 5 })).toThrow(
+      SimulationTimeoutError,
+    );
+
+    sim.dispose();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Phase 3b: fourState() method
+// ---------------------------------------------------------------------------
+
+describe("E2E: fourState() method", () => {
+  test("Simulator.fourState: reads 4-state value and mask", () => {
+    interface Ports {
+      a: number;
+      b: number;
+      readonly y: number;
+    }
+
+    const sim = Simulator.fromSource<Ports>(ADDER_4STATE_SOURCE, "Adder4S", {
+      fourState: true,
+    });
+
+    sim.dut.a = 100;
+    sim.dut.b = 55;
+    // Trigger evalComb via output read (Adder4S is purely combinational)
+    expect(sim.dut.y).toBe(155);
+
+    const fs = sim.fourState("y");
+    expect(fs.__fourState).toBe(true);
+    expect(fs.value).toBe(155);
+    expect(fs.mask).toBe(0);
+
+    sim.dispose();
+  });
+
+  test("Simulator.fourState: reads X mask when input is X", () => {
+    interface Ports {
+      a: number;
+      b: number;
+      readonly y: number;
+    }
+
+    const sim = Simulator.fromSource<Ports>(ADDER_4STATE_SOURCE, "Adder4S", {
+      fourState: true,
+    });
+
+    (sim.dut as any).a = X;
+    sim.dut.b = 10;
+    // Trigger evalComb via output read
+    sim.dut.y;
+
+    const fs = sim.fourState("y");
+    expect(fs.mask).toBe(0xFF); // all X from arithmetic propagation
+
+    sim.dispose();
+  });
+
+  test("Simulation.fourState: reads 4-state value", () => {
+    interface Ports {
+      a: number;
+      b: number;
+      readonly y: number;
+    }
+
+    const sim = Simulation.fromSource<Ports>(ADDER_4STATE_SOURCE, "Adder4S", {
+      fourState: true,
+    });
+
+    sim.dut.a = 50;
+    sim.dut.b = 25;
+    sim.runUntil(0);
+
+    const fs = sim.fourState("y");
+    expect(fs.value).toBe(75);
+    expect(fs.mask).toBe(0);
+
+    sim.dispose();
+  });
+
+  test("fourState: throws for unknown port", () => {
+    interface Ports {
+      a: number;
+      b: number;
+      readonly y: number;
+    }
+
+    const sim = Simulator.fromSource<Ports>(ADDER_4STATE_SOURCE, "Adder4S", {
+      fourState: true,
+    });
+
+    expect(() => sim.fourState("nonexistent")).toThrow("Unknown port");
+
+    sim.dispose();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Phase 3b: optimize flag
+// ---------------------------------------------------------------------------
+
+describe("E2E: optimize flag", () => {
+  test("Simulator.fromSource with optimize: true", () => {
+    interface AdderPorts {
+      rst: number;
+      a: number;
+      b: number;
+      readonly sum: number;
+    }
+
+    const sim = Simulator.fromSource<AdderPorts>(ADDER_SOURCE, "Adder", {
+      optimize: true,
+    });
+
+    sim.dut.a = 100;
+    sim.dut.b = 200;
+    sim.tick();
+    expect(sim.dut.sum).toBe(300);
+
+    sim.dispose();
+  });
+
+  test("Simulation.fromSource with optimize: true", () => {
+    interface CounterPorts {
+      rst: number;
+      en: number;
+      readonly count: number;
+    }
+
+    const sim = Simulation.fromSource<CounterPorts>(COUNTER_SOURCE, "Counter", {
+      optimize: true,
+    });
+
+    sim.addClock("clk", { period: 10 });
+
+    // Reset (default async_low: rst=0 is active)
+    sim.dut.rst = 0;
+    sim.runUntil(20);
+    sim.dut.rst = 1;
+    sim.dut.en = 1;
+    sim.runUntil(100);
+
+    expect(sim.dut.count).toBeGreaterThan(0);
+
+    sim.dispose();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// parseSignalPath unit tests
+// ---------------------------------------------------------------------------
+
+describe("parseSignalPath", () => {
+  test("simple variable path", () => {
+    const result = parseSignalPath("v");
+    expect(result.instancePath).toEqual([]);
+    expect(result.varPath).toEqual(["v"]);
+  });
+
+  test("instance:variable split", () => {
+    const result = parseSignalPath("p2:i");
+    expect(result.instancePath).toEqual([{ name: "p2", index: 0 }]);
+    expect(result.varPath).toEqual(["i"]);
+  });
+
+  test("nested instance with array index", () => {
+    const result = parseSignalPath("a.b[3]:x.y");
+    expect(result.instancePath).toEqual([
+      { name: "a", index: 0 },
+      { name: "b", index: 3 },
+    ]);
+    expect(result.varPath).toEqual(["x", "y"]);
+  });
+
+  test("dotted variable path without instance", () => {
+    const result = parseSignalPath("foo.bar.baz");
+    expect(result.instancePath).toEqual([]);
+    expect(result.varPath).toEqual(["foo", "bar", "baz"]);
+  });
+});

package/src/index.ts

@@ -15,6 +15,8 @@ export type {
   SimulatorOptions,
   EventHandle,
   FourStateValue,
+  LoopBreak,
+  TrueLoopSpec,
 } from "./types.js";
 
 /** @internal */
@@ -29,6 +31,9 @@ export type {
 // 4-state helpers
 export { X, FourState, isFourStateValue } from "./types.js";
 
+// Error types
+export { SimulationTimeoutError } from "./types.js";
+
 // Simulator (event-based)
 export { Simulator } from "./simulator.js";
 
@@ -36,7 +41,7 @@ export { Simulator } from "./simulator.js";
 export { Simulation } from "./simulation.js";
 
 /** @internal */
-export { createDut, readFourState } from "./dut.js";
+export { createDut, createChildDut, readFourState } from "./dut.js";
 /** @internal */
 export type { DirtyState } from "./dut.js";
 
@@ -44,14 +49,17 @@ export type { DirtyState } from "./dut.js";
 export {
   loadNativeAddon,
   parseNapiLayout,
+  parseHierarchyLayout,
   buildPortsFromLayout,
   wrapDirectSimulatorHandle,
   wrapDirectSimulationHandle,
   createSimulatorBridge,
   createSimulationBridge,
+  parseSignalPath,
+  buildNapiOpts,
 } from "./napi-helpers.js";
 /** @internal */
-export type { RawNapiAddon, RawNapiSimulatorHandle, RawNapiSimulationHandle } from "./napi-helpers.js";
+export type { HierarchyNode, RawNapiAddon, RawNapiSimulatorHandle, RawNapiSimulationHandle } from "./napi-helpers.js";
 
 // NAPI bridge (backward compat — re-exports from napi-helpers)
 // Consumers that import from "./napi-bridge.js" still work.