esiaccel 0.0.17.dev447__cp310-cp310-win_amd64.whl → 0.1.5.dev406__cp310-cp310-win_amd64.whl

esiaccel/esi-cosim.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+
+# ===- esi-cosim.py - ESI cosimulation launch utility --------*- python -*-===//
+#
+# 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
+#
+# ===----------------------------------------------------------------------===//
+#
+# Utility script to start a simulation and launch a command to interact with it
+# via ESI cosimulation.
+#
+# ===----------------------------------------------------------------------===//
+
+import argparse
+from pathlib import Path
+import sys
+import textwrap
+from typing import Dict, List
+
+from esiaccel.cosim.questa import Questa
+from esiaccel.cosim.verilator import Verilator
+from esiaccel.cosim.simulator import SourceFiles
+
+
+def __main__(args):
+  argparser = argparse.ArgumentParser(
+      description="Wrap a 'inner_cmd' in an ESI cosimulation environment.",
+      formatter_class=argparse.RawDescriptionHelpFormatter,
+      epilog=textwrap.dedent("""
+        Notes:
+          - For Verilator, libEsiCosimDpiServer.so must be in the dynamic
+          library runtime search path (LD_LIBRARY_PATH) and link time path
+          (LIBRARY_PATH). If it is installed to a standard location (e.g.
+          /usr/lib), this should be handled automatically.
+          - This script needs to sit in the same directory as the ESI support
+          SystemVerilog (e.g. Cosim_DpiPkg.sv, Cosim_MMIO.sv, etc.). It can,
+          however, be soft linked to a different location.
+          - The simulator executable(s) must be in your PATH.
+      """))
+
+  argparser.add_argument(
+      "--sim",
+      type=str,
+      default="verilator",
+      help="Name of the RTL simulator to use or path to an executable.")
+  argparser.add_argument("--rundir",
+                         default="run",
+                         help="Directory in which simulation should be run.")
+  argparser.add_argument(
+      "--top",
+      default="ESI_Cosim_Top",
+      help="Name of the 'top' module to use in the simulation.")
+  argparser.add_argument("--no-compile",
+                         action="store_true",
+                         help="Do not run the compile.")
+  argparser.add_argument("--debug",
+                         action="store_true",
+                         help="Enable debug output.")
+  argparser.add_argument("--gui",
+                         action="store_true",
+                         help="Run the simulator in GUI mode (if supported).")
+  argparser.add_argument("--source",
+                         help="Directories containing the source files.",
+                         default="hw")
+
+  argparser.add_argument("inner_cmd",
+                         nargs=argparse.REMAINDER,
+                         help="Command to run in the simulation environment.")
+
+  argparser.add_argument(
+      "--server-only",
+      action="store_true",
+      help="Only run the cosim server, and do not run any inner command.")
+
+  if len(args) <= 1:
+    argparser.print_help()
+    return
+  args = argparser.parse_args(args[1:])
+
+  sources = SourceFiles(args.top)
+  sources.add_dir(Path(args.source))
+
+  if args.sim == "verilator":
+    sim = Verilator(sources, Path(args.rundir), args.debug)
+  elif args.sim == "questa":
+    sim = Questa(sources, Path(args.rundir), args.debug)
+  else:
+    print("Unknown simulator: " + args.sim)
+    print("Supported simulators: ")
+    print("  - verilator")
+    print("  - questa")
+    return 1
+
+  if not args.no_compile:
+    rc = sim.compile()
+    if rc != 0:
+      return rc
+  return sim.run(args.inner_cmd[1:], gui=args.gui, server_only=args.server_only)
+
+
+if __name__ == '__main__':
+  sys.exit(__main__(sys.argv))

esiaccel/include/esi/Accelerator.h

@@ -23,6 +23,7 @@
 
 #include "esi/Context.h"
 #include "esi/Design.h"
+#include "esi/Engines.h"
 #include "esi/Manifest.h"
 #include "esi/Ports.h"
 #include "esi/Services.h"
