esiaccel 0.2.2__cp312-cp312-win_amd64.whl

esiaccel/cosim/Cosim_Endpoint.sv

@@ -0,0 +1,218 @@
+//===- Cosim_Endpoint.sv - ESI cosim primary RTL module -----*- verilog -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// Package: Cosim_DpiPkg
+//
+// Main cosim <--> dpi bridge module.
+
+
+//
+//===----------------------------------------------------------------------===//
+
+import Cosim_DpiPkg::*;
+
+module Cosim_Endpoint_ToHost
+#(
+  parameter string ENDPOINT_ID = "",
+  parameter string TO_HOST_TYPE_ID = "",
+  parameter int TO_HOST_SIZE_BITS = -1
+)
+(
+  input  logic clk,
+  input  logic rst,
+
+  input  logic DataInValid,
+  output logic DataInReady,
+  input  logic [TO_HOST_SIZE_BITS-1:0] DataIn
+);
+
+  initial begin
+    int rc;
+    rc = cosim_init();
+    if (rc != 0)
+      $error("Cosim init failed (%d)", rc);
+    rc = cosim_ep_register(ENDPOINT_ID, "", 0,
+                            TO_HOST_TYPE_ID, TO_HOST_SIZE_BYTES);
+    if (rc != 0)
+      $error("Cosim endpoint (%s) register failed: %d", ENDPOINT_ID, rc);
+  end
+
+  /// **********************
+  /// Data in management.
+  ///
+
+  localparam int TO_HOST_SIZE_BYTES = int'((TO_HOST_SIZE_BITS+7)/8);
+  // The number of bits over a byte.
+  localparam int TO_HOST_SIZE_BITS_DIFF = TO_HOST_SIZE_BITS % 8;
+  localparam int TO_HOST_SIZE_BYTES_FLOOR = int'(TO_HOST_SIZE_BITS/8);
+  localparam int TO_HOST_SIZE_BYTES_FLOOR_IN_BITS
+      = TO_HOST_SIZE_BYTES_FLOOR * 8;
+
+  assign DataInReady = 1'b1;
+  byte unsigned DataInBuffer[TO_HOST_SIZE_BYTES-1:0];
+
+  always@(posedge clk) begin
+    if (~rst) begin
+      if (DataInValid) begin
+        int rc;
+        rc = cosim_ep_tryput(ENDPOINT_ID, DataInBuffer, TO_HOST_SIZE_BYTES);
+        if (rc != 0)
+          $error("cosim_ep_tryput(%s, *, %d) = %d Error! (Data lost)",
+            ENDPOINT_ID, TO_HOST_SIZE_BYTES, rc);
+      end
+    end
+  end
+
+  // Assign packed input bit array to unpacked byte array.
+  genvar iIn;
+  generate
+    for (iIn=0; iIn<TO_HOST_SIZE_BYTES_FLOOR; iIn++)
+      assign DataInBuffer[iIn] = DataIn[((iIn+1)*8)-1:iIn*8];
+    if (TO_HOST_SIZE_BITS_DIFF != 0)
+      // If the type is not a multiple of 8, we've got to copy the extra bits.
+      assign DataInBuffer[TO_HOST_SIZE_BYTES - 1]
+                         [TO_HOST_SIZE_BITS_DIFF - 1:0] =
+             DataIn[(TO_HOST_SIZE_BYTES_FLOOR_IN_BITS +
+                     TO_HOST_SIZE_BITS_DIFF - 1) :
+                       TO_HOST_SIZE_BYTES_FLOOR_IN_BITS];
+  endgenerate
+
+endmodule
+
+module Cosim_Endpoint_FromHost
+#(
+  parameter string ENDPOINT_ID = "",
+  parameter string FROM_HOST_TYPE_ID = "",
+  parameter int FROM_HOST_SIZE_BITS = -1
+)
+(
+  input  logic clk,
+  input  logic rst,
+
+  output logic DataOutValid,
+  input  logic DataOutReady,
+  output logic [FROM_HOST_SIZE_BITS-1:0] DataOut
+);
+
+  // Handle initialization logic.
+  initial begin
+    int rc;
+    rc = cosim_init();
+    if (rc != 0)
+      $error("Cosim init failed (%d)", rc);
+    rc = cosim_ep_register(ENDPOINT_ID, FROM_HOST_TYPE_ID, FROM_HOST_SIZE_BYTES,
+                            "", 0);
+    if (rc != 0)
+      $error("Cosim endpoint (%s) register failed: %d", ENDPOINT_ID, rc);
+  end
+
+  /// ***********************
+  /// Useful constants.
+
+  localparam int FROM_HOST_SIZE_BYTES = int'((FROM_HOST_SIZE_BITS+7)/8);
+  // The number of bits over a byte.
+  localparam int FROM_HOST_SIZE_BITS_DIFF = FROM_HOST_SIZE_BITS % 8;
+  localparam int FROM_HOST_SIZE_BYTES_FLOOR = int'(FROM_HOST_SIZE_BITS/8);
+  localparam int FROM_HOST_SIZE_BYTES_FLOOR_IN_BITS
+      = FROM_HOST_SIZE_BYTES_FLOOR * 8;
+
+  // Buffer to hold incoming data directly from the DPI calls.
+  byte unsigned DataOutBuffer[FROM_HOST_SIZE_BYTES-1:0];
+
+  // Pipeline interface signals for buffering DataOut.
+  // DataOut_a_valid is asserted when a complete message is available in
+  // DataOut_a buffer and waiting to be accepted by the skid buffer.
+  logic DataOut_a_valid;
+  // Packed representation of the byte buffer to feed the skid input.
+  logic [FROM_HOST_SIZE_BITS-1:0] DataOut_a;
+  // Ready/valid wires between this module and the skid buffer.
+  wire DataOut_a_ready;
+  wire DataOut_x_valid;
+  wire [FROM_HOST_SIZE_BITS-1:0] DataOut_x;
+
+  always @(posedge clk) begin
+    if (~rst) begin
+      // If the skid buffer accepted the input token this cycle, clear the
+      // internal valid that indicates we have buffered data.
+      if (DataOut_a_valid && DataOut_a_ready)
+        DataOut_a_valid <= 1'b0;
+
+      // Only attempt to fetch data from the host when the skid buffer can
+      // accept it (DataOut_a_ready).
+      if (!DataOut_a_valid && DataOut_a_ready) begin
+        int data_limit;
+        int rc;
+
+        data_limit = FROM_HOST_SIZE_BYTES;
+        rc = cosim_ep_tryget(ENDPOINT_ID, DataOutBuffer, data_limit);
+        if (rc < 0) begin
+          $error("cosim_ep_tryget(%s, *, %d -> %d) returned an error (%d)",
+            ENDPOINT_ID, FROM_HOST_SIZE_BYTES, data_limit, rc);
+        end else if (rc > 0) begin
+          $error("cosim_ep_tryget(%s, *, %d -> %d) had data left over! (%d)",
+            ENDPOINT_ID, FROM_HOST_SIZE_BYTES, data_limit, rc);
+        end else if (rc == 0) begin
+          if (data_limit == FROM_HOST_SIZE_BYTES)
+            DataOut_a_valid <= 1'b1;
+          else if (data_limit == 0)
+            begin end // No message.
+          else
+            $error(
+              "cosim_ep_tryget(%s, *, %d -> %d) did not load entire buffer!",
+              ENDPOINT_ID, FROM_HOST_SIZE_BYTES, data_limit);
+        end
+      end
+    end else begin
+      DataOut_a_valid <= 1'b0;
+    end
+  end
+
+  // Pack the byte array into a single vector that will be handed to the
+  // skid buffer as its input payload.
+  genvar iOut;
+  generate
+    for (iOut=0; iOut<FROM_HOST_SIZE_BYTES_FLOOR; iOut++)
+      assign DataOut_a[((iOut+1)*8)-1:iOut*8] = DataOutBuffer[iOut];
+    if (FROM_HOST_SIZE_BITS_DIFF != 0)
+      // If the type is not a multiple of 8, copy the extra bits.
+      assign DataOut_a[(FROM_HOST_SIZE_BYTES_FLOOR_IN_BITS +
+                        FROM_HOST_SIZE_BITS_DIFF - 1) :
+                          FROM_HOST_SIZE_BYTES_FLOOR_IN_BITS]
+             = DataOutBuffer[FROM_HOST_SIZE_BYTES - 1]
+                            [FROM_HOST_SIZE_BITS_DIFF - 1 : 0];
+  endgenerate
+
+  /// *******************
+  /// Data out management.
+  ///
+  /// It has been observed that some simulators (verilator) does not handle
+  /// combinational driving from DPI well (resulting in non-determinism wrt
+  /// some of the combinational outputs being dropped/replicated). Questa does
+  /// not show this behavior.
+  /// A mitigation is to add a skid buffer to decouple the DPI interface
+  /// from the output interface.
+
+  // Instantiate a single-stage pipeline to buffer tokens that arrive from
+  // the host and present them to the module's output with proper
+  // ready/valid handshaking.
+  ESI_PipelineStage #(.WIDTH(FROM_HOST_SIZE_BITS)) out_pipe (
+    .clk(clk),
+    .rst(rst),
+    .a_valid(DataOut_a_valid),
+    .a(DataOut_a),
+    .a_ready(DataOut_a_ready),
+    .x_valid(DataOut_x_valid),
+    .x(DataOut_x),
+    .x_ready(DataOutReady)
+  );
+
+  // Drive the module's outward-facing signals from the pipeline output.
+  assign DataOutValid = DataOut_x_valid;
+  assign DataOut = DataOut_x;
+
+endmodule

