esiaccel 0.1.4.dev31__cp310-cp310-win_amd64.whl → 0.2.3.dev80__cp310-cp310-win_amd64.whl

esiaccel/__init__.py

@@ -1,13 +1,31 @@
 #  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
-
-from .accelerator import AcceleratorConnection
+import sys
+import os
+from .accelerator import AcceleratorConnection, Context, LogLevel
 
 from .esiCppAccel import (AppID, Type, BundleType, ChannelType, ArrayType,
                           StructType, BitsType, UIntType, SIntType)
 
 __all__ = [
-    "AcceleratorConnection", "AppID", "Type", "BundleType", "ChannelType",
-    "ArrayType", "StructType", "BitsType", "UIntType", "SIntType"
+    "AcceleratorConnection", "AppID", "Context", "LogLevel", "Type",
+    "BundleType", "ChannelType", "ArrayType", "StructType", "BitsType",
+    "UIntType", "SIntType"
 ]
+
+if sys.platform == "win32":
+  """Ensure that ESI libraries are in the dll path on Windows. Necessary to
+  call when users build against the esiaccel-provided prebuilt CMake/prebuilt
+  libraries, before they are loaded via. python.
+  """
+  from .utils import get_dll_dir
+  os.add_dll_directory(str(get_dll_dir()))
+
+
+def connect(platform: str, connection_str: str) -> "AcceleratorConnection":
+  """Connect to an accelerator using the specified platform and connection
+  string."""
+  ctxt = Context.default()
+  return AcceleratorConnection(ctxt,
+                               ctxt.cpp_ctxt.connect(platform, connection_str))

esiaccel/accelerator.py

@@ -15,19 +15,51 @@ from typing import Dict, List, Optional
 from .types import BundlePort
 from . import esiCppAccel as cpp
 
-# Global context for the C++ side.
-ctxt = cpp.Context()
+LogLevel = cpp.LogLevel
+
+
+class Context:
+  """A context for ESI accelerator connections. The underlying C++ context owns
+  everything assocated with it including types, accelerator connections, and
+  the accelerator facade/interface (aka Accelerator) itself. It must not be
+  garbage collected while any accelerators or connections that it owns are still
+  in use as they will be disconnected and destroyed when the context is
+  destroyed."""
+
+  _default: Optional["Context"] = None
+
+  def __init__(self, log_level: cpp.LogLevel = cpp.LogLevel.Warning):
+    self.cpp_ctxt = cpp.Context()
+    self.set_stdio_logger(log_level)
+
+  @staticmethod
+  def default() -> "Context":
+    if Context._default is None:
+      Context._default = Context()
+    return Context._default
+
+  def set_stdio_logger(self, level: cpp.LogLevel):
+    self.cpp_ctxt.set_stdio_logger(level)
+
+  def connect(self, platform: str,
+              connection_str: str) -> "AcceleratorConnection":
+    return AcceleratorConnection(
+        self, self.cpp_ctxt.connect(platform, connection_str))
 
 
 class AcceleratorConnection:
   """A connection to an ESI accelerator."""
 
-  def __init__(self, platform: str, connection_str: str):
-    self.cpp_accel = cpp.AcceleratorConnection(ctxt, platform, connection_str)
+  def __init__(self, ctxt: Context, cpp_accel: cpp.AcceleratorConnection):
+    if not isinstance(ctxt, Context):
+      raise TypeError("ctxt must be a Context")
+    self.ctxt = ctxt
+    self.cpp_accel = cpp_accel
 
   def manifest(self) -> cpp.Manifest:
     """Get and parse the accelerator manifest."""
-    return cpp.Manifest(ctxt, self.cpp_accel.sysinfo().json_manifest())
+    return cpp.Manifest(self.ctxt.cpp_ctxt,
+                        self.cpp_accel.sysinfo().json_manifest())
 
   def sysinfo(self) -> cpp.SysInfo:
     return self.cpp_accel.sysinfo()

esiaccel/cmake/esiaccelConfig.cmake

@@ -13,3 +13,37 @@ else()
     IMPORTED_LOCATION "${CMAKE_CURRENT_LIST_DIR}/.././libESICppRuntime.so"
   )
 endif()
+
+add_library(esiaccel::CosimRpc SHARED IMPORTED)
+set_target_properties(esiaccel::CosimRpc PROPERTIES
+  INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_LIST_DIR}/../include"
+  INTERFACE_LINK_LIBRARIES esiaccel::ESICppRuntime
+)
+
+if(WIN32)
+  set_target_properties(esiaccel::CosimRpc PROPERTIES
+    IMPORTED_LOCATION "${CMAKE_CURRENT_LIST_DIR}/../CosimRpc.dll"
+    IMPORTED_IMPLIB "${CMAKE_CURRENT_LIST_DIR}/../CosimRpc.lib"
+  )
+else()
+  set_target_properties(esiaccel::CosimRpc PROPERTIES
+    IMPORTED_LOCATION "${CMAKE_CURRENT_LIST_DIR}/.././libCosimRpc.so"
+  )
+endif()
+
+add_library(esiaccel::CosimBackend SHARED IMPORTED)
+set_target_properties(esiaccel::CosimBackend PROPERTIES
+  INTERFACE_INCLUDE_DIRECTORIES "${CMAKE_CURRENT_LIST_DIR}/../include"
+  INTERFACE_LINK_LIBRARIES "esiaccel::ESICppRuntime;esiaccel::CosimRpc"
+)
+
+if(WIN32)
+  set_target_properties(esiaccel::CosimBackend PROPERTIES
+    IMPORTED_LOCATION "${CMAKE_CURRENT_LIST_DIR}/../CosimBackend.dll"
+    IMPORTED_IMPLIB "${CMAKE_CURRENT_LIST_DIR}/../CosimBackend.lib"
+  )
+else()
+  set_target_properties(esiaccel::CosimBackend PROPERTIES
+    IMPORTED_LOCATION "${CMAKE_CURRENT_LIST_DIR}/.././libCosimBackend.so"
+  )
+endif()

