esiaccel 0.1.5.dev205__cp39-cp39-win_amd64.whl → 0.1.5.dev533__cp39-cp39-win_amd64.whl

esiaccel/cosim/verilator.py

@@ -4,7 +4,7 @@
 
 import os
 from pathlib import Path
-from typing import List
+from typing import List, Optional, Callable, Dict
 
 from .simulator import CosimCollateralDir, Simulator, SourceFiles
 
@@ -14,9 +14,29 @@ class Verilator(Simulator):
 
   DefaultDriver = CosimCollateralDir / "driver.cpp"
 
-  def __init__(self, sources: SourceFiles, run_dir: Path, debug: bool):
-    super().__init__(sources, run_dir, debug)
-
+  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,
+  ):
+    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.verilator = "verilator"
     if "VERILATOR_PATH" in os.environ:
       self.verilator = os.environ["VERILATOR_PATH"]
@@ -25,6 +45,15 @@ class Verilator(Simulator):
     cmd: List[str] = [
         self.verilator,
         "--cc",
+    ]
+
+    if self.macro_definitions:
+      cmd += [
+          f"+define+{k}={v}" if v is not None else f"+define+{k}"
+          for k, v in self.macro_definitions.items()
+      ]
+
+    cmd += [
         "--top-module",
         self.sources.top,
         "-DSIMULATION",
@@ -36,6 +65,7 @@ class Verilator(Simulator):
         "-j",
         "0",
         "--output-split",
+        "--autoflush",
         "--assert",
         str(Verilator.DefaultDriver),
     ]
@@ -44,7 +74,8 @@ class Verilator(Simulator):
     ]
     if self.debug:
       cmd += [
-          "--trace", "--trace-params", "--trace-structs", "--trace-underscore"
+          "--trace-fst", "--trace-params", "--trace-structs",
+          "--trace-underscore"
       ]
       cflags.append("-DTRACE")
     if len(cflags) > 0:

esiaccel/include/esi/Accelerator.h

@@ -65,8 +65,8 @@ public:
   Accelerator(std::optional<ModuleInfo> info,
               std::vector<std::unique_ptr<Instance>> children,
               std::vector<services::Service *> services,
-              std::vector<std::unique_ptr<BundlePort>> &ports)
-      : HWModule(info, std::move(children), services, ports) {}
+              std::vector<std::unique_ptr<BundlePort>> &&ports)
+      : HWModule(info, std::move(children), services, std::move(ports)) {}
 };
 
 //===----------------------------------------------------------------------===//
@@ -86,13 +86,6 @@ public:
   /// Disconnect from the accelerator cleanly.
   virtual void disconnect();
 
-  // While building the design, keep around a std::map of active services
-  // indexed by the service name. When a new service is encountered during
-  // descent, add it to the table (perhaps overwriting one). Modifications to
-  // the table only apply to the current branch, so copy this and update it at
-  // each level of the tree.
-  using ServiceTable = std::map<std::string, services::Service *>;
-
   /// Return a pointer to the accelerator 'service' thread (or threads). If the
   /// thread(s) are not running, they will be started when this method is
   /// called. `std::thread` is used. If users don't want the runtime to spin up
@@ -165,7 +158,7 @@ private:
 
   /// Cache services via a unique_ptr so they get free'd automatically when
   /// Accelerator objects get deconstructed.
-  using ServiceCacheKey = std::tuple<const std::type_info *, AppIDPath>;
+  using ServiceCacheKey = std::tuple<std::string, AppIDPath>;
   std::map<ServiceCacheKey, std::unique_ptr<Service>> serviceCache;
 
   std::unique_ptr<AcceleratorServiceThread> serviceThread;
