@celox-sim/celox 0.1.5 → 0.1.7

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.

package/src/matchers.ts

@@ -70,7 +70,7 @@ function isFourStateRef(v: unknown): v is FourStateRef {
 // Matcher implementations
 // ---------------------------------------------------------------------------
 
-function getMask(received: unknown): number | bigint {
+function getMask(received: unknown): bigint {
   if (!isFourStateRef(received)) {
     throw new TypeError(
       "toBeX/toBeAllX/toBeNotX matchers require a FourStateRef. " +
@@ -84,7 +84,7 @@ function getMask(received: unknown): number | bigint {
 const customMatchers = {
   toBeX(received: unknown) {
     const mask = getMask(received);
-    const pass = mask !== 0 && mask !== 0n;
+    const pass = mask !== 0n;
     return {
       pass,
       message: () =>
@@ -100,10 +100,7 @@ const customMatchers = {
     }
     const [, mask] = readFourState(received.buffer, received.layout);
     const width = received.layout.width;
-    const allOnes =
-      width <= 53
-        ? (width === 53 ? Number.MAX_SAFE_INTEGER : (1 << width) - 1)
-        : (1n << BigInt(width)) - 1n;
+    const allOnes = (1n << BigInt(width)) - 1n;
     const pass = mask === allOnes;
     return {
       pass,
@@ -116,7 +113,7 @@ const customMatchers = {
 
   toBeNotX(received: unknown) {
     const mask = getMask(received);
-    const pass = mask === 0 || mask === 0n;
+    const pass = mask === 0n;
     return {
       pass,
       message: () =>

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 };
   };
 }