@@ -85,18 +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 *>;
-
-  /// Request the host side channel ports for a particular instance (identified
-  /// by the AppID path). For convenience, provide the bundle type.
-  virtual std::map<std::string, ChannelPort &>
-  requestChannelsFor(AppIDPath, const BundleType *, const ServiceTable &) = 0;
-
   /// 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
@@ -126,7 +115,30 @@ public:
   /// accelerator to this connection. Returns a raw pointer to the object.
   Accelerator *takeOwnership(std::unique_ptr<Accelerator> accel);
 
+  /// Create a new engine for channel communication with the accelerator. The
+  /// default is to call the global `createEngine` to get an engine which has
+  /// registered itself. Individual accelerator connection backends can override
+  /// this to customize behavior.
+  virtual void createEngine(const std::string &engineTypeName, AppIDPath idPath,
+                            const ServiceImplDetails &details,
+                            const HWClientDetails &clients);
+  virtual const BundleEngineMap &getEngineMapFor(AppIDPath id) {
+    return clientEngines[id];
+  }
+
+  Accelerator &getAccelerator() {
+    if (!ownedAccelerator)
+      throw std::runtime_error(
+          "AcceleratorConnection does not own an accelerator");
+    return *ownedAccelerator;
+  }
+
 protected:
+  /// If `createEngine` is overridden, this method should be called to register
+  /// the engine and all of the channels it services.
+  void registerEngine(AppIDPath idPath, std::unique_ptr<Engine> engine,
+                      const HWClientDetails &clients);
+
   /// Called by `getServiceImpl` exclusively. It wraps the pointer returned by
   /// this in a unique_ptr and caches it. Separate this from the
   /// wrapping/caching since wrapping/caching is an implementation detail.
@@ -135,6 +147,11 @@ protected:
                                  const ServiceImplDetails &details,
                                  const HWClientDetails &clients) = 0;
 
+  /// Collection of owned engines.
+  std::map<AppIDPath, std::unique_ptr<Engine>> ownedEngines;
+  /// Mapping of clients to their servicing engines.
+  std::map<AppIDPath, BundleEngineMap> clientEngines;
+
 private:
   /// ESI accelerator context.
   Context &ctxt;
@@ -146,9 +163,8 @@ private:
 
   std::unique_ptr<AcceleratorServiceThread> serviceThread;
 
-  /// List of accelerator objects owned by this connection. These are destroyed
-  /// when the connection dies or is shutdown.
-  std::vector<std::unique_ptr<Accelerator>> ownedAccelerators;
+  /// Accelerator object owned by this connection.
+  std::unique_ptr<Accelerator> ownedAccelerator;
 };
 
 namespace registry {

esiaccel/include/esi/CLI.h

@@ -0,0 +1,77 @@
+//===- CLI.h - ESI runtime tool CLI parser common ---------------*- 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 file contains the common CLI parser code for ESI runtime tools. Exposed
+// publicly so that out-of-tree tools can use it. This is a header-only library
+// to make compilation easier for out-of-tree tools.
+//
+// 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_CLI_H
+#define ESI_CLI_H
+
+#include "CLI/CLI.hpp"
+#include "esi/Context.h"
+
+namespace esi {
+
+/// Common options and code for ESI runtime tools.
+class CliParser : public CLI::App {
+public:
+  CliParser(const std::string &toolName)
+      : CLI::App(toolName), debug(false), verbose(false) {
+    add_option("backend", backend, "Backend to use for connection")->required();
+    add_option("connection", connStr,
+               "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);
+  }
+
+  /// Run the parser.
+  int esiParse(int argc, const char **argv) {
+    CLI11_PARSE(*this, argc, argv);
+    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);
+    return 0;
+  }
+
+  /// Connect to the accelerator using the specified backend and connection.
+  std::unique_ptr<AcceleratorConnection> connect() {
+    return ctxt.connect(backend, connStr);
+  }
+
+  /// Get the context.
+  Context &getContext() { return ctxt; }
+
+protected:
+  Context ctxt;
+
+  std::string backend;
+  std::string connStr;
+  bool trace = false;
+  bool debug = false;
+  bool verbose = false;
+};
+
+} // namespace esi
+
+#endif // ESI_CLI_H

esiaccel/include/esi/Common.h

@@ -20,6 +20,7 @@
 #include <cstdint>
 #include <map>
 #include <optional>
+#include <span>
 #include <stdexcept>
 #include <string>
 #include <vector>
@@ -42,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);
 
