esiaccel 0.0.17.dev735__cp312-cp312-win_amd64.whl → 0.1.0__cp312-cp312-win_amd64.whl

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_vcd_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
+  VerilatedVcdC *tfp = nullptr;
+#endif
+
+  if (waveformFile) {
+#ifdef TRACE
+    tfp = new VerilatedVcdC();
+    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();
+    dut.clk = !dut.clk;
+#ifdef TRACE
+    if (tfp)
+      tfp->dump(timeStamp);
+#endif
+  }
+
+  // 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();
+    dut.clk = !dut.clk;
+
+#ifdef TRACE
+    if (tfp)
+      tfp->dump(timeStamp);
+#endif
+    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,60 @@
+//===- 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
+
+module driver();
+
+  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/include/esi/CLI.h

@@ -35,6 +35,9 @@ public:
                "Connection string to use for accelerator communication")
         ->required();
     add_flag("--debug", debug, "Enable debug logging");
+#ifdef ESI_RUNTIME_TRACE
+    add_flag("--trace", trace, "Enable trace logging");
+#endif
     add_flag("-v,--verbose", verbose, "Enable verbose (info) logging");
     require_subcommand(0, 1);
   }
@@ -42,7 +45,9 @@ public:
   /// Run the parser.
   int esiParse(int argc, const char **argv) {
     CLI11_PARSE(*this, argc, argv);
-    if (debug)
+    if (trace)
+      ctxt = Context::withLogger<ConsoleLogger>(Logger::Level::Trace);
+    else if (debug)
       ctxt = Context::withLogger<ConsoleLogger>(Logger::Level::Debug);
     else if (verbose)
       ctxt = Context::withLogger<ConsoleLogger>(Logger::Level::Info);
@@ -62,8 +67,9 @@ protected:
 
   std::string backend;
   std::string connStr;
-  bool debug;
-  bool verbose;
+  bool trace = false;
+  bool debug = false;
+  bool verbose = false;
 };
 
 } // namespace esi

esiaccel/include/esi/Engines.h

