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

esiaccel/esiCppAccel.pyi

@@ -0,0 +1,337 @@
+from collections.abc import Callable, Sequence
+import enum
+
+
+class Type:
+    def __init__(self, id: str) -> None: ...
+
+    @property
+    def id(self) -> str: ...
+
+    def __repr__(self) -> str: ...
+
+class ChannelType(Type):
+    def __init__(self, id: str, inner: Type) -> None: ...
+
+    @property
+    def inner(self) -> Type: ...
+
+class Direction(enum.Enum):
+    To = 0
+
+    From = 1
+
+To: Direction = Direction.To
+
+From: Direction = Direction.From
+
+class BundleType(Type):
+    def __init__(self, id: str, channels: Sequence["std::tuple<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >, esi::BundleType::Direction, esi::Type const*>"]) -> None: ...
+
+    @property
+    def channels(self) -> list["std::tuple<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >, esi::BundleType::Direction, esi::Type const*>"]: ...
+
+class VoidType(Type):
+    def __init__(self, id: str) -> None: ...
+
+class AnyType(Type):
+    def __init__(self, id: str) -> None: ...
+
+class BitVectorType(Type):
+    def __init__(self, id: str, width: int) -> None: ...
+
+    @property
+    def width(self) -> int: ...
+
+class BitsType(BitVectorType):
+    def __init__(self, id: str, width: int) -> None: ...
+
+class IntegerType(BitVectorType):
+    def __init__(self, id: str, width: int) -> None: ...
+
+class SIntType(IntegerType):
+    def __init__(self, id: str, width: int) -> None: ...
+
+class UIntType(IntegerType):
+    def __init__(self, id: str, width: int) -> None: ...
+
+class StructType(Type):
+    def __init__(self, id: str, fields: Sequence[tuple[str, Type]], reverse: bool = True) -> None: ...
+
+    @property
+    def fields(self) -> list[tuple[str, Type]]: ...
+
+    @property
+    def reverse(self) -> bool: ...
+
+class ArrayType(Type):
+    def __init__(self, id: str, element_type: Type, size: int) -> None: ...
+
+    @property
+    def element(self) -> Type: ...
+
+    @property
+    def size(self) -> int: ...
+
+class Constant:
+    @property
+    def value(self) -> object: ...
+
+    @property
+    def type(self) -> object: ...
+
+class AppID:
+    def __init__(self, name: str, idx: int | None = None) -> None: ...
+
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def idx(self) -> object: ...
+
+    def __repr__(self) -> str: ...
+
+    def __eq__(self, arg: AppID, /) -> bool: ...
+
+    def __hash__(self) -> int: ...
+
+class AppIDPath:
+    def __repr__(self) -> str: ...
+
+class ModuleInfo:
+    @property
+    def name(self) -> str | None: ...
+
+    @property
+    def summary(self) -> str | None: ...
+
+    @property
+    def version(self) -> str | None: ...
+
+    @property
+    def repo(self) -> str | None: ...
+
+    @property
+    def commit_hash(self) -> str | None: ...
+
+    @property
+    def constants(self) -> dict[str, Constant]: ...
+
+    def __repr__(self) -> str: ...
+
+class LogLevel(enum.Enum):
+    Debug = 1
+
+    Info = 2
+
+    Warning = 3
+
+    Error = 4
+
+Debug: LogLevel = LogLevel.Debug
+
+Info: LogLevel = LogLevel.Info
+
+Warning: LogLevel = LogLevel.Warning
+
+Error: LogLevel = LogLevel.Error
+
+class Logger:
+    pass
+
+class Service:
+    def get_service_symbol(self) -> str: ...
+
+class SysInfo(Service):
+    def esi_version(self) -> int: ...
+
+    def json_manifest(self) -> str: ...
+
+    def cycle_count(self) -> int | None:
+        """Get the current cycle count of the accelerator system"""
+
+    def core_clock_frequency(self) -> int | None:
+        """Get the core clock frequency of the accelerator system in Hz"""
+
+class MMIORegionDescriptor:
+    @property
+    def base(self) -> int: ...
+
+    @property
+    def size(self) -> int: ...
+
+class MMIO(Service):
+    def read(self, arg: int, /) -> int: ...
+
+    def write(self, arg0: int, arg1: int, /) -> None: ...
+
+    @property
+    def regions(self) -> dict[AppIDPath, MMIORegionDescriptor]: ...
+
+class HostMemRegion:
+    @property
+    def ptr(self) -> int: ...
+
+    @property
+    def size(self) -> int: ...
+
+class HostMemOptions:
+    def __init__(self) -> None: ...
+
+    @property
+    def writeable(self) -> bool: ...
+
+    @writeable.setter
+    def writeable(self, arg: bool, /) -> None: ...
+
+    @property
+    def use_large_pages(self) -> bool: ...
+
+    @use_large_pages.setter
+    def use_large_pages(self, arg: bool, /) -> None: ...
+
+    def __repr__(self) -> str: ...
+
+class HostMem(Service):
+    def allocate(self, size: int, options: HostMemOptions = ...) -> HostMemRegion: ...
+
+    def map_memory(self, ptr: int, size: int, options: HostMemOptions = ...) -> bool: ...
+
+    def unmap_memory(self, ptr: int) -> None: ...
+
+class TelemetryService(Service):
+    pass
+
+class MessageDataFuture:
+    def valid(self) -> bool: ...
+
+    def wait(self) -> None: ...
+
+    def get(self) -> bytearray: ...
+
+class ConnectOptions:
+    def __init__(self) -> None: ...
+
+    @property
+    def buffer_size(self) -> int | None: ...
+
+    @buffer_size.setter
+    def buffer_size(self, buffer_size: int | None) -> None: ...
+
+    @property
+    def translate_message(self) -> bool: ...
+
+    @translate_message.setter
+    def translate_message(self, arg: bool, /) -> None: ...
+
+class ChannelPort:
+    def connect(self, options: ConnectOptions) -> None:
+        """Connect with specified options"""
+
+    def disconnect(self) -> None: ...
+
+    @property
+    def type(self) -> Type: ...
+
+class WriteChannelPort(ChannelPort):
+    def write(self, arg: bytearray, /) -> None: ...
+
+    def tryWrite(self, arg: bytearray, /) -> bool: ...
+
+class ReadChannelPort(ChannelPort):
+    def read(self) -> bytearray:
+        """Read data from the channel. Blocking."""
+
+    def read_async(self) -> MessageDataFuture: ...
+
+class BundlePort:
+    @property
+    def id(self) -> AppID: ...
+
+    @property
+    def channels(self) -> dict[str, ChannelPort]: ...
+
+    def getWrite(self, arg: str, /) -> WriteChannelPort: ...
+
+    def getRead(self, arg: str, /) -> ReadChannelPort: ...
+
+class ServicePort(BundlePort):
+    pass
+
+class MMIORegion(ServicePort):
+    @property
+    def descriptor(self) -> MMIORegionDescriptor: ...
+
+    def read(self, arg: int, /) -> int: ...
+
+    def write(self, arg0: int, arg1: int, /) -> None: ...
+
+class Function(ServicePort):
+    def call(self, arg: bytearray, /) -> MessageDataFuture: ...
+
+    def connect(self) -> None: ...
+
+class Callback(ServicePort):
+    def connect(self, arg: Callable[[object], object], /) -> None: ...
+
+class Metric(ServicePort):
+    def connect(self) -> None: ...
+
+    def read(self) -> MessageDataFuture: ...
+
+    def readInt(self) -> int: ...
+
+class HWModule:
+    @property
+    def info(self) -> ModuleInfo | None: ...
+
+    @property
+    def ports(self) -> dict[AppID, BundlePort]: ...
+
+    @property
+    def services(self) -> list[Service]: ...
+
+    @property
+    def children(self) -> dict[AppID, Instance]: ...
+
+class Instance(HWModule):
+    @property
+    def id(self) -> AppID: ...
+
+class Accelerator(HWModule):
+    pass
+
+class AcceleratorConnection:
+    def sysinfo(self) -> SysInfo: ...
+
+    def get_service_mmio(self) -> MMIO: ...
+
+    def get_service_hostmem(self) -> HostMem: ...
+
+    def get_accelerator(self) -> Accelerator: ...
+
+class Context:
+    """
+    An ESI context owns everything -- types, accelerator connections, and the accelerator facade (aka Accelerator) itself. It MUST NOT be garbage collected while the accelerator is still in use. When it is destroyed, all accelerator connections are disconnected.
+    """
+
+    def __init__(self) -> None:
+        """Create a context with a default logger."""
+
+    def connect(self, arg0: str, arg1: str, /) -> AcceleratorConnection: ...
+
+    def set_stdio_logger(self, arg: LogLevel, /) -> None: ...
+
+class Manifest:
+    def __init__(self, arg0: Context, arg1: str, /) -> None: ...
+
+    @property
+    def api_version(self) -> int: ...
+
+    def build_accelerator(self, arg: AcceleratorConnection, /) -> Accelerator: ...
+
+    @property
+    def type_table(self) -> list[object]: ...
+
+    @property
+    def module_infos(self) -> list[ModuleInfo]: ...

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