@@ -49,8 +57,10 @@ class AppIDPath : public std::vector<AppID> {
 public:
   using std::vector<AppID>::vector;
 
-  AppIDPath operator+(const AppIDPath &b);
+  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);
 
@@ -104,13 +114,32 @@ 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) {}
   ~MessageData() = default;
 
   const uint8_t *getBytes() const { return data.data(); }
+
+  /// Get the data as a vector of bytes.
+  const std::vector<uint8_t> &getData() const { return data; }
+
+  /// Implicit conversion to a vector/span of bytes, to play nice with other
+  /// APIs that accept bytearray-like things.
+  operator const std::vector<uint8_t> &() const { return data; }
+  operator std::span<const uint8_t>() const { return data; }
+
+  /// Move the data out of this object.
+  std::vector<uint8_t> takeData() { return std::move(data); }
+
   /// 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(); }
 
   /// Cast to a type. Throws if the size of the data does not match the size of
   /// the message. The lifetime of the resulting pointer is tied to the lifetime
@@ -140,14 +169,14 @@ 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.
 //===----------------------------------------------------------------------===//
 
 namespace esi {
-std::string toHex(uint32_t val);
+std::string toHex(void *val);
+std::string toHex(uint64_t val);
 } // namespace esi
 
 #endif // ESI_COMMON_H

esiaccel/include/esi/Context.h

@@ -30,7 +30,7 @@ class AcceleratorConnection;
 /// context. It owns all the types, uniquifying them.
 class Context {
 public:
-  Context() : logger(std::make_unique<NullLogger>()) {}
+  Context() : logger(std::make_unique<ConsoleLogger>(Logger::Level::Warning)) {}
   Context(std::unique_ptr<Logger> logger) : logger(std::move(logger)) {}
 
   /// Create a context with a specific logger type.

esiaccel/include/esi/Design.h

@@ -73,9 +73,7 @@ public:
     return ret;
   }
   /// Access the module's ports by ID.
-  const std::map<AppID, const BundlePort &> &getPorts() const {
-    return portIndex;
-  }
+  const std::map<AppID, BundlePort &> &getPorts() const { return portIndex; }
   /// Access the services provided by this module.
   const std::vector<services::Service *> &getServices() const {
     return services;
@@ -86,13 +84,22 @@ public:
   /// the `poll` calls returns true.
   bool poll();
 
+  /// Attempt to resolve a path to a module instance. If a child is not found,
+  /// return null and set lastLookup to the path which wasn't found.
+  const HWModule *resolveInst(const AppIDPath &path,
+                              AppIDPath &lastLookup) const;
+
+  /// Attempt to resolve a path to a port. If a child or port is not found,
+  /// return null and set lastLookup to the path which wasn't found.
+  BundlePort *resolvePort(const AppIDPath &path, AppIDPath &lastLookup) const;
+
 protected:
   const std::optional<ModuleInfo> info;
   const std::vector<std::unique_ptr<Instance>> children;
   const std::map<AppID, Instance *> childIndex;
   const std::vector<services::Service *> services;
   const std::vector<std::unique_ptr<BundlePort>> ports;
-  const std::map<AppID, const BundlePort &> portIndex;
+  const std::map<AppID, BundlePort &> portIndex;
 };
 
 /// Subclass of `HWModule` which represents a submodule instance. Adds an AppID,

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,
@@ -165,10 +201,24 @@ private:
   std::ostream &errorStream;
 };
 
+/// A logger that writes to the console. Includes color support.
+class ConsoleLogger : public TSLogger {
+public:
+  /// Create a stream logger that logs to stdout, stderr.
+  ConsoleLogger(Level minLevel);
+  void logImpl(Level level, const std::string &subsystem,
+               const std::string &msg,
+               const std::map<std::string, std::any> *details) override;
+
+private:
+  /// The minimum log level to emit.
+  Level minLevel;
+};
+
 /// 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/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