@@ -0,0 +1,124 @@
+//===- Engines.h - Implement port communication -----------------*- C++ -*-===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+//
+// DO NOT EDIT!
+// This file is distributed as part of an ESI package. The source for this file
+// should always be modified within CIRCT.
+//
+//===----------------------------------------------------------------------===//
+//
+// Engines (as in DMA engine) implement the actual communication between the
+// host and the accelerator. They are low level of the ESI runtime API and are
+// not intended to be used directly by users.
+//
+// They are called "engines" rather than "DMA engines" since communication need
+// not be implemented via DMA.
+//
+//===----------------------------------------------------------------------===//
+
+// NOLINTNEXTLINE(llvm-header-guard)
+#ifndef ESI_ENGINGES_H
+#define ESI_ENGINGES_H
+
+#include "esi/Common.h"
+#include "esi/Ports.h"
+#include "esi/Services.h"
+#include "esi/Utils.h"
+
+#include <cassert>
+#include <future>
+
+namespace esi {
+class Accelerator;
+
+/// Engines implement the actual channel communication between the host and the
+/// accelerator. Engines can support multiple channels. They are low level of
+/// the ESI runtime API and are not intended to be used directly by users.
+class Engine {
+public:
+  Engine(AcceleratorConnection &conn) : connected(false), conn(conn) {}
+  virtual ~Engine() = default;
+  /// Start the engine, if applicable.
+  virtual void connect() { connected = true; };
+  /// Stop the engine, if applicable.
+  virtual void disconnect() { connected = false; };
+  /// Get a port for a channel, from the cache if it exists or create it. An
+  /// engine may override this method if different behavior is desired.
+  virtual ChannelPort &requestPort(AppIDPath idPath,
+                                   const std::string &channelName,
+                                   BundleType::Direction dir, const Type *type);
+
+protected:
+  /// Each engine needs to know how to create a ports. This method is called if
+  /// a port doesn't exist in the engine cache.
+  virtual std::unique_ptr<ChannelPort>
+  createPort(AppIDPath idPath, const std::string &channelName,
+             BundleType::Direction dir, const Type *type) = 0;
+
+  bool connected;
+  AcceleratorConnection &conn;
+
+private:
+  std::map<std::pair<AppIDPath, std::string>, std::unique_ptr<ChannelPort>>
+      ownedPorts;
+};
+
+/// Since engines can support multiple channels BUT not necessarily all of the
+/// channels in a bundle, a mapping from bundle channels to engines is needed.
+class BundleEngineMap {
+  friend class AcceleratorConnection;
+
+public:
+  /// Request ports for all the channels in a bundle. If the engine doesn't
+  /// exist for a particular channel, skip said channel.
+  PortMap requestPorts(const AppIDPath &idPath,
+                       const BundleType *bundleType) const;
+
+private:
+  /// Set a particlar engine for a particular channel. Should only be called by
+  /// AcceleratorConnection while registering engines.
+  void setEngine(const std::string &channelName, Engine *engine);
+  std::map<std::string, Engine *> bundleEngineMap;
+};
+
+namespace registry {
+
+/// Create an engine by name. This is the primary way to create engines for
+/// "normal" backends.
+std::unique_ptr<Engine> createEngine(AcceleratorConnection &conn,
+                                     const std::string &dmaEngineName,
+                                     AppIDPath idPath,
+                                     const ServiceImplDetails &details,
+                                     const HWClientDetails &clients);
+
+namespace internal {
+
+/// Engines can register themselves for pluggable functionality.
+using EngineCreate = std::function<std::unique_ptr<Engine>(
+    AcceleratorConnection &conn, AppIDPath idPath,
+    const ServiceImplDetails &details, const HWClientDetails &clients)>;
+void registerEngine(const std::string &name, EngineCreate create);
+
+/// Helper struct to register engines.
+template <typename TEngine>
+struct RegisterEngine {
+  RegisterEngine(const char *name) { registerEngine(name, &TEngine::create); }
+};
+
+#define CONCAT_(prefix, suffix) prefix##suffix
+#define CONCAT(prefix, suffix) CONCAT_(prefix, suffix)
+#define REGISTER_ENGINE(Name, TEngine)                                         \
+  static ::esi::registry::internal::RegisterEngine<TEngine> CONCAT(            \
+      __register_engine__, __LINE__)(Name)
+
+} // namespace internal
+} // namespace registry
+
+} // namespace esi
+
+#endif // ESI_PORTS_H

esiaccel/include/esi/Logging.h

