esiaccel 0.2.3.dev80__cp314-cp314-win_amd64.whl

esiaccel/include/esi/Accelerator.h

@@ -0,0 +1,229 @@
+//===- Accelerator.h - Base ESI runtime API ---------------------*- 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
+//
+//===----------------------------------------------------------------------===//
+//
+// Basic ESI APIs. The 'Accelerator' class is the superclass for all accelerator
+// backends. It should (usually) provide enough functionality such that users do
+// not have to interact with the platform-specific backend implementation with
+// the exception of connecting to the accelerator.
+//
+// DO NOT EDIT!
+// This file is distributed as part of an ESI package. The source for this file
+// should always be modified within CIRCT.
+//
+//===----------------------------------------------------------------------===//
+
+// NOLINTNEXTLINE(llvm-header-guard)
+#ifndef ESI_ACCELERATOR_H
+#define ESI_ACCELERATOR_H
+
+#include "esi/Context.h"
+#include "esi/Design.h"
+#include "esi/Engines.h"
+#include "esi/Manifest.h"
+#include "esi/Ports.h"
+#include "esi/Services.h"
+
+#include <functional>
+#include <map>
+#include <memory>
+#include <string>
+#include <typeinfo>
+
+namespace esi {
+// Forward declarations.
+class AcceleratorServiceThread;
+
+//===----------------------------------------------------------------------===//
+// Metadata constants which may or may not be used by various backends. Provided
+// here since they are intended to be somewhat standard.
+//===----------------------------------------------------------------------===//
+
+constexpr uint32_t MetadataOffset = 8;
+
+constexpr uint64_t MagicNumberLo = 0xE5100E51;
+constexpr uint64_t MagicNumberHi = 0x207D98E5;
+constexpr uint64_t MagicNumber = MagicNumberLo | (MagicNumberHi << 32);
+constexpr uint64_t MagicNumberOffset = 0;
+
+constexpr uint32_t ExpectedVersionNumber = 0;
+constexpr uint64_t VersionNumberOffset = 8;
+
+constexpr uint32_t ManifestPtrOffset = 0x10;
+
+constexpr uint32_t CycleCountOffset = 0x20;
+constexpr uint32_t CoreFreqOffset = 0x28;
+
+//===----------------------------------------------------------------------===//
+// Accelerator design hierarchy root.
+//===----------------------------------------------------------------------===//
+
+/// Top level accelerator class. Maintains a shared pointer to the manifest,
+/// which owns objects used in the design hierarchy owned by this class. Since
+/// this class owns the entire design hierarchy, when it gets destroyed the
+/// entire design hierarchy gets destroyed so all of the instances, ports, etc.
+/// are no longer valid pointers.
+class Accelerator : public HWModule {
+public:
+  Accelerator() = delete;
+  Accelerator(const Accelerator &) = delete;
+  ~Accelerator() = default;
+  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, std::move(ports)) {}
+};
+
+//===----------------------------------------------------------------------===//
+// Connection to the accelerator and its services.
+//===----------------------------------------------------------------------===//
+
+/// Abstract class representing a connection to an accelerator. Actual
+/// connections (e.g. to a co-simulation or actual device) are implemented by
+/// subclasses. No methods in here are thread safe.
+class AcceleratorConnection {
+public:
+  AcceleratorConnection(Context &ctxt);
+  virtual ~AcceleratorConnection();
+  Context &getCtxt() const { return ctxt; }
+  Logger &getLogger() const { return ctxt.getLogger(); }
+
+  /// Disconnect from the accelerator cleanly.
+  virtual void disconnect();
+
+  /// 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
+  /// threads, don't call this method. `AcceleratorServiceThread` is owned by
+  /// AcceleratorConnection and governed by the lifetime of the this object.
+  AcceleratorServiceThread *getServiceThread();
+
+  using Service = services::Service;
+  /// Get a typed reference to a particular service type. Caller does *not* take
+  /// ownership of the returned pointer -- the Accelerator object owns it.
+  /// Pointer lifetime ends with the Accelerator lifetime.
+  template <typename ServiceClass>
+  ServiceClass *getService(AppIDPath id = {}, std::string implName = {},
+                           ServiceImplDetails details = {},
+                           HWClientDetails clients = {}) {
+    return dynamic_cast<ServiceClass *>(
+        getService(typeid(ServiceClass), id, implName, details, clients));
+  }
+  /// Calls `createService` and caches the result. Subclasses can override if
+  /// they want to use their own caching mechanism.
+  virtual Service *getService(Service::Type service, AppIDPath id = {},
+                              std::string implName = {},
+                              ServiceImplDetails details = {},
+                              HWClientDetails clients = {});
+
+  /// Assume ownership of an accelerator object. Ties the lifetime of the
+  /// 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.
+  virtual Service *createService(Service::Type service, AppIDPath idPath,
+                                 std::string implName,
+                                 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;
+
+  /// Cache services via a unique_ptr so they get free'd automatically when
+  /// Accelerator objects get deconstructed.
+  using ServiceCacheKey = std::tuple<std::string, AppIDPath>;
+  std::map<ServiceCacheKey, std::unique_ptr<Service>> serviceCache;
+
+  std::unique_ptr<AcceleratorServiceThread> serviceThread;
+
+  /// Accelerator object owned by this connection.
+  std::unique_ptr<Accelerator> ownedAccelerator;
+};
+
+namespace registry {
+
+namespace internal {
+
+/// Backends can register themselves to be connected via a connection string.
+using BackendCreate = std::function<std::unique_ptr<AcceleratorConnection>(
+    Context &, std::string)>;
+void registerBackend(const std::string &name, BackendCreate create);
+
+// Helper struct to
+template <typename TAccelerator>
+struct RegisterAccelerator {
+  RegisterAccelerator(const char *name) {
+    registerBackend(name, &TAccelerator::connect);
+  }
+};
+
+#define REGISTER_ACCELERATOR(Name, TAccelerator)                               \
+  static ::esi::registry::internal::RegisterAccelerator<TAccelerator>          \
+  __register_accel____LINE__(Name)
+
+} // namespace internal
+} // namespace registry
+
+/// Background thread which services various requests. Currently, it listens on
+/// ports and calls callbacks for incoming messages on said ports.
+class AcceleratorServiceThread {
+public:
+  AcceleratorServiceThread();
+  ~AcceleratorServiceThread();
+
+  /// When there's data on any of the listenPorts, call the callback. Callable
+  /// from any thread.
+  void
+  addListener(std::initializer_list<ReadChannelPort *> listenPorts,
+              std::function<void(ReadChannelPort *, MessageData)> callback);
+
+  /// Poll this module.
+  void addPoll(HWModule &module);
+
+  /// Instruct the service thread to stop running.
+  void stop();
+
+private:
+  struct Impl;
+  std::unique_ptr<Impl> impl;
+};
+} // namespace esi
+
+#endif // ESI_ACCELERATOR_H

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);
+    else
+      ctxt = Context::withLogger<ConsoleLogger>(Logger::Level::Warning);
+    return 0;
+  }
+
+  /// Connect to the accelerator using the specified backend and connection.
+  AcceleratorConnection *connect() { return ctxt->connect(backend, connStr); }
+
+  /// Get the context.
+  Context &getContext() { return *ctxt; }
+
+protected:
+  std::unique_ptr<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

