@celox-sim/celox 0.0.1 → 0.1.3

package/src/simulation.test.ts

@@ -0,0 +1,185 @@
+import { describe, test, expect, vi } from "vitest";
+import { Simulation, type NativeCreateSimulationFn } from "./simulation.js";
+import type {
+  CreateResult,
+  ModuleDefinition,
+  NativeSimulationHandle,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Mock helpers
+// ---------------------------------------------------------------------------
+
+interface TopPorts {
+  rst: number;
+  d: number;
+  readonly q: number;
+}
+
+const TopModule: ModuleDefinition<TopPorts> = {
+  __celox_module: true,
+  name: "Top",
+  source: "module Top ...",
+  ports: {
+    clk: { direction: "input", type: "clock", width: 1 },
+    rst: { direction: "input", type: "reset", width: 1 },
+    d:   { direction: "input", type: "logic", width: 8 },
+    q:   { direction: "output", type: "logic", width: 8 },
+  },
+  events: ["clk"],
+};
+
+function createMockNative(): {
+  create: NativeCreateSimulationFn;
+  handle: NativeSimulationHandle;
+  buffer: SharedArrayBuffer;
+} {
+  const buffer = new SharedArrayBuffer(64);
+  let currentTime = 0;
+
+  const handle: NativeSimulationHandle = {
+    addClock: vi.fn(),
+    schedule: vi.fn(),
+    runUntil: vi.fn().mockImplementation((endTime: number) => {
+      // Simulate: q = d after running
+      const view = new DataView(buffer);
+      view.setUint8(4, view.getUint8(2));
+      currentTime = endTime;
+    }),
+    step: vi.fn().mockImplementation(() => {
+      currentTime += 5;
+      const view = new DataView(buffer);
+      view.setUint8(4, view.getUint8(2));
+      return currentTime;
+    }),
+    time: vi.fn().mockImplementation(() => currentTime),
+    evalComb: vi.fn().mockImplementation(() => {
+      const view = new DataView(buffer);
+      view.setUint8(4, view.getUint8(2));
+    }),
+    dump: vi.fn(),
+    dispose: vi.fn(),
+  };
+
+  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" },
+    },
+    events: { clk: 0 },
+    handle,
+  } satisfies CreateResult<NativeSimulationHandle>);
+
+  return { create, handle, buffer };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("Simulation", () => {
+  test("create and addClock", () => {
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.addClock("clk", { period: 10 });
+    expect(mock.handle.addClock).toHaveBeenCalledWith(0, 10, 0);
+  });
+
+  test("addClock with initialDelay", () => {
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.addClock("clk", { period: 10, initialDelay: 5 });
+    expect(mock.handle.addClock).toHaveBeenCalledWith(0, 10, 5);
+  });
+
+  test("schedule", () => {
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.schedule("clk", { time: 50, value: 1 });
+    expect(mock.handle.schedule).toHaveBeenCalledWith(0, 50, 1);
+  });
+
+  test("runUntil", () => {
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.dut.d = 42;
+    sim.runUntil(100);
+
+    expect(mock.handle.runUntil).toHaveBeenCalledWith(100);
+    expect(sim.dut.q).toBe(42);
+  });
+
+  test("step", () => {
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.dut.d = 0xAB;
+    const t = sim.step();
+
+    expect(t).toBe(5);
+    expect(sim.dut.q).toBe(0xAB);
+  });
+
+  test("time", () => {
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    expect(sim.time()).toBe(0);
+    sim.runUntil(100);
+    expect(sim.time()).toBe(100);
+  });
+
+  test("unknown event throws", () => {
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    expect(() => sim.addClock("bad", { period: 10 })).toThrow("Unknown event");
+  });
+
+  test("dispose prevents further operations", () => {
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.dispose();
+    expect(() => sim.runUntil(100)).toThrow("disposed");
+  });
+
+  test("dump delegates to handle", () => {
+    const mock = createMockNative();
+    const sim = Simulation.create(TopModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.dump(99);
+    expect(mock.handle.dump).toHaveBeenCalledWith(99);
+  });
+
+  test("create throws without native binding", () => {
+    expect(() => {
+      Simulation.create(TopModule);
+    }).toThrow("Native simulator binding not loaded");
+  });
+});

package/src/simulation.ts

@@ -0,0 +1,273 @@
+/**
+ * Time-based Simulation.
+ *
+ * Wraps a NativeSimulationHandle and provides a high-level TypeScript API
+ * for clock-driven simulation with automatic scheduling.
+ */
+
+import type {
+  CreateResult,
+  ModuleDefinition,
+  NativeSimulationHandle,
+  SimulatorOptions,
+} from "./types.js";
+import { createDut, type DirtyState } from "./dut.js";
+import {
+  loadNativeAddon,
+  parseNapiLayout,
+  buildPortsFromLayout,
+  wrapDirectSimulationHandle,
+} from "./napi-helpers.js";
+
+/**
+ * Placeholder for the NAPI binding's `createSimulation()`.
+ * Stream B will provide the real implementation.
+ * @internal
+ */
+export type NativeCreateSimulationFn = (
+  source: string,
+  moduleName: string,
+  options: SimulatorOptions,
+) => CreateResult<NativeSimulationHandle>;
+
+let _nativeCreate: NativeCreateSimulationFn | undefined;
+
+/**
+ * Register the NAPI binding at module load time.
+ * @internal
+ */
+export function setNativeSimulationCreate(fn: NativeCreateSimulationFn): void {
+  _nativeCreate = fn;
+}
+
+// ---------------------------------------------------------------------------
+// Simulation
+// ---------------------------------------------------------------------------
+
+export class Simulation<P = Record<string, unknown>> {
+  private readonly _handle: NativeSimulationHandle;
+  private readonly _dut: P;
+  private readonly _events: Record<string, number>;
+  private readonly _state: DirtyState;
+  private _disposed = false;
+
+  private constructor(
+    handle: NativeSimulationHandle,
+    dut: P,
+    events: Record<string, number>,
+    state: DirtyState,
+  ) {
+    this._handle = handle;
+    this._dut = dut;
+    this._events = events;
+    this._state = state;
+  }
+
+  /**
+   * Create a Simulation for the given module.
+   *
+   * ```ts
+   * import { Top } from "./generated/Top.js";
+   * const sim = Simulation.create(Top);
+   * sim.addClock("clk", { period: 10 });
+   * ```
+   */
+  static create<P>(
+    module: ModuleDefinition<P>,
+    options?: SimulatorOptions & {
+      __nativeCreate?: NativeCreateSimulationFn;
+    },
+  ): Simulation<P> {
+    // When the module was produced by the Vite plugin, delegate to fromProject()
+    if (module.projectPath && !options?.__nativeCreate) {
+      return Simulation.fromProject<P>(module.projectPath, module.name, options);
+    }
+
+    const createFn = options?.__nativeCreate ?? _nativeCreate;
+    if (!createFn) {
+      throw new Error(
+        "Native simulator binding not loaded. " +
+          "Ensure @celox-sim/celox-napi is installed.",
+      );
+    }
+
+    const { fourState, vcd } = options ?? {};
+    const result = createFn(module.source, module.name, { fourState, vcd });
+    const state: DirtyState = { dirty: false };
+
+    const dut = createDut<P>(
+      result.buffer,
+      result.layout,
+      module.ports,
+      result.handle,
+      state,
+    );
+
+    return new Simulation<P>(result.handle, dut, result.events, state);
+  }
+
+  /**
+   * Create a Simulation directly from Veryl source code.
+   *
+   * Automatically discovers ports from the NAPI layout — no
+   * `ModuleDefinition` needed.
+   *
+   * ```ts
+   * const sim = Simulation.fromSource<CounterPorts>(COUNTER_SOURCE, "Counter");
+   * sim.addClock("clk", { period: 10 });
+   * sim.runUntil(100);
+   * ```
+   */
+  static fromSource<P = Record<string, unknown>>(
+    source: string,
+    top: string,
+    options?: SimulatorOptions & { nativeAddonPath?: string },
+  ): Simulation<P> {
+    const addon = loadNativeAddon(options?.nativeAddonPath);
+    const napiOpts = options?.fourState ? { fourState: options.fourState } : undefined;
+    const raw = new addon.NativeSimulationHandle(source, top, napiOpts);
+
+    const layout = parseNapiLayout(raw.layoutJson);
+    const events: Record<string, number> = JSON.parse(raw.eventsJson);
+
+    const ports = buildPortsFromLayout(layout.signals, events);
+
+    const buf = raw.sharedMemory().buffer;
+
+    const state: DirtyState = { dirty: false };
+    const handle = wrapDirectSimulationHandle(raw);
+    const dut = createDut<P>(buf, layout.forDut, ports, handle, state);
+
+    return new Simulation<P>(handle, dut, events, state);
+  }
+
+  /**
+   * Create a Simulation from a Veryl project directory.
+   *
+   * Searches upward from `projectPath` for `Veryl.toml`, gathers all
+   * `.veryl` source files, and builds the simulation using the project's
+   * clock/reset settings.
+   *
+   * ```ts
+   * const sim = Simulation.fromProject<MyPorts>("./my-project", "Top");
+   * sim.addClock("clk", { period: 10 });
+   * ```
+   */
+  static fromProject<P = Record<string, unknown>>(
+    projectPath: string,
+    top: string,
+    options?: SimulatorOptions & { nativeAddonPath?: string },
+  ): Simulation<P> {
+    const addon = loadNativeAddon(options?.nativeAddonPath);
+    const napiOpts = options?.fourState ? { fourState: options.fourState } : undefined;
+    const raw = addon.NativeSimulationHandle.fromProject(projectPath, top, napiOpts);
+
+    const layout = parseNapiLayout(raw.layoutJson);
+    const events: Record<string, number> = JSON.parse(raw.eventsJson);
+
+    const ports = buildPortsFromLayout(layout.signals, events);
+
+    const buf = raw.sharedMemory().buffer;
+
+    const state: DirtyState = { dirty: false };
+    const handle = wrapDirectSimulationHandle(raw);
+    const dut = createDut<P>(buf, layout.forDut, ports, handle, state);
+
+    return new Simulation<P>(handle, dut, events, state);
+  }
+
+  /** The DUT accessor object — read/write ports as plain properties. */
+  get dut(): P {
+    return this._dut;
+  }
+
+  /**
+   * Register a periodic clock.
+   *
+   * @param name    Clock event name (must match a `clock` port).
+   * @param opts    `period` in time units; optional `initialDelay`.
+   */
+  addClock(
+    name: string,
+    opts: { period: number; initialDelay?: number },
+  ): void {
+    this.ensureAlive();
+    const eventId = this.resolveEvent(name);
+    this._handle.addClock(eventId, opts.period, opts.initialDelay ?? 0);
+  }
+
+  /**
+   * Schedule a one-shot value change for a signal.
+   *
+   * @param name  Event/signal name.
+   * @param opts  `time` — absolute time to apply; `value` — value to set.
+   */
+  schedule(name: string, opts: { time: number; value: number }): void {
+    this.ensureAlive();
+    const eventId = this.resolveEvent(name);
+    this._handle.schedule(eventId, opts.time, opts.value);
+  }
+
+  /**
+   * 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.
+   */
+  runUntil(endTime: number): void {
+    this.ensureAlive();
+    this._handle.runUntil(endTime);
+    this._state.dirty = false;
+  }
+
+  /**
+   * Advance to the next scheduled event.
+   *
+   * @returns The time of the processed event, or `null` if no events remain.
+   */
+  step(): number | null {
+    this.ensureAlive();
+    const t = this._handle.step();
+    this._state.dirty = false;
+    return t;
+  }
+
+  /** Current simulation time. */
+  time(): number {
+    this.ensureAlive();
+    return this._handle.time();
+  }
+
+  /** Write current signal values to VCD at the given timestamp. */
+  dump(timestamp: number): void {
+    this.ensureAlive();
+    this._handle.dump(timestamp);
+  }
+
+  /** Release native resources. */
+  dispose(): void {
+    if (!this._disposed) {
+      this._disposed = true;
+      this._handle.dispose();
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Internal
+  // -----------------------------------------------------------------------
+
+  private resolveEvent(name: string): number {
+    const id = this._events[name];
+    if (id === undefined) {
+      throw new Error(
+        `Unknown event '${name}'. Available: ${Object.keys(this._events).join(", ")}`,
+      );
+    }
+    return id;
+  }
+
+  private ensureAlive(): void {
+    if (this._disposed) {
+      throw new Error("Simulation has been disposed");
+    }
+  }
+}

package/src/simulator.test.ts

@@ -0,0 +1,191 @@
+import { describe, test, expect, vi } from "vitest";
+import { Simulator, type NativeCreateFn } from "./simulator.js";
+import type {
+  CreateResult,
+  ModuleDefinition,
+  NativeSimulatorHandle,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Mock helpers
+// ---------------------------------------------------------------------------
+
+interface AdderPorts {
+  rst: number;
+  a: number;
+  b: number;
+  readonly sum: number;
+}
+
+const AdderModule: ModuleDefinition<AdderPorts> = {
+  __celox_module: true,
+  name: "Adder",
+  source: "module Adder ...",
+  ports: {
+    clk: { direction: "input", type: "clock", width: 1 },
+    rst: { direction: "input", type: "reset", width: 1 },
+    a:   { direction: "input", type: "logic", width: 16 },
+    b:   { direction: "input", type: "logic", width: 16 },
+    sum: { direction: "output", type: "logic", width: 17 },
+  },
+  events: ["clk"],
+};
+
+function createMockNative(): {
+  create: NativeCreateFn;
+  handle: NativeSimulatorHandle;
+  buffer: SharedArrayBuffer;
+} {
+  const buffer = new SharedArrayBuffer(64);
+  const evalFn = () => {
+    const view = new DataView(buffer);
+    const a = view.getUint16(2, true);
+    const b = view.getUint16(4, true);
+    view.setUint32(8, a + b, true);
+  };
+  const handle: NativeSimulatorHandle = {
+    tick: vi.fn().mockImplementation(evalFn),
+    tickN: vi.fn().mockImplementation((_eventId: number, count: number) => {
+      for (let i = 0; i < count; i++) evalFn();
+    }),
+    evalComb: vi.fn().mockImplementation(evalFn),
+    dump: vi.fn(),
+    dispose: vi.fn(),
+  };
+
+  const create: NativeCreateFn = vi.fn().mockReturnValue({
+    buffer,
+    layout: {
+      clk: { offset: 12, width: 1, byteSize: 1, is4state: false, direction: "input" },
+      rst: { offset: 0, width: 1, byteSize: 1, is4state: false, direction: "input" },
+      a:   { offset: 2, width: 16, byteSize: 2, is4state: false, direction: "input" },
+      b:   { offset: 4, width: 16, byteSize: 2, is4state: false, direction: "input" },
+      sum: { offset: 8, width: 17, byteSize: 4, is4state: false, direction: "output" },
+    },
+    events: { clk: 0 },
+    handle,
+  } satisfies CreateResult<NativeSimulatorHandle>);
+
+  return { create, handle, buffer };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("Simulator", () => {
+  test("create and basic tick", () => {
+    const mock = createMockNative();
+    const sim = Simulator.create(AdderModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.dut.a = 100;
+    sim.dut.b = 200;
+    sim.tick();
+
+    expect(sim.dut.sum).toBe(300);
+    expect(mock.handle.tick).toHaveBeenCalledTimes(1);
+  });
+
+  test("tick with count", () => {
+    const mock = createMockNative();
+    const sim = Simulator.create(AdderModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.tick(3);
+    expect(mock.handle.tickN).toHaveBeenCalledWith(0, 3);
+  });
+
+  test("tick with event handle", () => {
+    const mock = createMockNative();
+    const sim = Simulator.create(AdderModule, {
+      __nativeCreate: mock.create,
+    });
+
+    const clk = sim.event("clk");
+    expect(clk.name).toBe("clk");
+    expect(clk.id).toBe(0);
+
+    sim.tick(clk);
+    expect(mock.handle.tick).toHaveBeenCalledWith(0);
+  });
+
+  test("tick with event handle and count", () => {
+    const mock = createMockNative();
+    const sim = Simulator.create(AdderModule, {
+      __nativeCreate: mock.create,
+    });
+
+    const clk = sim.event("clk");
+    sim.tick(clk, 5);
+    expect(mock.handle.tickN).toHaveBeenCalledWith(0, 5);
+  });
+
+  test("event() throws for unknown event", () => {
+    const mock = createMockNative();
+    const sim = Simulator.create(AdderModule, {
+      __nativeCreate: mock.create,
+    });
+
+    expect(() => sim.event("nonexistent")).toThrow("Unknown event");
+  });
+
+  test("dispose prevents further operations", () => {
+    const mock = createMockNative();
+    const sim = Simulator.create(AdderModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.dispose();
+    expect(() => sim.tick()).toThrow("disposed");
+    expect(mock.handle.dispose).toHaveBeenCalledTimes(1);
+  });
+
+  test("double dispose is safe", () => {
+    const mock = createMockNative();
+    const sim = Simulator.create(AdderModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.dispose();
+    sim.dispose(); // no-op
+    expect(mock.handle.dispose).toHaveBeenCalledTimes(1);
+  });
+
+  test("dump delegates to handle", () => {
+    const mock = createMockNative();
+    const sim = Simulator.create(AdderModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.dump(42);
+    expect(mock.handle.dump).toHaveBeenCalledWith(42);
+  });
+
+  test("create throws without native binding", () => {
+    expect(() => {
+      Simulator.create(AdderModule);
+    }).toThrow("Native simulator binding not loaded");
+  });
+
+  test("tick clears dirty flag", () => {
+    const mock = createMockNative();
+    const sim = Simulator.create(AdderModule, {
+      __nativeCreate: mock.create,
+    });
+
+    sim.dut.a = 100;
+    sim.tick();
+
+    // After tick, reading output should NOT trigger evalComb
+    // because tick already cleared dirty
+    void sim.dut.sum;
+    // evalComb might have been called by the first dut.sum read,
+    // but tick itself should have cleared dirty
+    const callsBefore = (mock.handle.evalComb as ReturnType<typeof vi.fn>).mock.calls.length;
+    void sim.dut.sum;
+    expect((mock.handle.evalComb as ReturnType<typeof vi.fn>).mock.calls.length).toBe(callsBefore);
+  });
+});