@@ -176,12 +169,6 @@ private:
 
 namespace registry {
 
-// Connect to an ESI accelerator given a backend name and connection specifier.
-// Alternatively, instantiate the backend directly (if you're using C++).
-std::unique_ptr<AcceleratorConnection> connect(Context &ctxt,
-                                               const std::string &backend,
-                                               const std::string &connection);
-
 namespace internal {
 
 /// Backends can register themselves to be connected via a connection string.

esiaccel/include/esi/CLI.h

@@ -51,19 +51,19 @@ public:
       ctxt = Context::withLogger<ConsoleLogger>(Logger::Level::Debug);
     else if (verbose)
       ctxt = Context::withLogger<ConsoleLogger>(Logger::Level::Info);
+    else
+      ctxt = Context::withLogger<ConsoleLogger>(Logger::Level::Warning);
     return 0;
   }
 
   /// Connect to the accelerator using the specified backend and connection.
-  std::unique_ptr<AcceleratorConnection> connect() {
-    return ctxt.connect(backend, connStr);
-  }
+  AcceleratorConnection *connect() { return ctxt->connect(backend, connStr); }
 
   /// Get the context.
-  Context &getContext() { return ctxt; }
+  Context &getContext() { return *ctxt; }
 
 protected:
-  Context ctxt;
+  std::unique_ptr<Context> ctxt;
 
   std::string backend;
   std::string connStr;

esiaccel/include/esi/Common.h

@@ -43,6 +43,13 @@ struct AppID {
     return name == other.name && idx == other.idx;
   }
   bool operator!=(const AppID &other) const { return !(*this == other); }
+  friend std::ostream &operator<<(std::ostream &os, const AppID &id);
+
+  std::string toString() const {
+    if (idx.has_value())
+      return name + "[" + std::to_string(idx.value()) + "]";
+    return name;
+  }
 };
 bool operator<(const AppID &a, const AppID &b);
 
@@ -53,6 +60,7 @@ public:
   AppIDPath operator+(const AppIDPath &b) const;
   AppIDPath parent() const;
   std::string toStr() const;
+  friend std::ostream &operator<<(std::ostream &os, const AppIDPath &path);
 };
 bool operator<(const AppIDPath &a, const AppIDPath &b);
 
@@ -106,6 +114,8 @@ class MessageData {
 public:
   /// Adopts the data vector buffer.
   MessageData() = default;
+  MessageData(std::span<const uint8_t> data)
+      : data(data.data(), data.data() + data.size()) {}
   MessageData(std::vector<uint8_t> &data) : data(std::move(data)) {}
   MessageData(std::vector<uint8_t> &&data) : data(std::move(data)) {}
   MessageData(const uint8_t *data, size_t size) : data(data, data + size) {}
@@ -126,6 +136,7 @@ public:
 
   /// Get the size of the data in bytes.
   size_t getSize() const { return data.size(); }
+  size_t size() const { return getSize(); }
 
   /// Returns true if this message contains no data.
   bool empty() const { return data.empty(); }
@@ -158,7 +169,6 @@ private:
 } // namespace esi
 
 std::ostream &operator<<(std::ostream &, const esi::ModuleInfo &);
-std::ostream &operator<<(std::ostream &, const esi::AppID &);
 
 //===----------------------------------------------------------------------===//
 // Functions which should be in the standard library.

esiaccel/include/esi/Context.h

@@ -20,23 +20,30 @@
 #include "esi/Types.h"
 
 #include <exception>
+#include <map>
 #include <memory>