@@ -0,0 +1,182 @@
+//===- Common.h - Commonly used classes w/o dependencies --------*- 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.
+//
+//===----------------------------------------------------------------------===//
+
+// NOLINTNEXTLINE(llvm-header-guard)
+#ifndef ESI_COMMON_H
+#define ESI_COMMON_H
+
+#include <any>
+#include <cstdint>
+#include <map>
+#include <optional>
+#include <span>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+namespace esi {
+class Type;
+
+//===----------------------------------------------------------------------===//
+// Common accelerator description types.
+//===----------------------------------------------------------------------===//
+
+struct AppID {
+  std::string name;
+  std::optional<uint32_t> idx;
+
+  AppID(const std::string &name, std::optional<uint32_t> idx = std::nullopt)
+      : name(name), idx(idx) {}
+
+  bool operator==(const AppID &other) const {
+    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);
+
+class AppIDPath : public std::vector<AppID> {
+public:
+  using std::vector<AppID>::vector;
+
+  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);
+
+struct Constant {
+  std::any value;
+  std::optional<const Type *> type;
+};
+
+struct ModuleInfo {
+  std::optional<std::string> name;
+  std::optional<std::string> summary;
+  std::optional<std::string> version;
+  std::optional<std::string> repo;
+  std::optional<std::string> commitHash;
+  std::map<std::string, Constant> constants;
+  std::map<std::string, std::any> extra;
+};
+
+/// A description of a service port. Used pretty exclusively in setting up the
+/// design.
+struct ServicePortDesc {
+  std::string name;
+  std::string portName;
+};
+
+/// Details about how to connect to a particular channel.
+struct ChannelAssignment {
+  /// The name of the type of connection. Typically, the name of the DMA engine
+  /// or "cosim" if a cosimulation channel is being used.
+  std::string type;
+  /// Implementation-specific options.
+  std::map<std::string, std::any> implOptions;
+};
+using ChannelAssignments = std::map<std::string, ChannelAssignment>;
+
+/// A description of a hardware client. Used pretty exclusively in setting up
+/// the design.
+struct HWClientDetail {
+  AppIDPath relPath;
+  ServicePortDesc port;
+  ChannelAssignments channelAssignments;
+  std::map<std::string, std::any> implOptions;
+};
+using HWClientDetails = std::vector<HWClientDetail>;
+using ServiceImplDetails = std::map<std::string, std::any>;
+
+/// A logical chunk of data representing serialized data. Currently, just a
+/// wrapper for a vector of bytes, which is not efficient in terms of memory
+/// copying. This will change in the future as will the API.
+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
+  /// of this object.
+  template <typename T>
+  const T *as() const {
+    if (data.size() != sizeof(T))
+      throw std::runtime_error("Data size does not match type size. Size is " +
+                               std::to_string(data.size()) + ", expected " +
+                               std::to_string(sizeof(T)) + ".");
+    return reinterpret_cast<const T *>(data.data());
+  }
+
+  /// Cast from a type to its raw bytes.
+  template <typename T>
+  static MessageData from(T &t) {
+    return MessageData(reinterpret_cast<const uint8_t *>(&t), sizeof(T));
+  }
+
+  /// Convert the data to a hex string.
+  std::string toHex() const;
+
+private:
+  std::vector<uint8_t> data;
+};
+
+} // namespace esi
+
+std::ostream &operator<<(std::ostream &, const esi::ModuleInfo &);
+
+//===----------------------------------------------------------------------===//
+// Functions which should be in the standard library.
+//===----------------------------------------------------------------------===//
+
+namespace esi {
+std::string toHex(void *val);
+std::string toHex(uint64_t val);
+} // namespace esi
+
+#endif // ESI_COMMON_H