@@ -35,15 +35,19 @@ namespace esi {
 class Logger {
 public:
   enum class Level {
-    Debug,   // Everything and the kitchen sink, possibly including _all_
-             // messages written and read.
-    Info,    // General information, like connecting to an accelerator.
+    Trace, // Trace is even more detailed than debug and requires a compiler
+           // flag to be enabled when the runtime is built. Allows clients to do
+           // things like log every single message or interaction.
+    Debug, // Information useful when trying to debug an application.
+    Info,  // General information, like connecting to an accelerator.
     Warning, // May indicate a problem.
     Error,   // Many errors will be followed by exceptions which may get caught.
   };
-  Logger(bool debugEnabled) : debugEnabled(debugEnabled) {}
+  Logger(bool debugEnabled, bool traceEnabled)
+      : debugEnabled(debugEnabled), traceEnabled(traceEnabled) {}
   virtual ~Logger() = default;
   bool getDebugEnabled() { return debugEnabled; }
+  bool getTraceEnabled() { return traceEnabled; }
 
   /// Report a log message.
   /// Arguments:
@@ -95,6 +99,35 @@ public:
       debugImpl(debugFunc);
   }
 
+  /// Log a trace message. If tracing is not enabled, this is a no-op. Since it
+  /// is inlined, the compiler will hopefully optimize it away creating a
+  /// zero-overhead call. This means that clients are free to go crazy with
+  /// trace messages.
+  inline void trace(const std::string &subsystem, const std::string &msg,
+                    const std::map<std::string, std::any> *details = nullptr) {
+#ifdef ESI_RUNTIME_TRACE
+    if (traceEnabled)
+      log(Level::Trace, subsystem, msg, details);
+#endif
+  }
+  /// Log a trace message using a callback. Same as above, users can go hog-wild
+  /// calling this.
+  inline void
+  trace(std::function<
+        void(std::string &subsystem, std::string &msg,
+             std::unique_ptr<std::map<std::string, std::any>> &details)>
+            traceFunc) {
+#ifdef ESI_RUNTIME_TRACE
+    if (!traceEnabled)
+      return;
+    std::string subsystem;
+    std::string msg;
+    std::unique_ptr<std::map<std::string, std::any>> details = nullptr;
+    traceFunc(subsystem, msg, details);
+    log(Level::Trace, subsystem, msg, details.get());
+#endif
+  }
+
 protected:
   /// Overrideable version of debug. Only gets called if debug is enabled.
   virtual void debugImpl(const std::string &subsystem, const std::string &msg,
@@ -118,6 +151,9 @@ protected:
 
   /// Enable or disable debug messages.
   bool debugEnabled = false;
+
+  /// Enable or disable trace messages.
+  bool traceEnabled;
 };
 
 /// A thread-safe logger which calls functions implemented by subclasses. Only
@@ -147,8 +183,8 @@ public:
   /// Create a stream logger that logs to the given output stream and error
   /// output stream.
   StreamLogger(Level minLevel, std::ostream &out, std::ostream &error)
-      : TSLogger(minLevel == Level::Debug), minLevel(minLevel), outStream(out),
-        errorStream(error) {}
+      : TSLogger(minLevel <= Level::Debug, minLevel <= Level::Trace),
+        minLevel(minLevel), outStream(out), errorStream(error) {}
   /// Create a stream logger that logs to stdout, stderr.
   StreamLogger(Level minLevel);
   void logImpl(Level level, const std::string &subsystem,
@@ -182,7 +218,7 @@ private:
 /// A logger that does nothing.
 class NullLogger : public Logger {
 public:
-  NullLogger() : Logger(false) {}
+  NullLogger() : Logger(false, false) {}
   void log(Level, const std::string &, const std::string &,
            const std::map<std::string, std::any> *) override {}
 };

esiaccel/include/esi/Services.h

@@ -337,6 +337,50 @@ private:
   std::string symbol;
 };
 
+/// Service for retrieving telemetry data from the accelerator.
+class TelemetryService : public Service {
+public:
+  static constexpr std::string_view StdName = "esi.service.std.telemetry";
+
+  TelemetryService(AppIDPath id, AcceleratorConnection &,
+                   ServiceImplDetails details, HWClientDetails clients);
+
+  virtual std::string getServiceSymbol() const override;
+  virtual BundlePort *getPort(AppIDPath id,
+                              const BundleType *type) const override;
+
+  /// A telemetry port which gets attached to a service port.
+  class Telemetry : public ServicePort {
+    friend class TelemetryService;
+    Telemetry(AppID id, const BundleType *type, PortMap channels);
+
+  public:
+    static Telemetry *get(AppID id, BundleType *type, WriteChannelPort &get,
+                          ReadChannelPort &data);
+
+    void connect();
+    std::future<MessageData> read();
+
+    virtual std::optional<std::string> toString() const override {
+      const esi::Type *dataType =
+          dynamic_cast<const ChannelType *>(type->findChannel("data").first)
+              ->getInner();
+      return "telemetry " + dataType->getID();
+    }
+
+  private:
+    WriteChannelPort *get_req;
+    ReadChannelPort *data;
+  };
+
+  const std::map<AppIDPath, Telemetry *> &getTelemetryPorts() {
+    return telemetryPorts;
+  }
+
+private:
+  mutable std::map<AppIDPath, Telemetry *> telemetryPorts;
+};
+
 /// Registry of services which can be instantiated directly by the Accelerator
 /// class if the backend doesn't do anything special with a service.
 class ServiceRegistry {

esiaccel/include/esi/backends/Cosim.h

@@ -0,0 +1,85 @@
+//===- Cosim.h - ESI C++ cosimulation backend -------------------*- C++ -*-===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+//
+// This is a specialization of the ESI C++ API (backend) for connection into a
+// simulation of an ESI system. Currently uses Cap'nProto RPC, but that could
+// change. Requires Cap'nProto C++ library.
+//
+// DO NOT EDIT!
+// This file is distributed as part of an ESI package. The source for this file
+// should always be modified within CIRCT (lib/dialect/ESI/runtime/cpp).
+//
+//===----------------------------------------------------------------------===//
+
+// NOLINTNEXTLINE(llvm-header-guard)
+#ifndef ESI_BACKENDS_COSIM_H
+#define ESI_BACKENDS_COSIM_H
+
+#include "esi/Accelerator.h"
+
+#include <memory>
+#include <set>
+
+namespace esi {
+namespace cosim {
+class ChannelDesc;
+}
+
+namespace backends {
+namespace cosim {
+class CosimEngine;
+
+/// Connect to an ESI simulation.
+class CosimAccelerator : public esi::AcceleratorConnection {
+  friend class CosimEngine;
+
+public:
+  CosimAccelerator(Context &, std::string hostname, uint16_t port);
+  ~CosimAccelerator();
+
+  static std::unique_ptr<AcceleratorConnection>
+  connect(Context &, std::string connectionString);
+
+  // Different ways to retrieve the manifest in Cosimulation.
+  enum ManifestMethod {
+    Cosim, // Use the backdoor cosim interface. Default.
+    MMIO,  // Use MMIO emulation.
+  };
+  // Set the way this connection will retrieve the manifest.
+  void setManifestMethod(ManifestMethod method);
+
+  // C++ doesn't have a mechanism to forward declare a nested class and we don't
+  // want to include the generated header here. So we have to wrap it in a
+  // forward-declared struct we write ourselves.
+  struct StubContainer;
+
+  void createEngine(const std::string &engineTypeName, AppIDPath idPath,
+                    const ServiceImplDetails &details,
+                    const HWClientDetails &clients) override;
+
+protected:
+  virtual Service *createService(Service::Type service, AppIDPath path,
+                                 std::string implName,
+                                 const ServiceImplDetails &details,
+                                 const HWClientDetails &clients) override;
+
+private:
+  StubContainer *rpcClient;
+
+  // We own all channels connected to rpcClient since their lifetime is tied to
+  // rpcClient.
+  std::set<std::unique_ptr<ChannelPort>> channels;
+
+  ManifestMethod manifestMethod = Cosim;
+};
+
+} // namespace cosim
+} // namespace backends
+} // namespace esi
+
+#endif // ESI_BACKENDS_COSIM_H

esiaccel/include/esi/backends/RpcServer.h

@@ -0,0 +1,55 @@
+//===- RpcServer.h - Run a cosim server -------------------------*- C++ -*-===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+//
+// Setup and run a server accepting connections via the 'cosim' RPC protocol.
+// Then, one can request ports to and from the clients.
+//
+// Abstract this out to support multi-party communication in the future.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef ESI_COSIM_RPCSERVER_H
+#define ESI_COSIM_RPCSERVER_H
+
+#include "esi/Ports.h"
+
+namespace esi {
+namespace cosim {
+
+/// TODO: make this a proper backend (as much as possible).
+class RpcServer {
+public:
+  ~RpcServer();
+
+  /// Set the manifest and version. There is a race condition here in that the
+  /// RPC server can be started and a connection from the client could happen
+  /// before the manifest is set. TODO: rework the DPI API to require that the
+  /// manifest gets set first.
+  void setManifest(int esiVersion,
+                   const std::vector<uint8_t> &compressedManifest);
+
+  /// Register a read or write port which communicates over RPC.
+  ReadChannelPort &registerReadPort(const std::string &name,
+                                    const std::string &type);
+  WriteChannelPort &registerWritePort(const std::string &name,
+                                      const std::string &type);
+
+  void stop();
+  void run(int port);
+
+  /// Hide the implementation details from this header file.
+  class Impl;
+
+private:
+  Impl *impl = nullptr;
+};
+
+} // namespace cosim
+} // namespace esi
+
+#endif // ESI_COSIM_RPCSERVER_H