esiaccel/cosim/Cosim_Manifest.sv

@@ -0,0 +1,32 @@
+//===- Cosim_Manifest.sv - ESI manifest module -------------*- verilog -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// A cosimulated design needs to instantiate this ONCE with the zlib-compressed
+// JSON manifest as the parameter.
+//
+//===----------------------------------------------------------------------===//
+
+import Cosim_DpiPkg::*;
+
+module Cosim_Manifest
+#(
+  parameter int COMPRESSED_MANIFEST_SIZE = 0,
+  parameter int unsigned ESI_VERSION = 0
+)(
+  input logic [COMPRESSED_MANIFEST_SIZE-1:0][7:0] compressed_manifest
+);
+
+  byte unsigned compressed_manifest_bytes[COMPRESSED_MANIFEST_SIZE-1:0];
+  always_comb
+    for (int i=0; i<COMPRESSED_MANIFEST_SIZE; i++)
+      compressed_manifest_bytes[i] = compressed_manifest[i];
+
+  always@(compressed_manifest)
+    cosim_set_manifest(ESI_VERSION, compressed_manifest_bytes);
+
+endmodule

esiaccel/cosim/driver.cpp

@@ -0,0 +1,131 @@
+//===- driver.cpp - ESI Verilator software driver -------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// A fairly standard, boilerplate Verilator C++ simulation driver. Assumes the
+// top level exposes just two signals: 'clk' and 'rst'.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef TOP_MODULE
+#define TOP_MODULE ESI_Cosim_Top
+#endif // TOP_MODULE
+
+// Macro black magic to get the header file name and class name from the
+// TOP_MODULE macro. Need to disable formatting for this section, as
+// clang-format messes it up by inserting spaces.
+
+// clang-format off
+#define STRINGIFY_MACRO(x) STR(x)
+#define STR(x) #x
+#define EXPAND(x)x
+#define CONCAT3(n1, n2, n3) STRINGIFY_MACRO(EXPAND(n1)EXPAND(n2)EXPAND(n3))
+#define TOKENPASTE(x, y) x ## y
+#define CLASSNAME(x, y) TOKENPASTE(x, y)
+
+#include CONCAT3(V,TOP_MODULE,.h)
+// clang-format on
+
+#include "verilated_fst_c.h"
+
+#include "signal.h"
+#include <iostream>
+#include <thread>
+
+vluint64_t timeStamp;
+
+// Stop the simulation gracefully on ctrl-c.
+volatile bool stopSimulation = false;
+void handle_sigint(int) { stopSimulation = true; }
+
+// Called by $time in Verilog.
+double sc_time_stamp() { return timeStamp; }
+
+int main(int argc, char **argv) {
+  // Register graceful exit handler.
+  signal(SIGINT, handle_sigint);
+
+  Verilated::commandArgs(argc, argv);
+
+  // Construct the simulated module's C++ model.
+  auto &dut = *new CLASSNAME(V, TOP_MODULE)();
+  char *waveformFile = getenv("SAVE_WAVE");
+
+  char *periodStr = getenv("DEBUG_PERIOD");
+  unsigned debugPeriod = 0;
+  if (periodStr) {
+    debugPeriod = std::stoi(periodStr);
+    std::cout << "[driver] Setting debug period to " << debugPeriod
+              << std::endl;
+  }
+
+#ifdef TRACE
+  VerilatedFstC *tfp = nullptr;
+#endif
+
+  if (waveformFile) {
+#ifdef TRACE
+    tfp = new VerilatedFstC();
+    Verilated::traceEverOn(true);
+    dut.trace(tfp, 99); // Trace 99 levels of hierarchy
+    tfp->open(waveformFile);
+    std::cout << "[driver] Writing trace to " << waveformFile << std::endl;
+#else
+    std::cout
+        << "[driver] Warning: waveform file specified, but not a debug build"
+        << std::endl;
+#endif
+  }
+
+  std::cout << "[driver] Starting simulation" << std::endl;
+
+  // TODO: Add max speed (cycles per second) option for small, interactive
+  // simulations to reduce waveform for debugging. Should this be a command line
+  // option or configurable over the cosim interface?
+
+  // Reset.
+  dut.rst = 1;
+  dut.clk = 0;
+
+  // TODO: Support ESI reset handshake in the future.
+  // Run for a few cycles with reset held.
+  for (timeStamp = 0; timeStamp < 8 && !Verilated::gotFinish(); timeStamp++) {
+    dut.eval();
+#ifdef TRACE
+    if (tfp)
+      tfp->dump(timeStamp);
+#endif
+    dut.clk = !dut.clk;
+  }
+
+  // Take simulation out of reset.
+  dut.rst = 0;
+
+  // Run for the specified number of cycles out of reset.
+  for (; !Verilated::gotFinish() && !stopSimulation; timeStamp++) {
+    dut.eval();
+#ifdef TRACE
+    if (tfp)
+      tfp->dump(timeStamp);
+#endif
+    dut.clk = !dut.clk;
+
+    if (debugPeriod)
+      std::this_thread::sleep_for(std::chrono::milliseconds(debugPeriod));
+  }
+
+  // Tell the simulator that we're going to exit. This flushes the output(s) and
+  // frees whatever memory may have been allocated.
+  dut.final();
+#ifdef TRACE
+  if (tfp)
+    tfp->close();
+#endif
+
+  std::cout << "[driver] Ending simulation at tick #" << timeStamp << std::endl;
+  return 0;
+}