esiaccel/include/esi/Context.h

@@ -0,0 +1,82 @@
+//===- Context.h - Accelerator context --------------------------*- 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.
+//
+//===----------------------------------------------------------------------===//
+
+// NOLINTNEXTLINE(llvm-header-guard)
+#ifndef ESI_CONTEXT_H
+#define ESI_CONTEXT_H
+
+#include "esi/Logging.h"
+#include "esi/Types.h"
+
+#include <exception>
+#include <map>
+#include <memory>
+#include <vector>
+
+namespace esi {
+class AcceleratorConnection;
+
+/// AcceleratorConnections, Accelerators, and Manifests must all share a
+/// 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();
+  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 std::unique_ptr<Context> withLogger(Args &&...args) {
+    return std::make_unique<Context>(std::make_unique<T>(args...));
+  }
+
+  /// Resolve a type id to the type.
+  std::optional<const Type *> getType(Type::ID id) const {
+    if (auto f = types.find(id); f != types.end())
+      return f->second.get();
+    return std::nullopt;
+  }
+
+  /// Register a type with the context. Takes ownership of the pointer type.
+  void registerType(Type *type);
+
+  /// 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) {
+    if (!logger)
+      throw std::invalid_argument("logger must not be null");
+    this->logger = std::move(logger);
+  }
+  inline Logger &getLogger() { return *logger; }
+
+private:
+  std::unique_ptr<Logger> logger;
+  std::vector<std::unique_ptr<AcceleratorConnection>> connections;
+
+private:
+  using TypeCache = std::map<Type::ID, std::unique_ptr<Type>>;
+  TypeCache types;
+};
+
+} // namespace esi
+
+#endif // ESI_CONTEXT_H