-#include <optional>
+#include <vector>
 
 namespace esi {
 class AcceleratorConnection;
 
 /// AcceleratorConnections, Accelerators, and Manifests must all share a
-/// context. It owns all the types, uniquifying them.
+/// context. It owns all the types, uniquifying them. It also owns the
+/// connections (which own the Accelerators). When it is destroyed, all
+/// connections are disconnected and the objects are destroyed.
 class Context {
 public:
-  Context() : logger(std::make_unique<ConsoleLogger>(Logger::Level::Warning)) {}
-  Context(std::unique_ptr<Logger> logger) : logger(std::move(logger)) {}
+  Context();
+  Context(std::unique_ptr<Logger> logger);
+  ~Context();
+
+  /// Disconnect from all accelerators associated with this context.
+  void disconnectAll();
 
   /// Create a context with a specific logger type.
   template <typename T, typename... Args>
-  static Context withLogger(Args &&...args) {
-    return Context(std::make_unique<T>(args...));
+  static std::unique_ptr<Context> withLogger(Args &&...args) {
+    return std::make_unique<Context>(std::make_unique<T>(args...));
   }
 
   /// Resolve a type id to the type.
@@ -49,9 +56,9 @@ public:
   /// Register a type with the context. Takes ownership of the pointer type.
   void registerType(Type *type);
 
-  /// Connect to an accelerator backend.
-  std::unique_ptr<AcceleratorConnection> connect(std::string backend,
-                                                 std::string connection);
+  /// Connect to an accelerator backend. Retains ownership internally and
+  /// returns a non-owning pointer.
+  AcceleratorConnection *connect(std::string backend, std::string connection);
 
   /// Register a logger with the accelerator. Assumes ownership of the logger.
   void setLogger(std::unique_ptr<Logger> logger) {
@@ -63,6 +70,7 @@ public:
 
 private:
   std::unique_ptr<Logger> logger;
+  std::vector<std::unique_ptr<AcceleratorConnection>> connections;
 
 private:
   using TypeCache = std::map<Type::ID, std::unique_ptr<Type>>;

esiaccel/include/esi/Design.h

@@ -45,11 +45,15 @@ class Service;
 
 /// Represents either the top level or an instance of a hardware module.
 class HWModule {
+public:
+  HWModule(const HWModule &) = delete;
+  HWModule &operator=(const HWModule &) = delete;
+
 protected:
   HWModule(std::optional<ModuleInfo> info,
            std::vector<std::unique_ptr<Instance>> children,
            std::vector<services::Service *> services,
-           std::vector<std::unique_ptr<BundlePort>> &ports);
+           std::vector<std::unique_ptr<BundlePort>> &&ports);
 
 public:
   virtual ~HWModule() = default;
@@ -112,11 +116,12 @@ public:
   Instance(AppID id, std::optional<ModuleInfo> info,
            std::vector<std::unique_ptr<Instance>> children,
            std::vector<services::Service *> services,
-           std::vector<std::unique_ptr<BundlePort>> &ports)
-      : HWModule(info, std::move(children), services, ports), id(id) {}
+           std::vector<std::unique_ptr<BundlePort>> &&ports)
+      : HWModule(info, std::move(children), services, std::move(ports)),
+        id(id) {}
 
   /// Get the instance's ID, which it will always have.
-  const AppID getID() const { return id; }
+  AppID getID() const { return id; }
 
 protected:
   const AppID id;

esiaccel/include/esi/Manifest.h

@@ -65,8 +65,6 @@ private:
 
 } // namespace esi
 
-std::ostream &operator<<(std::ostream &os, const esi::AppID &id);
-std::ostream &operator<<(std::ostream &, const esi::AppIDPath &);
 std::ostream &operator<<(std::ostream &, const esi::ModuleInfo &);
 
 #endif // ESI_MANIFEST_H

esiaccel/include/esi/Ports.h

@@ -35,13 +35,63 @@ using PortMap = std::map<std::string, ChannelPort &>;
 /// but used by higher level APIs which add types.
 class ChannelPort {
 public:
-  ChannelPort(const Type *type) : type(type) {}
+  ChannelPort(const Type *type);
   virtual ~ChannelPort() {}
 
-  /// Set up a connection to the accelerator. The buffer size is optional and
-  /// should be considered merely a hint. Individual implementations use it
-  /// however they like. The unit is number of messages of the port type.
-  virtual void connect(std::optional<unsigned> bufferSize = std::nullopt) = 0;
+  struct ConnectOptions {
+    /// The buffer size is optional and should be considered merely a hint.
+    /// Individual implementations use it however they like. The unit is number
+    /// of messages of the port type.
+    std::optional<unsigned> bufferSize = std::nullopt;
+
+    /// If the type of this port is a window, translate the incoming/outgoing
+    /// data into its underlying ('into') type. For 'into' types without lists,
+    /// just re-arranges the data fields from the lowered type to the 'into'
+    /// type.
+    ///
+    /// If this option is false, no translation is done and the data is
+    /// passed through as-is. Same is true for non-windowed types.
+    ///
+    /// For messages with lists, only two types are supported:
+    ///   1) Parallel encoding includes any 'header' data with each frame. Said
+    ///      header data is the same across all frames, so this encoding is
+    ///      inefficient but is commonly used for on-chip streaming interfaces.
+    ///      Each frame contains a 'last' field to indicate the end of the list.
+    ///      In cases where 'numItems' is greater than 1, a field named
+    ///      '<listField>_size' indicates the number of valid items in that
+    ///      frame.
+    ///   2) Serial (bulk transfer) encoding, where a 'header' frame precedes
+    ///      the list data frame. Said header frame contains a 'count' field
+    ///      indicating the number of items in the list.  Importantly, the
+    ///      header frame is always re-transmitted after the specified number of
+    ///      list items have been sent. If the 'count' field is zero, the end of
+    ///      the list has been reached. If it is non-zero, the message has not
+    ///      been completely transmitted and reading should continue until a
+    ///      'count' of zero is received.
+    ///
+    /// In both cases, the returned MessageData contains the complete header
+    /// followed by the list data. In other words, header data is not duplicated
+    /// in the returned message.
+    ///
+    /// Important note: for consistency, preserves SystemVerilog struct field
+    /// ordering! So it's the opposite of C struct ordering.
+    ///
+    /// Implementation status:
+    ///   - Lists are not yet supported.
+    ///   - Write ports are not yet supported.
+    ///   - Fields must be byte-aligned.
+    ///
+    /// See the CIRCT documentation (or td files) for more details on windowed
+    /// messages.
+    bool translateMessage = true;
+
+    ConnectOptions(std::optional<unsigned> bufferSize = std::nullopt,
+                   bool translateMessage = true)
+        : bufferSize(bufferSize), translateMessage(translateMessage) {}
+  };
+
+  /// Set up a connection to the accelerator.
+  virtual void connect(const ConnectOptions &options = ConnectOptions()) = 0;
   virtual void disconnect() = 0;
   virtual bool isConnected() const = 0;
 
@@ -63,6 +113,7 @@ public:
 
 protected:
   const Type *type;
+  const WindowType *translationType;
 
   /// Method called by poll() to actually poll the channel if the channel is
   /// connected.
@@ -70,7 +121,7 @@ protected:
 
   /// Called by all connect methods to let backends initiate the underlying
   /// connections.
-  virtual void connectImpl(std::optional<unsigned> bufferSize) {}
+  virtual void connectImpl(const ConnectOptions &options) {}
 };
 
 /// A ChannelPort which sends data to the accelerator.
@@ -78,9 +129,8 @@ class WriteChannelPort : public ChannelPort {
 public:
   using ChannelPort::ChannelPort;
 
-  virtual void
-  connect(std::optional<unsigned> bufferSize = std::nullopt) override {
-    connectImpl(bufferSize);
+  virtual void connect(const ConnectOptions &options = {}) override {
+    connectImpl(options);
     connected = true;
   }
   virtual void disconnect() override { connected = false; }
@@ -105,7 +155,7 @@ public:
   UnknownWriteChannelPort(const Type *type, std::string errmsg)
       : WriteChannelPort(type), errmsg(errmsg) {}
 
-  void connect(std::optional<unsigned> bufferSize = std::nullopt) override {
+  void connect(const ConnectOptions &options = {}) override {
     throw std::runtime_error(errmsg);
   }
   void write(const MessageData &) override { throw std::runtime_error(errmsg); }
@@ -143,7 +193,7 @@ public:
   //===--------------------------------------------------------------------===//
 
   virtual void connect(std::function<bool(MessageData)> callback,
-                       std::optional<unsigned> bufferSize = std::nullopt);
+                       const ConnectOptions &options = {});
 
   //===--------------------------------------------------------------------===//
   // Polling mode methods: To use futures or blocking reads, connect without any
@@ -154,8 +204,7 @@ public:
   static constexpr uint64_t DefaultMaxDataQueueMsgs = 32;
 
   /// Connect to the channel in polling mode.
-  virtual void
-  connect(std::optional<unsigned> bufferSize = std::nullopt) override;
+  virtual void connect(const ConnectOptions &options = {}) override;
 
   /// Asynchronous read.
   virtual std::future<MessageData> readAsync();
@@ -184,6 +233,14 @@ protected:
   /// Backends call this callback when new data is available.
   std::function<bool(MessageData)> callback;
 
+  /// Window translation support.
+  std::vector<uint8_t> translationBuffer;
+  /// Index of the next expected frame (for multi-frame windows).
+  size_t nextFrameIndex = 0;
+  /// Translate incoming data if the port type is a window type. Returns true if
+  /// the message has been completely received.
+  bool translateIncoming(MessageData &data);
+
   //===--------------------------------------------------------------------===//
   // Polling mode members.
   //===--------------------------------------------------------------------===//
@@ -206,10 +263,10 @@ public:
       : ReadChannelPort(type), errmsg(errmsg) {}
 
   void connect(std::function<bool(MessageData)> callback,
-               std::optional<unsigned> bufferSize = std::nullopt) override {
+               const ConnectOptions &options = ConnectOptions()) override {
     throw std::runtime_error(errmsg);
   }
-  void connect(std::optional<unsigned> bufferSize = std::nullopt) override {
+  void connect(const ConnectOptions &options = ConnectOptions()) override {
     throw std::runtime_error(errmsg);
   }
   std::future<MessageData> readAsync() override {

esiaccel/include/esi/Services.h

@@ -25,10 +25,21 @@
 #include "esi/Ports.h"
 
 #include <cstdint>
+#include <list>
 
 namespace esi {
 class AcceleratorConnection;
 class Engine;
+namespace services {
+class Service;
+}
+
+// While building the design, keep around a std::map of active services indexed
+// by the service name. When a new service is encountered during descent, add it
+// to the table (perhaps overwriting one). Modifications to the table only apply
+// to the current branch, so copy this and update it at each level of the tree.
+using ServiceTable = std::map<std::string, services::Service *>;
+
 namespace services {
 
 /// Add a custom interface to a service client at a particular point in the
@@ -38,7 +49,9 @@ public:
   using BundlePort::BundlePort;
   virtual ~ServicePort() = default;
   // Get a description of the service port.
-  virtual std::optional<std::string> toString() const { return std::nullopt; }
+  virtual std::optional<std::string> toString(bool oneLine = false) const {
+    return std::nullopt;
+  }
 };
 
 /// Parent class of all APIs modeled as 'services'. May or may not map to a
@@ -170,7 +183,8 @@ public:
     /// Write a 64-bit value to this region, not the global address space.
     virtual void write(uint32_t addr, uint64_t data);
 
-    virtual std::optional<std::string> toString() const override {
+    virtual std::optional<std::string>
+    toString(bool oneLine = false) const override {
       return "MMIO region " + toHex(desc.base) + " - " +
              toHex(desc.base + desc.size);
     }
@@ -282,10 +296,12 @@ public:
           ->getInner();
     }
 
-    virtual std::optional<std::string> toString() const override {
+    virtual std::optional<std::string>
+    toString(bool oneLine = false) const override {
       const esi::Type *argType = getArgType();
       const esi::Type *resultType = getResultType();
-      return "function " + resultType->getID() + "(" + argType->getID() + ")";
+      return "function " + resultType->toString(oneLine) + "(" +
+             argType->toString(oneLine) + ")";
     }
 
   private:
@@ -338,10 +354,12 @@ public:
           ->getInner();
     }
 
-    virtual std::optional<std::string> toString() const override {
+    virtual std::optional<std::string>
+    toString(bool oneLine = false) const override {
       const esi::Type *argType = getArgType();
       const esi::Type *resultType = getResultType();
-      return "callback " + resultType->getID() + "(" + argType->getID() + ")";
+      return "callback " + resultType->toString(oneLine) + "(" +
+             argType->toString(oneLine) + ")";
     }
 
   private:
@@ -365,37 +383,51 @@ public:
   virtual std::string getServiceSymbol() const override;
   virtual BundlePort *getPort(AppIDPath id,
                               const BundleType *type) const override;
+  virtual Service *getChildService(Service::Type service, AppIDPath id = {},
+                                   std::string implName = {},
+                                   ServiceImplDetails details = {},
+                                   HWClientDetails clients = {}) override;
+  MMIO::MMIORegion *getMMIORegion() const;
 
   /// A telemetry port which gets attached to a service port.
-  class Telemetry : public ServicePort {
+  class Metric : public ServicePort {
     friend class TelemetryService;
-    Telemetry(AppID id, const BundleType *type, PortMap channels);
+    Metric(AppID id, const BundleType *type, PortMap channels,
+           const TelemetryService *telemetryService,
+           std::optional<uint64_t> offset);
 
   public:
-    static Telemetry *get(AppID id, BundleType *type, WriteChannelPort &get,
-                          ReadChannelPort &data);
-
     void connect();
     std::future<MessageData> read();
+    uint64_t readInt();
 
-    virtual std::optional<std::string> toString() const override {
+    virtual std::optional<std::string>
+    toString(bool oneLine = false) const override {
       const esi::Type *dataType =
           dynamic_cast<const ChannelType *>(type->findChannel("data").first)
               ->getInner();
-      return "telemetry " + dataType->getID();
+      return "telemetry " + dataType->toString(oneLine);
     }
 
   private:
-    WriteChannelPort *get_req;
-    ReadChannelPort *data;
+    const TelemetryService *telemetryService;
+    MMIO::MMIORegion *mmio;
+    std::optional<uint64_t> offset;
   };
 
-  const std::map<AppIDPath, Telemetry *> &getTelemetryPorts() {
-    return telemetryPorts;
+  std::map<AppIDPath, Metric *> getTelemetryPorts() {
+    std::map<AppIDPath, Metric *> ports;
+    getTelemetryPorts(ports);
+    return ports;
   }
+  void getTelemetryPorts(std::map<AppIDPath, Metric *> &ports);
 
 private:
-  mutable std::map<AppIDPath, Telemetry *> telemetryPorts;
+  AppIDPath id;
+  mutable MMIO::MMIORegion *mmio;
+  std::map<AppIDPath, uint64_t> portAddressAssignments;
+  mutable std::map<AppIDPath, Metric *> telemetryPorts;
+  std::list<TelemetryService *> children;
 };
 
 /// Registry of services which can be instantiated directly by the Accelerator