@celox-sim/celox 0.1.10 → 0.1.12

package/src/e2e.test.ts

@@ -27,6 +27,7 @@ import {
 const FIXTURES_DIR = path.resolve(import.meta.dirname ?? __dirname, "../fixtures");
 const ADDER_PROJECT = path.join(FIXTURES_DIR, "adder");
 const COUNTER_PROJECT = path.join(FIXTURES_DIR, "counter_project");
+const CELOX_TOML_PROJECT = path.join(FIXTURES_DIR, "celox_toml");
 
 // ---------------------------------------------------------------------------
 // Test Veryl sources
@@ -496,9 +497,9 @@ module InitTest (
     const layout = parseNapiLayout(raw.layoutJson);
     const buf = raw.sharedMemory().buffer;
 
-    // logic port should have mask=0xFF (all X)
+    // logic port should have mask=0xFF (all X), X encoding: v=1, m=1
     const [valA, maskA] = readFourState(buf, layout.forDut.a);
-    expect(valA).toBe(0n);
+    expect(valA).toBe(0xFFn);
     expect(maskA).toBe(0xFFn);
 
     // bit port should have mask=0 (defined)
@@ -811,6 +812,11 @@ describe("E2E: 4-state high-level DUT API", () => {
     // In 4-state mode, count starts as X. Reset should clear it.
     // (default async_low: rst=0 is active)
     sim.dut.rst = 0n;
+    // Clear X on en before deactivating reset. In 4-state mode, en starts
+    // as X (v=1, m=1). The FF branch condition currently uses only the value
+    // bit, so X with v=1 is treated as "true" — a known limitation in FF
+    // conditional handling (combinational mux handles X correctly).
+    sim.dut.en = 0n;
     sim.tick();
     sim.dut.rst = 1n;
     sim.tick();
@@ -1654,3 +1660,366 @@ describe("E2E: parameter override — DUT correctness", () => {
     sim.dispose();
   });
 });
+
+// ---------------------------------------------------------------------------
+// celox.toml: test-only source directories
+// ---------------------------------------------------------------------------
+
+describe("E2E: celox.toml test sources", () => {
+  test("fromProject loads test-only module declared in celox.toml", () => {
+    interface RegPorts {
+      rst: bigint;
+      d: bigint;
+      readonly q: bigint;
+    }
+
+    // `Reg` lives in test_veryl/ — not in Veryl.toml sources — but celox.toml
+    // declares test_veryl/ as an additional test source directory.
+    const sim = Simulator.fromProject<RegPorts>(CELOX_TOML_PROJECT, "Reg");
+
+    // Deassert async_low reset (rst=0 is active; rst=1 is normal operation)
+    sim.dut.rst = 1n;
+    sim.dut.d = 0xABn;
+    sim.tick();
+    expect(sim.dut.q).toBe(0xABn);
+
+    sim.dut.d = 0xCDn;
+    expect(sim.dut.q).toBe(0xABn); // not yet clocked
+    sim.tick();
+    expect(sim.dut.q).toBe(0xCDn);
+
+    sim.dispose();
+  });
+
+  test("genTs includes test-only module declared in celox.toml", () => {
+    const addon = loadNativeAddon();
+    const json = addon.genTs(CELOX_TOML_PROJECT);
+    const output = JSON.parse(json) as { modules: Array<{ moduleName: string }> };
+    const names = output.modules.map((m) => m.moduleName);
+    // Both the regular source (Adder) and the test-only source (Reg) must appear
+    expect(names).toContain("Adder");
+    expect(names).toContain("Reg");
+  });
+
+  test("[simulation] max_steps from celox.toml is used as waitUntil default", () => {
+    // celox.toml sets [simulation] max_steps = 20; waitUntil should honour it
+    // when no per-call maxSteps is provided.
+    const sim = Simulation.fromProject(CELOX_TOML_PROJECT, "Reg");
+    sim.addClock("clk", { period: 10 });
+    expect(() => sim.waitUntil(() => false)).toThrow(SimulationTimeoutError);
+    const err = (() => {
+      try { sim.waitUntil(() => false); } catch (e) { return e; }
+    })() as SimulationTimeoutError;
+    expect(err.steps).toBe(20);
+    sim.dispose();
+  });
+
+  test("[simulation] max_steps per-call override takes precedence over celox.toml", () => {
+    const sim = Simulation.fromProject(CELOX_TOML_PROJECT, "Reg");
+    sim.addClock("clk", { period: 10 });
+    // Per-call maxSteps=5 is lower than the toml default of 20
+    expect(() => sim.waitUntil(() => false, { maxSteps: 5 })).toThrow(SimulationTimeoutError);
+    const err = (() => {
+      try { sim.waitUntil(() => false, { maxSteps: 5 }); } catch (e) { return e; }
+    })() as SimulationTimeoutError;
+    expect(err.steps).toBe(5);
+    sim.dispose();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Interface port DUT accessor tests
+// ---------------------------------------------------------------------------
+
+// A module whose top-level port is a modport interface.
+// After Veryl expansion "sig.data" and "sig.valid" become individual ports.
+// buildPortsFromLayout must group them into a nested PortInfo so that the
+// DUT exposes them as dut.sig.data / dut.sig.valid.
+const INTERFACE_PORT_SOURCE = `
+interface Signal {
+    var data:  logic<8>;
+    var valid: logic;
+    modport src {
+        data:  output,
+        valid: output,
+    }
+    modport dst {
+        data:  input,
+        valid: input,
+    }
+}
+
+module Top (
+    sig: modport Signal::dst,
+    out: output logic<8>,
+) {
+    assign out = sig.data;
+}
+`;
+
+// A module that uses two instances connected via an interface so we can verify
+// that the hierarchy DUT also exposes nested accessors correctly.
+const INTERFACE_HIERARCHY_SOURCE = `
+interface Bus {
+    var data:  logic<8>;
+    var valid: logic;
+    modport producer {
+        data:  output,
+        valid: output,
+    }
+    modport consumer {
+        data:  input,
+        valid: input,
+    }
+}
+
+module Producer (
+    bus: modport Bus::producer,
+    val: input logic<8>,
+) {
+    assign bus.data  = val;
+    assign bus.valid = 1'b1;
+}
+
+module Consumer (
+    bus:  modport Bus::consumer,
+    out:  output logic<8>,
+    got:  output logic,
+) {
+    assign out = bus.data;
+    assign got = bus.valid;
+}
+
+module Top (
+    val: input  logic<8>,
+    out: output logic<8>,
+    got: output logic,
+) {
+    inst b:   Bus;
+    inst p:   Producer (bus: b, val: val);
+    inst c:   Consumer (bus: b, out: out, got: got);
+}
+`;
+
+describe("E2E: interface port DUT accessor", () => {
+  test("top-level interface port members accessible as nested dut properties", () => {
+    interface TopPorts {
+      sig: { data: bigint; valid: bigint };
+      readonly out: bigint;
+    }
+
+    const sim = Simulator.fromSource<TopPorts>(INTERFACE_PORT_SOURCE, "Top");
+
+    sim.dut.sig.data = 0x42n;
+    expect(sim.dut.out).toBe(0x42n);
+
+    sim.dut.sig.data = 0xFFn;
+    expect(sim.dut.out).toBe(0xFFn);
+
+    sim.dut.sig.data = 0x00n;
+    expect(sim.dut.out).toBe(0x00n);
+
+    sim.dispose();
+  });
+
+  test("writing to interface output member throws", () => {
+    // bus.data / bus.valid are outputs of Top — writing should throw.
+    const PRODUCER_ONLY = `
+interface Bus {
+    var data:  logic<8>;
+    var valid: logic;
+    modport src {
+        data:  output,
+        valid: output,
+    }
+}
+module Top (
+    bus: modport Bus::src,
+    val: input logic<8>,
+) {
+    assign bus.data  = val;
+    assign bus.valid = 1'b1;
+}
+`;
+    const sim = Simulator.fromSource(PRODUCER_ONLY, "Top");
+
+    expect(() => {
+      (sim.dut as any).bus.data = 0n;
+    }).toThrow("Cannot write to output port 'data'");
+
+    sim.dispose();
+  });
+
+  test("interface port propagates through sub-module instances", () => {
+    interface TopPorts {
+      val: bigint;
+      readonly out: bigint;
+      readonly got: bigint;
+    }
+
+    const sim = Simulator.fromSource<TopPorts>(INTERFACE_HIERARCHY_SOURCE, "Top");
+
+    sim.dut.val = 0xABn;
+    expect(sim.dut.out).toBe(0xABn);
+    expect(sim.dut.got).toBe(1n);
+
+    sim.dut.val = 0x00n;
+    expect(sim.dut.out).toBe(0x00n);
+
+    sim.dispose();
+  });
+
+  test("multiple interface port members are independently accessible", () => {
+    interface TopPorts {
+      sig: { data: bigint; valid: bigint };
+      readonly out: bigint;
+    }
+
+    const sim = Simulator.fromSource<TopPorts>(INTERFACE_PORT_SOURCE, "Top");
+
+    sim.dut.sig.data = 0x77n;
+    sim.dut.sig.valid = 1n;
+    expect(sim.dut.out).toBe(0x77n);
+
+    sim.dut.sig.data = 0x33n;
+    sim.dut.sig.valid = 0n;
+    expect(sim.dut.out).toBe(0x33n);
+
+    sim.dispose();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Bug fix: 1-bit unpacked array port (logic [N])
+// ---------------------------------------------------------------------------
+
+const ARRAY_1BIT_SOURCE = `
+module ArrayPassThrough (
+    clk: input  clock,
+    rst: input  reset,
+    en:  input  logic [4],
+    y0:  output logic,
+    y1:  output logic,
+    y2:  output logic,
+    y3:  output logic,
+) {
+    always_comb {
+        y0 = en[0];
+        y1 = en[1];
+        y2 = en[2];
+        y3 = en[3];
+    }
+}
+`;
+
+describe("E2E: 1-bit unpacked array port (logic [N])", () => {
+  test("each element is independently visible in hardware (issue #6)", () => {
+    interface Ports {
+      rst: bigint;
+      en: { at(i: number): bigint; set(i: number, v: bigint): void; length: number };
+      readonly y0: bigint;
+      readonly y1: bigint;
+      readonly y2: bigint;
+      readonly y3: bigint;
+    }
+
+    const sim = Simulator.fromSource<Ports>(ARRAY_1BIT_SOURCE, "ArrayPassThrough");
+
+    // Default: all inputs 0
+    sim.tick();
+    expect(sim.dut.y0).toBe(0n);
+    expect(sim.dut.y1).toBe(0n);
+    expect(sim.dut.y2).toBe(0n);
+    expect(sim.dut.y3).toBe(0n);
+
+    // Set element 0 only
+    sim.dut.en.set(0, 1n);
+    sim.tick();
+    expect(sim.dut.y0).toBe(1n);
+    expect(sim.dut.y1).toBe(0n);
+    expect(sim.dut.y2).toBe(0n);
+    expect(sim.dut.y3).toBe(0n);
+
+    // Set element 1 (was silently ignored before the fix)
+    sim.dut.en.set(0, 0n);
+    sim.dut.en.set(1, 1n);
+    sim.tick();
+    expect(sim.dut.y0).toBe(0n);
+    expect(sim.dut.y1).toBe(1n);
+    expect(sim.dut.y2).toBe(0n);
+    expect(sim.dut.y3).toBe(0n);
+
+    // Set elements 2 and 3
+    sim.dut.en.set(1, 0n);
+    sim.dut.en.set(2, 1n);
+    sim.dut.en.set(3, 1n);
+    sim.tick();
+    expect(sim.dut.y0).toBe(0n);
+    expect(sim.dut.y1).toBe(0n);
+    expect(sim.dut.y2).toBe(1n);
+    expect(sim.dut.y3).toBe(1n);
+
+    sim.dispose();
+  });
+
+  test("length property is correct", () => {
+    interface Ports {
+      rst: bigint;
+      en: { at(i: number): bigint; set(i: number, v: bigint): void; length: number };
+      readonly y0: bigint;
+      readonly y1: bigint;
+      readonly y2: bigint;
+      readonly y3: bigint;
+    }
+
+    const sim = Simulator.fromSource<Ports>(ARRAY_1BIT_SOURCE, "ArrayPassThrough");
+    expect(sim.dut.en.length).toBe(4);
+    sim.dispose();
+  });
+
+  test("4-state mode: X written to element i propagates only to output yi (verifies maskBase layout)", () => {
+    // This test validates that the maskBase = baseOffset + totalValueBytes assumption
+    // matches the actual JIT memory layout when fourState: true is used.
+    interface Ports {
+      rst: bigint;
+      en: { at(i: number): bigint; set(i: number, v: unknown): void; length: number };
+      readonly y0: bigint;
+      readonly y1: bigint;
+      readonly y2: bigint;
+      readonly y3: bigint;
+    }
+
+    const sim = Simulator.fromSource<Ports>(ARRAY_1BIT_SOURCE, "ArrayPassThrough", { fourState: true });
+
+    // Start with all defined zeros
+    for (let i = 0; i < 4; i++) sim.dut.en.set(i, 0n);
+    sim.tick();
+
+    // Set element 1 to X; only y1 should become X
+    sim.dut.en.set(1, X);
+    sim.tick();
+
+    expect(sim.fourState("y1").mask).not.toBe(0n);  // y1 = X
+    expect(sim.fourState("y0").mask).toBe(0n);       // y0 defined
+    expect(sim.fourState("y2").mask).toBe(0n);       // y2 defined
+    expect(sim.fourState("y3").mask).toBe(0n);       // y3 defined
+
+    // Set element 2 to X; y2 becomes X, y1 remains X
+    sim.dut.en.set(2, X);
+    sim.tick();
+
+    expect(sim.fourState("y1").mask).not.toBe(0n);
+    expect(sim.fourState("y2").mask).not.toBe(0n);
+    expect(sim.fourState("y0").mask).toBe(0n);
+    expect(sim.fourState("y3").mask).toBe(0n);
+
+    // Clear element 1 to defined 0; y1 becomes defined again
+    sim.dut.en.set(1, 0n);
+    sim.tick();
+
+    expect(sim.fourState("y1").mask).toBe(0n);
+    expect(sim.fourState("y2").mask).not.toBe(0n);
+
+    sim.dispose();
+  });
+});

package/src/napi-helpers.ts

@@ -46,6 +46,7 @@ export interface RawNapiSimulationHandle {
   readonly hierarchyJson: string;
   readonly stableSize: number;
   readonly totalSize: number;
+  readonly defaultMaxSteps: number | null;
   addClock(eventId: number, period: number, initialDelay: number): void;
   schedule(eventId: number, time: number, value: number): void;
   runUntil(endTime: number): void;
@@ -300,12 +301,17 @@ export function parseNapiLayout(json: string): {
 /**
  * Build PortInfo records from the NAPI layout signals.
  * This auto-detects port metadata so users don't need to hand-write ModuleDefinition.
+ *
+ * Hierarchical signal names (e.g. "bus.data", "bus.valid" from an interface port)
+ * are grouped into a nested PortInfo with an `interface` map so that createDut can
+ * expose them as `dut.bus.data` and `dut.bus.valid`.
  */
 export function buildPortsFromLayout(
   signals: Record<string, SignalLayout & { typeKind: string; arrayDims?: number[] }>,
   _events: Record<string, number>,
 ): Record<string, PortInfo> {
-  const ports: Record<string, PortInfo> = {};
+  // Step 1: Build flat PortInfo for every signal name
+  const flat: Record<string, PortInfo> = {};
 
   for (const [name, sig] of Object.entries(signals)) {
     const typeKind = sig.typeKind;
@@ -329,7 +335,36 @@ export function buildPortsFromLayout(
     if (sig.arrayDims && sig.arrayDims.length > 0) {
       (port as { arrayDims: readonly number[] }).arrayDims = sig.arrayDims;
     }
-    ports[name] = port;
+    flat[name] = port;
+  }
+
+  // Step 2: Group hierarchical signals (e.g. "bus.data") into nested PortInfo.
+  // Veryl interface ports are exactly one level deep, so "bus.data" → parent "bus",
+  // member "data". The parent entry receives an `interface` map of its members;
+  // the flat layout keys are kept as-is so createNestedDut can look them up.
+  const ports: Record<string, PortInfo> = {};
+  const ifMaps = new Map<string, Record<string, PortInfo>>();
+
+  for (const [name, port] of Object.entries(flat)) {
+    const dotIdx = name.indexOf(".");
+    if (dotIdx < 0) {
+      ports[name] = port;
+      continue;
+    }
+    // Hierarchical signal: first segment is the interface port name
+    const parentName = name.slice(0, dotIdx);
+    const memberName = name.slice(dotIdx + 1);
+    if (!ifMaps.has(parentName)) {
+      const ifMap: Record<string, PortInfo> = {};
+      ifMaps.set(parentName, ifMap);
+      ports[parentName] = {
+        direction: "inout",
+        type: "logic",
+        width: 0,
+        interface: ifMap,
+      };
+    }
+    ifMaps.get(parentName)![memberName] = port;
   }
 
   return ports;

package/src/simulation.ts

@@ -57,6 +57,7 @@ export class Simulation<P = Record<string, unknown>> {
   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 readonly _defaultMaxSteps: number | undefined;
   private _disposed = false;
 
   private constructor(
@@ -66,6 +67,7 @@ export class Simulation<P = Record<string, unknown>> {
     state: DirtyState,
     buffer: ArrayBuffer | SharedArrayBuffer,
     layout: Record<string, SignalLayout & { typeKind?: string; associatedClock?: string }>,
+    defaultMaxSteps?: number,
   ) {
     this._handle = handle;
     this._dut = dut;
@@ -73,6 +75,7 @@ export class Simulation<P = Record<string, unknown>> {
     this._state = state;
     this._buffer = buffer;
     this._layout = layout;
+    this._defaultMaxSteps = defaultMaxSteps;
   }
 
   /**
@@ -185,12 +188,13 @@ export class Simulation<P = Record<string, unknown>> {
     const ports = buildPortsFromLayout(layout.signals, events);
 
     const buf = raw.sharedMemory().buffer;
+    const defaultMaxSteps = raw.defaultMaxSteps ?? undefined;
 
     const state: DirtyState = { dirty: false };
     const handle = wrapDirectSimulationHandle(raw);
     const dut = createDut<P>(buf, layout.forDut, ports, handle, state, hierarchy);
 
-    return new Simulation<P>(handle, dut, events, state, buf, layout.signals);
+    return new Simulation<P>(handle, dut, events, state, buf, layout.signals, defaultMaxSteps);
   }
 
   /** The DUT accessor object — read/write ports as plain properties. */
@@ -298,7 +302,7 @@ export class Simulation<P = Record<string, unknown>> {
     opts?: { maxSteps?: number },
   ): number {
     this.ensureAlive();
-    const max = opts?.maxSteps ?? 100_000;
+    const max = opts?.maxSteps ?? this._defaultMaxSteps ?? 100_000;
     let steps = 0;
     while (!condition()) {
       const t = this._handle.step();

package/src/types.ts

@@ -124,7 +124,7 @@ export interface CreateResult<H extends NativeHandle = NativeHandle> {
 // ---------------------------------------------------------------------------
 
 export interface SimulatorOptions {
-  /** Enable 4-state (X/Z) simulation. Default: false. */
+  /** Enable 4-state (X) simulation. Default: false. */
   fourState?: boolean;
   /** Path to write VCD waveform output. */
   vcd?: string;