@celox-sim/celox 0.0.1 → 0.1.4

package/src/simulator.ts

@@ -0,0 +1,266 @@
+/**
+ * Event-based Simulator.
+ *
+ * Wraps a NativeSimulatorHandle and provides a high-level TypeScript API
+ * for manually controlling clock edges via `tick()`.
+ */
+
+import type {
+  CreateResult,
+  EventHandle,
+  ModuleDefinition,
+  NativeSimulatorHandle,
+  SimulatorOptions,
+} from "./types.js";
+import { createDut, type DirtyState } from "./dut.js";
+import {
+  loadNativeAddon,
+  parseNapiLayout,
+  buildPortsFromLayout,
+  wrapDirectSimulatorHandle,
+} from "./napi-helpers.js";
+
+/**
+ * Placeholder for the NAPI binding's `createSimulator()`.
+ * Stream B will provide the real implementation; until then tests can
+ * inject a mock via `Simulator.create()` options or by replacing this
+ * module.
+ * @internal
+ */
+export type NativeCreateFn = (
+  source: string,
+  moduleName: string,
+  options: SimulatorOptions,
+) => CreateResult<NativeSimulatorHandle>;
+
+let _nativeCreate: NativeCreateFn | undefined;
+
+/**
+ * Register the NAPI binding at module load time.
+ * Called once by the package entry point after loading the native addon.
+ * @internal
+ */
+export function setNativeSimulatorCreate(fn: NativeCreateFn): void {
+  _nativeCreate = fn;
+}
+
+// ---------------------------------------------------------------------------
+// Simulator
+// ---------------------------------------------------------------------------
+
+export class Simulator<P = Record<string, unknown>> {
+  private readonly _handle: NativeSimulatorHandle;
+  private readonly _dut: P;
+  private readonly _events: Record<string, number>;
+  private readonly _defaultEventId: number;
+  private readonly _state: DirtyState;
+  private _disposed = false;
+
+  private constructor(
+    handle: NativeSimulatorHandle,
+    dut: P,
+    events: Record<string, number>,
+    state: DirtyState,
+  ) {
+    this._handle = handle;
+    this._dut = dut;
+    this._events = events;
+    this._state = state;
+    const keys = Object.keys(events);
+    this._defaultEventId = keys.length > 0 ? events[keys[0]!]! : -1;
+  }
+
+  /**
+   * Create a Simulator for the given module.
+   *
+   * ```ts
+   * import { Adder } from "./generated/Adder.js";
+   * const sim = Simulator.create(Adder);
+   * ```
+   */
+  static create<P>(
+    module: ModuleDefinition<P>,
+    options?: SimulatorOptions & {
+      /** Override for testing — inject a mock NAPI create function. */
+      __nativeCreate?: NativeCreateFn;
+    },
+  ): Simulator<P> {
+    // When the module was produced by the Vite plugin, delegate to fromProject()
+    if (module.projectPath && !options?.__nativeCreate) {
+      return Simulator.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 Simulator<P>(result.handle, dut, result.events, state);
+  }
+
+  /**
+   * Create a Simulator directly from Veryl source code.
+   *
+   * Automatically discovers ports from the NAPI layout — no
+   * `ModuleDefinition` needed.
+   *
+   * ```ts
+   * const sim = Simulator.fromSource<AdderPorts>(ADDER_SOURCE, "Adder");
+   * sim.dut.a = 100;
+   * sim.dut.b = 200;
+   * sim.tick();
+   * expect(sim.dut.sum).toBe(300);
+   * ```
+   */
+  static fromSource<P = Record<string, unknown>>(
+    source: string,
+    top: string,
+    options?: SimulatorOptions & { nativeAddonPath?: string },
+  ): Simulator<P> {
+    const addon = loadNativeAddon(options?.nativeAddonPath);
+    const napiOpts = options?.fourState ? { fourState: options.fourState } : undefined;
+    const raw = new addon.NativeSimulatorHandle(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 = wrapDirectSimulatorHandle(raw);
+    const dut = createDut<P>(buf, layout.forDut, ports, handle, state);
+
+    return new Simulator<P>(handle, dut, events, state);
+  }
+
+  /**
+   * Create a Simulator from a Veryl project directory.
+   *
+   * Searches upward from `projectPath` for `Veryl.toml`, gathers all
+   * `.veryl` source files, and builds the simulator using the project's
+   * clock/reset settings.
+   *
+   * ```ts
+   * const sim = Simulator.fromProject<MyPorts>("./my-project", "Top");
+   * ```
+   */
+  static fromProject<P = Record<string, unknown>>(
+    projectPath: string,
+    top: string,
+    options?: SimulatorOptions & { nativeAddonPath?: string },
+  ): Simulator<P> {
+    const addon = loadNativeAddon(options?.nativeAddonPath);
+    const napiOpts = options?.fourState ? { fourState: options.fourState } : undefined;
+    const raw = addon.NativeSimulatorHandle.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 = wrapDirectSimulatorHandle(raw);
+    const dut = createDut<P>(buf, layout.forDut, ports, handle, state);
+
+    return new Simulator<P>(handle, dut, events, state);
+  }
+
+  /** The DUT accessor object — read/write ports as plain properties. */
+  get dut(): P {
+    return this._dut;
+  }
+
+  /**
+   * Trigger a clock edge.
+   *
+   * @param event  Optional event handle from `this.event()`.
+   *               If omitted, ticks the first (default) event.
+   * @param count  Number of ticks. Default: 1.
+   */
+  tick(event?: EventHandle | number, count?: number): void;
+  tick(count?: number): void;
+  tick(
+    eventOrCount?: EventHandle | number,
+    count?: number,
+  ): void {
+    this.ensureAlive();
+
+    let eventId: number;
+    let ticks: number;
+
+    if (typeof eventOrCount === "object" && eventOrCount !== null) {
+      // tick(eventHandle, count?)
+      eventId = (eventOrCount as EventHandle).id;
+      ticks = count ?? 1;
+    } else if (typeof eventOrCount === "number") {
+      // tick(count) — default event
+      eventId = this._defaultEventId;
+      ticks = eventOrCount;
+    } else {
+      // tick() — default event, 1 tick
+      eventId = this._defaultEventId;
+      ticks = 1;
+    }
+
+    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()`. */
+  event(name: string): EventHandle {
+    const id = this._events[name];
+    if (id === undefined) {
+      throw new Error(
+        `Unknown event '${name}'. Available: ${Object.keys(this._events).join(", ")}`,
+      );
+    }
+    return { name, id };
+  }
+
+  /** 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 ensureAlive(): void {
+    if (this._disposed) {
+      throw new Error("Simulator has been disposed");
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,164 @@
+/**
+ * @celox-sim/celox — Core type definitions
+ *
+ * These types define the contract between:
+ *   - Stream A (type generator): produces ModuleDefinition
+ *   - Stream B (NAPI bindings): produces CreateResult / NativeHandles
+ *   - Stream C (this package): consumes both
+ */
+
+// ---------------------------------------------------------------------------
+// Module definition (produced by Stream A's `celox-gen-ts`)
+// ---------------------------------------------------------------------------
+
+/**
+ * A compiled module descriptor emitted by `celox-gen-ts`.
+ * The type parameter `Ports` carries the generated port interface
+ * (e.g. `AdderPorts`) so that `Simulator.create(Adder)` returns
+ * a correctly-typed DUT accessor.
+ */
+export interface ModuleDefinition<Ports = Record<string, unknown>> {
+  readonly __celox_module: true;
+  readonly name: string;
+  readonly source: string;
+  readonly ports: Record<string, PortInfo>;
+  readonly events: string[];
+  /** Absolute path to the Veryl project directory (set by Vite plugin). */
+  readonly projectPath?: string;
+  /** Phantom field — never set at runtime. Carries the `Ports` type. */
+  readonly __ports?: Ports;
+}
+
+/** Metadata for a single port / interface member. */
+export interface PortInfo {
+  readonly direction: "input" | "output" | "inout";
+  readonly type: "clock" | "reset" | "logic" | "bit";
+  readonly width: number;
+  readonly arrayDims?: readonly number[];
+  readonly is4state?: boolean;
+  /** Nested interface members (recursive). */
+  readonly interface?: Record<string, PortInfo>;
+}
+
+// ---------------------------------------------------------------------------
+// Signal layout (produced by Stream B's NAPI `create()`)
+// ---------------------------------------------------------------------------
+
+/**
+ * Byte-level location of a signal inside the SharedArrayBuffer.
+ * @internal
+ */
+export interface SignalLayout {
+  /** Byte offset within the STABLE region. */
+  readonly offset: number;
+  /** Bit width of the signal. */
+  readonly width: number;
+  /** Number of bytes occupied (ceil(width/8)). */
+  readonly byteSize: number;
+  /** If true, an equal-sized mask follows immediately after the value. */
+  readonly is4state: boolean;
+  readonly direction: "input" | "output" | "inout";
+}
+
+// ---------------------------------------------------------------------------
+// NAPI handles (produced by Stream B)
+// ---------------------------------------------------------------------------
+
+/**
+ * Opaque handle returned by NAPI for event-based simulation.
+ * @internal
+ */
+export interface NativeSimulatorHandle {
+  tick(eventId: number): void;
+  tickN(eventId: number, count: number): void;
+  evalComb(): void;
+  dump(timestamp: number): void;
+  dispose(): void;
+}
+
+/**
+ * Opaque handle returned by NAPI for time-based simulation.
+ * @internal
+ */
+export interface NativeSimulationHandle {
+  addClock(eventId: number, period: number, initialDelay: number): void;
+  schedule(eventId: number, time: number, value: number): void;
+  runUntil(endTime: number): void;
+  step(): number | null;
+  time(): number;
+  evalComb(): void;
+  dump(timestamp: number): void;
+  dispose(): void;
+}
+
+/**
+ * Union of both handle types for code that is handle-agnostic.
+ * @internal
+ */
+export type NativeHandle = NativeSimulatorHandle | NativeSimulationHandle;
+
+/**
+ * Result returned by NAPI `create()`.
+ * @internal
+ */
+export interface CreateResult<H extends NativeHandle = NativeHandle> {
+  /** The simulator's internal memory buffer shared zero-copy. */
+  readonly buffer: ArrayBuffer | SharedArrayBuffer;
+  /** Per-signal byte layout within `buffer`. */
+  readonly layout: Record<string, SignalLayout>;
+  /** Event name → internal event ID mapping. */
+  readonly events: Record<string, number>;
+  /** Native control handle. */
+  readonly handle: H;
+}
+
+// ---------------------------------------------------------------------------
+// User-facing options
+// ---------------------------------------------------------------------------
+
+export interface SimulatorOptions {
+  /** Enable 4-state (X/Z) simulation. Default: false. */
+  fourState?: boolean;
+  /** Path to write VCD waveform output. */
+  vcd?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Event handle (returned by Simulator.event())
+// ---------------------------------------------------------------------------
+
+/** A resolved event reference for use with `tick()`. */
+export interface EventHandle {
+  readonly name: string;
+  readonly id: number;
+}
+
+// ---------------------------------------------------------------------------
+// 4-state helpers
+// ---------------------------------------------------------------------------
+
+/** Sentinel representing all-X. */
+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;
+}
+
+/** Construct a 4-state value. Mask bits set to 1 indicate X. */
+export function FourState(
+  value: number | bigint,
+  mask: number | bigint,
+): FourStateValue {
+  return { __fourState: true, value, mask };
+}
+
+export function isFourStateValue(v: unknown): v is FourStateValue {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    (v as FourStateValue).__fourState === true
+  );
+}

package/README.md

@@ -1,45 +0,0 @@
-# @celox-sim/celox
-
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@celox-sim/celox`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**