esiaccel 0.2.3.dev49__cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

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

esiaccel/include/esi/Design.h

@@ -0,0 +1,132 @@
+//===- 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 {
+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);
+
+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, std::move(ports)),
+        id(id) {}
+
+  /// Get the instance's ID, which it will always have.
+  AppID getID() const { return id; }
+
+protected:
+  const AppID id;
+};
+
+} // namespace esi
+
+#endif // ESI_DESIGN_H

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