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

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