esiaccel 0.2.3.dev80__cp314-cp314-win_amd64.whl

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

esiaccel/include/esi/Logging.h

@@ -0,0 +1,231 @@
+//===- Logging.h - ESI Runtime logging --------------------------*- 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
+//
+//===----------------------------------------------------------------------===//
+//
+// ESI runtime logging is very simple but very flexible. Rather than mandating a
+// particular logging library, it allows users to hook into their existing
+// logging system by implementing a simple interface.
+//
+//===----------------------------------------------------------------------===//
+//
+// 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_LOGGING_H
+#define ESI_LOGGING_H
+
+#include <any>
+#include <functional>
+#include <iosfwd>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <string>
+
+namespace esi {
+
+class Logger {
+public:
+  enum class Level {
+    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, bool traceEnabled)
+      : debugEnabled(debugEnabled), traceEnabled(traceEnabled) {}
+  virtual ~Logger() = default;
+  bool getDebugEnabled() { return debugEnabled; }
+  bool getTraceEnabled() { return traceEnabled; }
+
+  /// Report a log message.
+  /// Arguments:
+  ///   level: The log level as defined by the 'Level' enum above.
+  ///   subsystem: The subsystem that generated the log message.
+  ///   msg: The log message.
+  ///   details: Optional additional structured details to include in the log
+  ///            message. If there are no details, this should be nullptr.
+  virtual void
+  log(Level level, const std::string &subsystem, const std::string &msg,
+      const std::map<std::string, std::any> *details = nullptr) = 0;
+
+  /// Report an error.
+  virtual void error(const std::string &subsystem, const std::string &msg,
+                     const std::map<std::string, std::any> *details = nullptr) {
+    log(Level::Error, subsystem, msg, details);
+  }
+  /// Report a warning.
+  virtual void
+  warning(const std::string &subsystem, const std::string &msg,
+          const std::map<std::string, std::any> *details = nullptr) {
+    log(Level::Warning, subsystem, msg, details);
+  }
+  /// Report an informational message.
+  virtual void info(const std::string &subsystem, const std::string &msg,
+                    const std::map<std::string, std::any> *details = nullptr) {
+    log(Level::Info, subsystem, msg, details);
+  }
+
+  /// Report a debug message. This is not virtual so that it can be inlined to
+  /// minimize performance impact that debug messages have, allowing debug
+  /// messages in Release builds.
+  inline void debug(const std::string &subsystem, const std::string &msg,
+                    const std::map<std::string, std::any> *details = nullptr) {
+    if (debugEnabled)
+      debugImpl(subsystem, msg, details);
+  }
+  /// Call the debug function callback only if debug is enabled then log a debug
+  /// message. Allows users to run heavy weight debug message generation code
+  /// only when debug is enabled, which in turns allows users to provide
+  /// fully-featured debug messages in Release builds with minimal performance
+  /// impact. Not virtual so that it can be inlined.
+  inline void
+  debug(std::function<
+        void(std::string &subsystem, std::string &msg,
+             std::unique_ptr<std::map<std::string, std::any>> &details)>
+            debugFunc) {
+    if (debugEnabled)
+      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,
+                         const std::map<std::string, std::any> *details) {
+    log(Level::Debug, subsystem, msg, details);
+  }
+  /// Overrideable version of debug. Only gets called if debug is enabled.
+  virtual void
+  debugImpl(std::function<
+            void(std::string &subsystem, std::string &msg,
+                 std::unique_ptr<std::map<std::string, std::any>> &details)>
+                debugFunc) {
+    if (!debugEnabled)
+      return;
+    std::string subsystem;
+    std::string msg;
+    std::unique_ptr<std::map<std::string, std::any>> details = nullptr;
+    debugFunc(subsystem, msg, details);
+    debugImpl(subsystem, msg, details.get());
+  }
+
+  /// 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
+/// protects the `log` method. If subclasses override other methods and need to
+/// protect them, they need to do that themselves.
+class TSLogger : public Logger {
+public:
+  using Logger::Logger;
+
+  /// Grabs the lock and calls logImpl.
+  void log(Level level, const std::string &subsystem, const std::string &msg,
+           const std::map<std::string, std::any> *details) override final;
+
+protected:
+  /// Subclasses must implement this method to log messages.
+  virtual void logImpl(Level level, const std::string &subsystem,
+                       const std::string &msg,
+                       const std::map<std::string, std::any> *details) = 0;
+
+  /// Mutex to protect the stream from interleaved logging writes.
+  std::mutex mutex;
+};
+
+/// A logger that writes to a C++ std::ostream.
+class StreamLogger : public TSLogger {
+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 <= 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,
+               const std::string &msg,
+               const std::map<std::string, std::any> *details) override;
+
+private:
+  /// The minimum log level to emit.
+  Level minLevel;
+
+  /// Everything except errors goes here.
+  std::ostream &outStream;
+  /// Just for errors.
+  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, false) {}
+  void log(Level, const std::string &, const std::string &,
+           const std::map<std::string, std::any> *) override {}
+};
+
+/// 'Stringify' a std::any. This is used to log std::any values by some loggers.
+std::string toString(const std::any &a);
+
+} // namespace esi
+
+#endif // ESI_LOGGING_H

esiaccel/include/esi/Manifest.h

@@ -0,0 +1,70 @@
+//===- Manifest.h - Metadata on the accelerator -----------------*- 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
+//
+//===----------------------------------------------------------------------===//
+//
+// Manifest parsing and API creation.
+//
+// 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_MANIFEST_H
+#define ESI_MANIFEST_H
+
+#include "esi/Common.h"
+#include "esi/Context.h"
+#include "esi/Types.h"
+
+#include <any>
+#include <memory>
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace esi {
+
+// Forward declarations.
+class AcceleratorConnection;
+class Accelerator;
+
+/// Class to parse a manifest. It also constructs the dynamic API for the
+/// accelerator.
+class Manifest {
+public:
+  class Impl;
+
+  Manifest(const Manifest &) = delete;
+  Manifest(Context &ctxt, const std::string &jsonManifest);
+  ~Manifest();
+
+  uint32_t getApiVersion() const;
+  // Modules which have designer specified metadata.
+  std::vector<ModuleInfo> getModuleInfos() const;
+
+  // Build a dynamic design hierarchy from the manifest. The
+  // AcceleratorConnection owns the returned pointer so its lifetime is
+  // determined by the connection.
+  Accelerator *buildAccelerator(AcceleratorConnection &acc) const;
+
+  /// The Type Table is an ordered list of types. The offset can be used to
+  /// compactly and uniquely within a design. It does not include all of the
+  /// types in a design -- just the ones listed in the 'types' section of the
+  /// manifest.
+  const std::vector<const Type *> &getTypeTable() const;
+
+private:
+  Impl *impl;
+};
+
+} // namespace esi
+
+std::ostream &operator<<(std::ostream &, const esi::ModuleInfo &);
+
+#endif // ESI_MANIFEST_H