esiaccel 0.1.0__cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

esiaccel/include/esi/Accelerator.h

@@ -0,0 +1,232 @@
+//===- 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;
+
+//===----------------------------------------------------------------------===//
+// Constants used by low-level APIs.
+//===----------------------------------------------------------------------===//
+
+constexpr uint32_t MetadataOffset = 8;
+constexpr uint64_t MagicNumberLo = 0xE5100E51;
+constexpr uint64_t MagicNumberHi = 0x207D98E5;
+constexpr uint64_t MagicNumber = MagicNumberLo | (MagicNumberHi << 32);
+constexpr uint32_t ExpectedVersionNumber = 0;
+
+//===----------------------------------------------------------------------===//
+// 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, 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();
+
+  // 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
+  /// 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<const std::type_info *, 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 {
+
+// 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.
+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);
+    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

@@ -0,0 +1,154 @@
+//===- 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 <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); }
+};
+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);
+  std::string toStr() const;
+};
+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::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 size of the data in bytes.
+  size_t getSize() const { return data.size(); }
+
+  /// 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 &);
+std::ostream &operator<<(std::ostream &, const esi::AppID &);
+
+//===----------------------------------------------------------------------===//
+// 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,74 @@
+//===- 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 <memory>
+#include <optional>
+
+namespace esi {
+class AcceleratorConnection;
+
+/// AcceleratorConnections, Accelerators, and Manifests must all share a
+/// context. It owns all the types, uniquifying them.
+class Context {
+public:
+  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.
+  template <typename T, typename... Args>
+  static Context withLogger(Args &&...args) {
+    return 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.
+  std::unique_ptr<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;
+
+private:
+  using TypeCache = std::map<Type::ID, std::unique_ptr<Type>>;
+  TypeCache types;
+};
+
+} // namespace esi
+
+#endif // ESI_CONTEXT_H

esiaccel/include/esi/Design.h

@@ -0,0 +1,127 @@
+//===- Design.h - Dynamic accelerator 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
+//
+//===----------------------------------------------------------------------===//
+//
+// The dynamic API into an accelerator allows access to the accelerator's design
+// and communication channels through various stl containers (e.g. std::vector,
+// std::map, etc.). This allows runtime reflection against the accelerator and
+// can be pybind'd to create a Python API.
+//
+// The static API, in contrast, is a compile-time API that allows access to the
+// design and communication channels symbolically. It will be generated once
+// (not here) then compiled into the host software.
+//
+// Note for hardware designers: the "design hierarchy" from the host API
+// perspective is not the same as the hardware module instance hierarchy.
+// Rather, it is only the relevant parts as defined by the AppID hierarchy --
+// levels in the hardware module instance hierarchy get skipped.
+//
+// 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_DESIGN_H
+#define ESI_DESIGN_H
+
+#include "esi/Manifest.h"
+#include "esi/Ports.h"
+#include "esi/Services.h"
+
+#include <string>
+
+namespace esi {
+// Forward declarations.
+class Instance;
+namespace services {
+class Service;
+} // namespace services
+
+/// Represents either the top level or an instance of a hardware module.
+class HWModule {
+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);
+
+public:
+  virtual ~HWModule() = default;
+
+  /// Access the module's metadata, if any.
+  std::optional<ModuleInfo> getInfo() const { return info; }
+  /// Get a vector of the module's children in a deterministic order.
+  std::vector<const Instance *> getChildrenOrdered() const {
+    std::vector<const Instance *> ret;
+    for (const auto &c : children)
+      ret.push_back(c.get());
+    return ret;
+  }
+  /// Access the module's children by ID.
+  const std::map<AppID, Instance *> &getChildren() const { return childIndex; }
+  /// Get the module's ports in a deterministic order.
+  std::vector<std::reference_wrapper<BundlePort>> getPortsOrdered() const {
+    std::vector<std::reference_wrapper<BundlePort>> ret;
+    for (const auto &p : ports)
+      ret.push_back(*p);
+    return ret;
+  }
+  /// Access the module's ports by ID.
+  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;
+  }
+
+  /// Master poll method. Calls the `poll` method on all locally owned ports and
+  /// the master `poll` method on all of the children. Returns true if any of
+  /// 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, BundlePort &> portIndex;
+};
+
+/// Subclass of `HWModule` which represents a submodule instance. Adds an AppID,
+/// which the top level doesn't have or need.
+class Instance : public HWModule {
+public:
+  Instance() = delete;
+  Instance(const Instance &) = delete;
+  ~Instance() = default;
+  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) {}
+
+  /// Get the instance's ID, which it will always have.
+  const AppID getID() const { return id; }
+
+protected:
+  const AppID id;
+};
+
+} // namespace esi
+
+#endif // ESI_DESIGN_H