esiaccel/cosim/driver.sv

@@ -0,0 +1,74 @@
+//===- driver.sv - ESI cosim testbench driver -----------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// Contains the top module driver for an ESI cosimulation. It simply provides a
+// clock and reset signal. In the future, the reset signal will become a reset
+// handshake.
+//
+//===----------------------------------------------------------------------===//
+
+`timescale 1ns / 100ps
+
+`ifndef TOP_MODULE
+`define TOP_MODULE ESI_Cosim_Top
+`endif
+
+// Allow reading environment variables to control waveform dumping.
+import "DPI-C" function string getenv(input string env_name);
+
+module driver();
+
+  // If the SAVE_WAVE environment variable is set, dump a VCD waveform to that
+  // filename.
+  initial begin
+    string save_wave = getenv("SAVE_WAVE");
+    if (save_wave != "") begin
+      $display("[driver] Saving waveform to %s", save_wave);
+      $dumpfile(save_wave);
+      $dumpvars(0, driver);
+    end
+  end
+
+  logic clk = 0;
+  logic rst = 0;
+
+  `TOP_MODULE top (
+    .clk(clk),
+    .rst(rst)
+  );
+
+  always begin
+    // A clock period is #4.
+    clk = ~clk;
+    #2;
+  end
+
+  initial begin
+    int cycles;
+
+    $display("[driver] Starting simulation");
+
+    rst = 1;
+    // Hold in reset for 4 cycles.
+    @(posedge clk);
+    @(posedge clk);
+    @(posedge clk);
+    @(posedge clk);
+    rst = 0;
+
+    if ($value$plusargs ("cycles=%d", cycles)) begin
+      int i;
+      for (i = 0; i < cycles; i++) begin
+        @(posedge clk);
+      end
+      $display("[driver] Ending simulation at tick #%0d", $time);
+      $finish();
+    end
+  end
+
+endmodule

esiaccel/cosim/questa.py

@@ -0,0 +1,141 @@
+#  Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+#  See https://llvm.org/LICENSE.txt for license information.
+#  SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+import os
+from pathlib import Path
+from typing import List, Optional, Callable, Dict
+
+from .simulator import CosimCollateralDir, Simulator, SourceFiles
+
+
+class Questa(Simulator):
+  """Run and compile funcs for Questasim."""
+
+  DefaultDriver = CosimCollateralDir / "driver.sv"
+
+  def __init__(
+      self,
+      sources: SourceFiles,
+      run_dir: Path,
+      debug: bool,
+      run_stdout_callback: Optional[Callable[[str], None]] = None,
+      run_stderr_callback: Optional[Callable[[str], None]] = None,
+      compile_stdout_callback: Optional[Callable[[str], None]] = None,
+      compile_stderr_callback: Optional[Callable[[str], None]] = None,
+      make_default_logs: bool = True,
+      macro_definitions: Optional[Dict[str, str]] = None,
+      # An optional list of questa error codes to suppress
+      suppressed_questa_errors: Optional[List[int]] = None):
+    super().__init__(
+        sources=sources,
+        run_dir=run_dir,
+        debug=debug,
+        run_stdout_callback=run_stdout_callback,
+        run_stderr_callback=run_stderr_callback,
+        compile_stdout_callback=compile_stdout_callback,
+        compile_stderr_callback=compile_stderr_callback,
+        make_default_logs=make_default_logs,
+        macro_definitions=macro_definitions,
+    )
+    self.suppressed_questa_errors = suppressed_questa_errors
+
+  # Questa doesn't use stderr for error messages. Everything goes to stdout.
+  UsesStderr = False
+
+  def internal_compile_commands(self) -> List[str]:
+    cmds = [
+        "onerror { quit -f -code 1 }",
+    ]
+    sources = self.sources.rtl_sources
+    sources.append(Questa.DefaultDriver)
+
+    # Format macro definition command
+    if self.macro_definitions:
+      macro_definitions_cmd = " ".join([
+          f"+define+{k}={v}" if v is not None else f"+define+{k}"
+          for k, v in self.macro_definitions.items()
+      ])
+    else:
+      macro_definitions_cmd = ""
+
+    # Format error suppression command
+    if self.suppressed_questa_errors:
+      suppressed_questa_errors_cmd = " ".join(
+          [f"-suppress {ec}" for ec in self.suppressed_questa_errors])
+    else:
+      suppressed_questa_errors_cmd = ""
+
+    for src in sources:
+      cmds.append(
+          f"vlog -incr +acc -sv {macro_definitions_cmd} {suppressed_questa_errors_cmd} +define+TOP_MODULE={self.sources.top}"
+          f" +define+SIMULATION {src.as_posix()}")
+    cmds.append(f"vopt -incr driver -o driver_opt +acc")
+    return cmds
+
+  def compile_commands(self) -> List[List[str]]:
+    with open("compile.do", "w") as f:
+      for cmd in self.internal_compile_commands():
+        f.write(cmd)
+        f.write("\n")
+      f.write("quit\n")
+    return [
+        ["vsim", "-batch", "-do", "compile.do"],
+    ]
+
+  def run_command(self, gui: bool) -> List[str]:
+    vsim = "vsim"
+    # Note: vsim exit codes say nothing about the test run's pass/fail even
+    # if $fatal is encountered in the simulation.
+    if gui:
+      cmd = [
+          vsim,
+          "driver_opt",
+      ]
+    else:
+      cmd = [
+          vsim,
+          "driver_opt",
+          "-batch",
+      ]
+
+      if self.debug:
+        # Create waveform dump .do file
+        wave_file = Path("wave.do")
+        with wave_file.open("w") as f:
+          f.write("log -r /*\n")
+        cmd += [
+            "-do",
+            str(wave_file.resolve()),
+        ]
+        # Questa will by default log to a vsim.wlf file in the current
+        # directory.
+        print(
+            f"Debug mode enabled - waveform will be in {wave_file.resolve().parent / 'vsim.wlf'}"
+        )
+
+      cmd += [
+          "-do",
+          "run -all",
+      ]
+
+    for lib in self.sources.dpi_so_paths():
+      svLib = os.path.splitext(lib)[0]
+      cmd.append("-sv_lib")
+      cmd.append(svLib)
+    return cmd
+
+  def run(self,
+          inner_command: str,
+          gui: bool = False,
+          server_only: bool = False) -> int:
+    """Override the Simulator.run() to add a soft link in the run directory (to
+    the work directory) before running vsim the usual way."""
+
+    # Create a soft link to the work directory.
+    workDir = self.run_dir / "work"
+    if not workDir.exists():
+      os.symlink(Path(os.getcwd()) / "work", workDir)
+
+    # Run the simulation.
+    return super().run(inner_command, gui, server_only=server_only)