esiaccel/codegen.py

@@ -6,7 +6,7 @@
 # with the runtime, though it is intended to be extensible for other languages.
 
 from typing import List, TextIO, Type, Optional
-from .accelerator import AcceleratorConnection
+from .accelerator import AcceleratorConnection, Context
 from .esiCppAccel import ModuleInfo
 from . import types
 
@@ -171,12 +171,12 @@ def run(generator: Type[Generator] = CppGenerator,
 
   conn: AcceleratorConnection
   if args.file is not None:
-    conn = AcceleratorConnection("trace", f"-:{args.file}")
+    conn = Context.default().connect("trace", f"-:{args.file}")
   elif args.platform is not None:
     if args.connection is None:
       print("Must specify --connection with --platform")
       return 1
-    conn = AcceleratorConnection(args.platform, args.connection)
+    conn = Context.default().connect(args.platform, args.connection)
   else:
     print("Must specify either --file or --platform")
     return 1

esiaccel/cosim/Cosim_CycleCount.sv

@@ -0,0 +1,84 @@
+//===- Cosim_CycleCount.sv - ESI cycle counter 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 should instantiate this ONCE to provide cycle count
+// information to the ESI runtime. The module maintains a 64-bit cycle counter
+// and uses request/response channels to provide the count to the runtime.
+//
+//===----------------------------------------------------------------------===//
+
+import Cosim_DpiPkg::*;
+
+module Cosim_CycleCount
+#(
+  // Core clock frequency in Hz. Used by the runtime to convert cycles to time.
+  parameter longint unsigned CORE_CLOCK_FREQUENCY_HZ = 0
+)(
+  input logic clk,
+  input logic rst
+);
+
+  // 64-bit cycle counter.
+  longint unsigned cycle_count;
+
+  always_ff @(posedge clk) begin
+    if (rst)
+      cycle_count <= 0;
+    else
+      cycle_count <= cycle_count + 1;
+  end
+
+  // Request channel (From Host)
+  // 0-bit message used as a trigger.
+  wire req_valid;
+  wire req_ready;
+
+  Cosim_Endpoint_FromHost #(
+    .ENDPOINT_ID("__cosim_cycle_count.arg"),
+    .FROM_HOST_TYPE_ID("!esi.channel<i1>"),
+    .FROM_HOST_SIZE_BITS(1)
+  ) req_ep (
+    .clk(clk),
+    .rst(rst),
+    .DataOutValid(req_valid),
+    .DataOutReady(req_ready),
+    .DataOut()
+  );
+
+  // Response channel (To Host)
+  typedef struct packed {
+    longint unsigned cycle;
+    longint unsigned freq;
+  } RespStruct;
+
+  wire resp_ready;
+  wire resp_valid;
+  RespStruct resp_data;
+
+  assign resp_data.cycle = cycle_count;
+  assign resp_data.freq = CORE_CLOCK_FREQUENCY_HZ;
+
+  // Handshake logic:
+  // When request arrives (req_valid), we are ready to send response (resp_valid).
+  // We consume request only when response is accepted.
+  assign resp_valid = req_valid;
+  assign req_ready = resp_ready;
+
+  Cosim_Endpoint_ToHost #(
+    .ENDPOINT_ID("__cosim_cycle_count.result"),
+    .TO_HOST_TYPE_ID("struct{cycle:int<64>,freq:int<64>}"),
+    .TO_HOST_SIZE_BITS(128)
+  ) resp_ep (
+    .clk(clk),
+    .rst(rst),
+    .DataInValid(resp_valid),
+    .DataInReady(resp_ready),
+    .DataIn(resp_data)
+  );
+
+endmodule

esiaccel/cosim/Cosim_Endpoint.sv

@@ -9,6 +9,8 @@
 // Package: Cosim_DpiPkg
 //
 // Main cosim <--> dpi bridge module.
+
+
 //
 //===----------------------------------------------------------------------===//
 
@@ -80,15 +82,6 @@ module Cosim_Endpoint_ToHost
                        TO_HOST_SIZE_BYTES_FLOOR_IN_BITS];
   endgenerate
 
