@celox-sim/celox 0.1.10 → 0.1.12

package/src/dut.test.ts

@@ -477,6 +477,193 @@ describe("createDut — array ports", () => {
     expect(dut.data.at(3)).toBe(0xDDn);
     expect(dut.data.length).toBe(4);
   });
+
+  test("1-bit elements (logic [N]): bit-packed read/write", () => {
+    // logic[4]: 4 elements of 1 bit each = 1 byte total in native memory
+    const buffer = makeBuffer(64);
+    const layout: Record<string, SignalLayout> = {
+      push: { offset: 0, width: 1, byteSize: 1, is4state: false, direction: "input" },
+    };
+    const ports: Record<string, PortInfo> = {
+      push: { direction: "input", type: "logic", width: 1, arrayDims: [4] },
+    };
+    const handle = mockHandle();
+    const state: DirtyState = { dirty: false };
+
+    const dut = createDut<{ push: { at(i: number): bigint; set(i: number, v: bigint): void; length: number } }>(
+      buffer, layout, ports, handle, state,
+    );
+
+    dut.push.set(0, 1n);
+    dut.push.set(1, 1n);
+    dut.push.set(2, 0n);
+    dut.push.set(3, 1n);
+
+    expect(dut.push.at(0)).toBe(1n);
+    expect(dut.push.at(1)).toBe(1n);
+    expect(dut.push.at(2)).toBe(0n);
+    expect(dut.push.at(3)).toBe(1n);
+    expect(dut.push.length).toBe(4);
+
+    // Verify native layout: all 4 elements packed in byte 0
+    const view = new DataView(buffer);
+    expect(view.getUint8(0)).toBe(0b1011); // bits 0,1,3 set = 0x0B
+    expect(view.getUint8(1)).toBe(0);      // no overflow into byte 1
+  });
+
+  test("1-bit elements: writes don't corrupt adjacent elements", () => {
+    const buffer = makeBuffer(64);
+    const layout: Record<string, SignalLayout> = {
+      bits: { offset: 0, width: 1, byteSize: 1, is4state: false, direction: "input" },
+    };
+    const ports: Record<string, PortInfo> = {
+      bits: { direction: "input", type: "logic", width: 1, arrayDims: [8] },
+    };
+    const handle = mockHandle();
+    const state: DirtyState = { dirty: false };
+
+    const dut = createDut<{ bits: { at(i: number): bigint; set(i: number, v: bigint): void } }>(
+      buffer, layout, ports, handle, state,
+    );
+
+    // Set element 0; verify element 1 unaffected
+    dut.bits.set(0, 1n);
+    expect(dut.bits.at(0)).toBe(1n);
+    dut.bits.set(1, 1n);
+    expect(dut.bits.at(0)).toBe(1n);  // element 0 must not be corrupted
+    expect(dut.bits.at(1)).toBe(1n);
+
+    // Clear element 0; element 1 must remain set
+    dut.bits.set(0, 0n);
+    expect(dut.bits.at(0)).toBe(0n);
+    expect(dut.bits.at(1)).toBe(1n);
+  });
+
+  test("1-bit elements: 8 elements span exactly one byte", () => {
+    const buffer = makeBuffer(64);
+    const layout: Record<string, SignalLayout> = {
+      bits: { offset: 2, width: 1, byteSize: 1, is4state: false, direction: "input" },
+    };
+    const ports: Record<string, PortInfo> = {
+      bits: { direction: "input", type: "logic", width: 1, arrayDims: [8] },
+    };
+    const handle = mockHandle();
+    const state: DirtyState = { dirty: false };
+
+    const dut = createDut<{ bits: { at(i: number): bigint; set(i: number, v: bigint): void } }>(
+      buffer, layout, ports, handle, state,
+    );
+
+    // Set all 8 bits
+    for (let i = 0; i < 8; i++) dut.bits.set(i, 1n);
+    const view = new DataView(buffer);
+    expect(view.getUint8(2)).toBe(0xff);
+
+    // Clear alternating bits
+    for (let i = 0; i < 8; i += 2) dut.bits.set(i, 0n);
+    expect(view.getUint8(2)).toBe(0b10101010);
+  });
+
+  test("elementWidth=3: elements spanning byte boundaries read/write correctly", () => {
+    // logic<3>[6]: 6 × 3 = 18 bits = 3 bytes
+    // Element 2: bitStart=6, spans bytes 0→1  ← cross-byte write/read path
+    // Element 5: bitStart=15, spans bytes 1→2 ← cross-byte write/read path
+    const buffer = makeBuffer(64);
+    const layout: Record<string, SignalLayout> = {
+      data: { offset: 0, width: 3, byteSize: 1, is4state: false, direction: "input" },
+    };
+    const ports: Record<string, PortInfo> = {
+      data: { direction: "input", type: "logic", width: 3, arrayDims: [6] },
+    };
+    const handle = mockHandle();
+    const state: DirtyState = { dirty: false };
+
+    const dut = createDut<{ data: { at(i: number): bigint; set(i: number, v: bigint): void; length: number } }>(
+      buffer, layout, ports, handle, state,
+    );
+
+    // Set all 6 elements to distinct values 1..6
+    for (let i = 0; i < 6; i++) dut.data.set(i, BigInt(i + 1));
+    for (let i = 0; i < 6; i++) expect(dut.data.at(i)).toBe(BigInt(i + 1));
+
+    // Overwrite the two cross-byte elements and verify neighbours are unaffected
+    dut.data.set(2, 0b101n);  // bitStart=6, crosses byte 0→1
+    expect(dut.data.at(2)).toBe(5n);
+    expect(dut.data.at(1)).toBe(2n);  // neighbour below
+    expect(dut.data.at(3)).toBe(4n);  // neighbour above
+
+    dut.data.set(5, 0b110n);  // bitStart=15, crosses byte 1→2
+    expect(dut.data.at(5)).toBe(6n);
+    expect(dut.data.at(4)).toBe(5n);  // neighbour below
+  });
+
+  test("1-bit 4-state: X writes value=0 and mask=1 at correct byte offset", () => {
+    // logic[8] with 4-state: value in byte 0 (bits 0-7 = elements 0-7),
+    // mask in byte 1 (bits 0-7 = masks for elements 0-7).
+    // totalValueBytes = ceil(8*1/8) = 1, so maskBase = offset + 1.
+    const buffer = makeBuffer(64);
+    const layout: Record<string, SignalLayout> = {
+      bits: { offset: 0, width: 1, byteSize: 1, is4state: true, direction: "input" },
+    };
+    const ports: Record<string, PortInfo> = {
+      bits: { direction: "input", type: "logic", width: 1, arrayDims: [8], is4state: true },
+    };
+    const handle = mockHandle();
+    const state: DirtyState = { dirty: false };
+
+    const dut = createDut<{ bits: { at(i: number): bigint; set(i: number, v: unknown): void } }>(
+      buffer, layout, ports, handle, state,
+    );
+
+    const view = new DataView(buffer);
+
+    // Assign X to element 3: value bit 3 → 0, mask bit 3 → 1
+    dut.bits.set(3, X);
+    expect(view.getUint8(0) & 0b00001000).toBe(0);           // value: bit 3 = 0
+    expect(view.getUint8(1) & 0b00001000).toBe(0b00001000);  // mask:  bit 3 = 1
+
+    // Write a defined 1 to element 3: value bit 3 → 1, mask bit 3 → 0
+    dut.bits.set(3, 1n);
+    expect(view.getUint8(0) & 0b00001000).toBe(0b00001000);  // value: bit 3 = 1
+    expect(view.getUint8(1) & 0b00001000).toBe(0);           // mask:  bit 3 cleared
+
+    // Setting elements 0 and 7 to X should only affect those mask bits
+    dut.bits.set(0, X);
+    dut.bits.set(7, X);
+    expect(view.getUint8(1)).toBe(0b10000001);  // mask: bits 0 and 7 set
+  });
+
+  test("3-bit 4-state: mask region starts at ceil(totalBits/8) bytes after value", () => {
+    // logic<3>[5]: 5 × 3 = 15 bits → totalValueBytes = ceil(15/8) = 2
+    // value occupies bytes 0-1, mask occupies bytes 2-3; maskBase = offset + 2
+    const buffer = makeBuffer(64);
+    const layout: Record<string, SignalLayout> = {
+      data: { offset: 0, width: 3, byteSize: 1, is4state: true, direction: "input" },
+    };
+    const ports: Record<string, PortInfo> = {
+      data: { direction: "input", type: "logic", width: 3, arrayDims: [5], is4state: true },
+    };
+    const handle = mockHandle();
+    const state: DirtyState = { dirty: false };
+
+    const dut = createDut<{ data: { set(i: number, v: unknown): void } }>(
+      buffer, layout, ports, handle, state,
+    );
+
+    const view = new DataView(buffer);
+
+    // Assign X to element 0 (bitStart=0, no cross-byte): value bits 0-2 = 0, mask bits 0-2 = 0b111
+    dut.data.set(0, X);
+    expect(view.getUint8(0) & 0b111).toBe(0);    // value byte 0: bits 0-2 cleared
+    expect(view.getUint8(2) & 0b111).toBe(0b111); // mask byte 2: bits 0-2 set
+    expect(view.getUint8(1)).toBe(0);              // value byte 1: untouched
+    expect(view.getUint8(3)).toBe(0);              // mask byte 3: untouched
+
+    // Write a defined value to element 0, verify mask cleared
+    dut.data.set(0, 0b110n);
+    expect(view.getUint8(0) & 0b111).toBe(0b110);  // value bits 0-2 = 6
+    expect(view.getUint8(2) & 0b111).toBe(0);       // mask bits 0-2 cleared
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/dut.ts

@@ -288,6 +288,25 @@ export function createChildDut(
   for (const [name, port] of Object.entries(hierarchy.ports)) {
     if (port.type === "clock") continue;
 
+    // Handle nested interface port
+    if (port.interface) {
+      const nestedObj = createNestedDut(
+        view,
+        hierarchy.forDut,
+        port.interface,
+        name,
+        handle,
+        state,
+      );
+      Object.defineProperty(obj, name, {
+        value: nestedObj,
+        enumerable: true,
+        configurable: false,
+        writable: false,
+      });
+      continue;
+    }
+
     const sig = hierarchy.forDut[name];
     if (!sig) continue;
 
@@ -439,6 +458,61 @@ function createNestedDut(
 // Array port accessor
 // ---------------------------------------------------------------------------
 
+/**
+ * Read a single element from a bit-packed byte region.
+ *
+ * The JIT stores array elements contiguously at the bit level:
+ * element i occupies bits [i*W .. (i+1)*W - 1] starting at baseOffset.
+ * Used when elementWidth < 8 (sub-byte elements).
+ */
+function readBitPackedElement(
+  view: DataView,
+  baseOffset: number,
+  elementWidth: number,
+  i: number,
+): number {
+  const bitStart = i * elementWidth;
+  const byteStart = baseOffset + (bitStart >> 3);
+  const bitShift = bitStart & 7;
+  const mask = (1 << elementWidth) - 1;
+  if (bitShift + elementWidth <= 8) {
+    return (view.getUint8(byteStart) >> bitShift) & mask;
+  }
+  // Spans two bytes
+  const lo = view.getUint8(byteStart);
+  const hi = view.getUint8(byteStart + 1);
+  return ((lo | (hi << 8)) >> bitShift) & mask;
+}
+
+/**
+ * Write a single element into a bit-packed byte region (read-modify-write).
+ *
+ * Used when elementWidth < 8 (sub-byte elements).
+ */
+function writeBitPackedElement(
+  view: DataView,
+  baseOffset: number,
+  elementWidth: number,
+  i: number,
+  value: number,
+): void {
+  const bitStart = i * elementWidth;
+  const byteStart = baseOffset + (bitStart >> 3);
+  const bitShift = bitStart & 7;
+  const mask = (1 << elementWidth) - 1;
+  const maskedValue = value & mask;
+
+  const lo = view.getUint8(byteStart);
+  view.setUint8(byteStart, (lo & ~((mask << bitShift) & 0xff)) | ((maskedValue << bitShift) & 0xff));
+
+  if (bitShift + elementWidth > 8) {
+    const bitsInLo = 8 - bitShift;
+    const hi = view.getUint8(byteStart + 1);
+    const hiMask = mask >> bitsInLo;
+    view.setUint8(byteStart + 1, (hi & ~hiMask) | (maskedValue >> bitsInLo));
+  }
+}
+
 function createArrayDut(
   view: DataView,
   baseSig: SignalLayout,
@@ -448,13 +522,61 @@ function createArrayDut(
 ): object {
   const dims = port.arrayDims!;
   const elementWidth = port.width;
-  const elementByteSize = Math.ceil(elementWidth / 8);
   const totalElements = dims.reduce((a, b) => a * b, 1);
   const isOutput = port.direction === "output";
   const isInput = port.direction === "input";
   const baseOffset = baseSig.offset;
   const is4state = baseSig.is4state;
 
+  if (elementWidth < 8) {
+    // Sub-byte elements: the JIT stores them bit-packed.
+    // Element i occupies bits [i*W .. (i+1)*W - 1] starting at baseOffset.
+    // For 4-state signals the mask region starts immediately after the value bytes.
+    const totalValueBytes = Math.ceil(totalElements * elementWidth / 8);
+    const maskBase = baseOffset + totalValueBytes;
+
+    return {
+      length: totalElements,
+
+      at(i: number): bigint {
+        if (state.dirty && !isInput) {
+          handle.evalComb();
+          state.dirty = false;
+        }
+        return BigInt(readBitPackedElement(view, baseOffset, elementWidth, i));
+      },
+
+      set(i: number, value: bigint | number | symbol | FourStateValue): void {
+        if (isOutput) {
+          throw new Error("Cannot write to output array port");
+        }
+        if (value === Symbol.for("veryl:X")) {
+          if (!is4state) {
+            throw new Error("Array port is not 4-state; cannot assign X");
+          }
+          writeBitPackedElement(view, baseOffset, elementWidth, i, 0);
+          writeBitPackedElement(view, maskBase, elementWidth, i, (1 << elementWidth) - 1);
+        } else if (isFourStateValue(value)) {
+          if (!is4state) {
+            throw new Error("Array port is not 4-state; cannot assign FourState");
+          }
+          writeBitPackedElement(view, baseOffset, elementWidth, i, Number(value.value));
+          writeBitPackedElement(view, maskBase, elementWidth, i, Number(value.mask));
+        } else {
+          const bigVal = typeof value === "bigint" ? value : BigInt(value as number);
+          writeBitPackedElement(view, baseOffset, elementWidth, i, Number(bigVal));
+          if (is4state) {
+            writeBitPackedElement(view, maskBase, elementWidth, i, 0);
+          }
+        }
+        state.dirty = true;
+      },
+    };
+  }
+
+  // elementWidth >= 8: byte-aligned stride.
+  const elementByteSize = Math.ceil(elementWidth / 8);
+
   return {
     length: totalElements,
 
@@ -519,7 +641,7 @@ function createArrayDut(
 
 /**
  * Read the raw 4-state (value, mask) pair for a signal.
- * Mask bits set to 1 indicate X/Z.
+ * Mask bits set to 1 indicate X.
  */
 export function readFourState(
   buffer: ArrayBuffer | SharedArrayBuffer,