-  initial begin
-    $display("TO_HOST_SIZE_BITS: %d", TO_HOST_SIZE_BITS);
-    $display("TO_HOST_SIZE_BYTES: %d", TO_HOST_SIZE_BYTES);
-    $display("TO_HOST_SIZE_BITS_DIFF: %d", TO_HOST_SIZE_BITS_DIFF);
-    $display("TO_HOST_SIZE_BYTES_FLOOR: %d", TO_HOST_SIZE_BYTES_FLOOR);
-    $display("TO_HOST_SIZE_BYTES_FLOOR_IN_BITS: %d",
-             TO_HOST_SIZE_BYTES_FLOOR_IN_BITS);
-  end
-
 endmodule
 
 module Cosim_Endpoint_FromHost
@@ -118,9 +111,8 @@ module Cosim_Endpoint_FromHost
       $error("Cosim endpoint (%s) register failed: %d", ENDPOINT_ID, rc);
   end
 
-  /// *******************
-  /// Data out management.
-  ///
+  /// ***********************
+  /// Useful constants.
 
   localparam int FROM_HOST_SIZE_BYTES = int'((FROM_HOST_SIZE_BITS+7)/8);
   // The number of bits over a byte.
@@ -129,13 +121,30 @@ module Cosim_Endpoint_FromHost
   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 (DataOutValid && DataOutReady) // A transfer occurred.
-        DataOutValid <= 1'b0;
-
-      if (!DataOutValid || DataOutReady) 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;
 
@@ -149,7 +158,7 @@ module Cosim_Endpoint_FromHost
             ENDPOINT_ID, FROM_HOST_SIZE_BYTES, data_limit, rc);
         end else if (rc == 0) begin
           if (data_limit == FROM_HOST_SIZE_BYTES)
-            DataOutValid <= 1'b1;
+            DataOut_a_valid <= 1'b1;
           else if (data_limit == 0)
             begin end // No message.
           else
@@ -159,31 +168,51 @@ module Cosim_Endpoint_FromHost
         end
       end
     end else begin
-      DataOutValid <= 1'b0;
+      DataOut_a_valid <= 1'b0;
     end
   end
 
-  // Assign packed output bit array from unpacked byte array.
+  // 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[((iOut+1)*8)-1:iOut*8] = DataOutBuffer[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, we've got to copy the extra bits.
-      assign DataOut[(FROM_HOST_SIZE_BYTES_FLOOR_IN_BITS +
-                      FROM_HOST_SIZE_BITS_DIFF - 1) :
-                        FROM_HOST_SIZE_BYTES_FLOOR_IN_BITS]
+      // 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
 
-  initial begin
-    $display("FROM_HOST_SIZE_BITS: %d", FROM_HOST_SIZE_BITS);
-    $display("FROM_HOST_SIZE_BYTES: %d", FROM_HOST_SIZE_BYTES);
-    $display("FROM_HOST_SIZE_BITS_DIFF: %d", FROM_HOST_SIZE_BITS_DIFF);
-    $display("FROM_HOST_SIZE_BYTES_FLOOR: %d", FROM_HOST_SIZE_BYTES_FLOOR);
-    $display("FROM_HOST_SIZE_BYTES_FLOOR_IN_BITS: %d",
-             FROM_HOST_SIZE_BYTES_FLOOR_IN_BITS);
-  end
+  /// *******************
+  /// 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/driver.cpp

@@ -30,7 +30,7 @@
 #include CONCAT3(V,TOP_MODULE,.h)
 // clang-format on
 
-#include "verilated_vcd_c.h"
+#include "verilated_fst_c.h"
 
 #include "signal.h"
 #include <iostream>
@@ -64,12 +64,12 @@ int main(int argc, char **argv) {
   }
 
 #ifdef TRACE
-  VerilatedVcdC *tfp = nullptr;
+  VerilatedFstC *tfp = nullptr;
 #endif
 
   if (waveformFile) {
 #ifdef TRACE
-    tfp = new VerilatedVcdC();
+    tfp = new VerilatedFstC();
     Verilated::traceEverOn(true);
     dut.trace(tfp, 99); // Trace 99 levels of hierarchy
     tfp->open(waveformFile);
@@ -95,11 +95,11 @@ int main(int argc, char **argv) {
   // Run for a few cycles with reset held.
   for (timeStamp = 0; timeStamp < 8 && !Verilated::gotFinish(); timeStamp++) {
     dut.eval();
-    dut.clk = !dut.clk;
 #ifdef TRACE
     if (tfp)
       tfp->dump(timeStamp);
 #endif
+    dut.clk = !dut.clk;
   }
 
   // Take simulation out of reset.
@@ -108,12 +108,12 @@ int main(int argc, char **argv) {
   // Run for the specified number of cycles out of reset.
   for (; !Verilated::gotFinish() && !stopSimulation; timeStamp++) {
     dut.eval();
-    dut.clk = !dut.clk;
-
 #ifdef TRACE
     if (tfp)
       tfp->dump(timeStamp);
 #endif
+    dut.clk = !dut.clk;
+
     if (debugPeriod)
       std::this_thread::sleep_for(std::chrono::milliseconds(debugPeriod));
   }

esiaccel/cosim/driver.sv

@@ -18,8 +18,22 @@
 `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;
 

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)