esiaccel 0.1.0__cp313-cp313-win_amd64.whl

esiaccel/include/esi/Ports.h

@@ -0,0 +1,275 @@
+//===- Ports.h - ESI communication channels ---------------------*- 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_PORTS_H
+#define ESI_PORTS_H
+
+#include "esi/Common.h"
+#include "esi/Types.h"
+#include "esi/Utils.h"
+
+#include <cassert>
+#include <future>
+
+namespace esi {
+
+class ChannelPort;
+using PortMap = std::map<std::string, ChannelPort &>;
+
+/// Unidirectional channels are the basic communication primitive between the
+/// host and accelerator. A 'ChannelPort' is the host side of a channel. It can
+/// be either read or write but not both. At this level, channels are untyped --
+/// just streams of bytes. They are not intended to be used directly by users
+/// but used by higher level APIs which add types.
+class ChannelPort {
+public:
+  ChannelPort(const Type *type) : type(type) {}
+  virtual ~ChannelPort() {}
+
+  /// Set up a connection to the accelerator. The buffer size is optional and
+  /// should be considered merely a hint. Individual implementations use it
+  /// however they like. The unit is number of messages of the port type.
+  virtual void connect(std::optional<unsigned> bufferSize = std::nullopt) = 0;
+  virtual void disconnect() = 0;
+  virtual bool isConnected() const = 0;
+
+  /// Poll for incoming data. Returns true if data was read or written into a
+  /// buffer as a result of the poll. Calling the call back could (will) also
+  /// happen in that case. Some backends need this to be called periodically. In
+  /// the usual case, this will be called by a background thread, but the ESI
+  /// runtime does not want to assume that the host processes use standard
+  /// threads. If the user wants to provide their own threads, they need to call
+  /// this on each port occasionally. This is also called from the 'master' poll
+  /// method in the Accelerator class.
+  bool poll() {
+    if (isConnected())
+      return pollImpl();
+    return false;
+  }
+
+  const Type *getType() const { return type; }
+
+protected:
+  const Type *type;
+
+  /// Method called by poll() to actually poll the channel if the channel is
+  /// connected.
+  virtual bool pollImpl() { return false; }
+
+  /// Called by all connect methods to let backends initiate the underlying
+  /// connections.
+  virtual void connectImpl(std::optional<unsigned> bufferSize) {}
+};
+
+/// A ChannelPort which sends data to the accelerator.
+class WriteChannelPort : public ChannelPort {
+public:
+  using ChannelPort::ChannelPort;
+
+  virtual void
+  connect(std::optional<unsigned> bufferSize = std::nullopt) override {
+    connectImpl(bufferSize);
+    connected = true;
+  }
+  virtual void disconnect() override { connected = false; }
+  virtual bool isConnected() const override { return connected; }
+
+  /// A very basic blocking write API. Will likely change for performance
+  /// reasons.
+  virtual void write(const MessageData &) = 0;
+
+  /// A basic non-blocking write API. Returns true if the data was written.
+  /// It is invalid for backends to always return false (i.e. backends must
+  /// eventually ensure that writes may succeed).
+  virtual bool tryWrite(const MessageData &data) = 0;
+
+private:
+  volatile bool connected = false;
+};
+
+/// Instantiated when a backend does not know how to create a write channel.
+class UnknownWriteChannelPort : public WriteChannelPort {
+public:
+  UnknownWriteChannelPort(const Type *type, std::string errmsg)
+      : WriteChannelPort(type), errmsg(errmsg) {}
+
+  void connect(std::optional<unsigned> bufferSize = std::nullopt) override {
+    throw std::runtime_error(errmsg);
+  }
+  void write(const MessageData &) override { throw std::runtime_error(errmsg); }
+  bool tryWrite(const MessageData &) override {
+    throw std::runtime_error(errmsg);
+  }
+
+protected:
+  std::string errmsg;
+};
+
+/// A ChannelPort which reads data from the accelerator. It has two modes:
+/// Callback and Polling which cannot be used at the same time. The mode is set
+/// at connect() time. To change the mode, disconnect() and then connect()
+/// again.
+class ReadChannelPort : public ChannelPort {
+
+public:
+  ReadChannelPort(const Type *type)
+      : ChannelPort(type), mode(Mode::Disconnected) {}
+  virtual void disconnect() override { mode = Mode::Disconnected; }
+  virtual bool isConnected() const override {
+    return mode != Mode::Disconnected;
+  }
+
+  //===--------------------------------------------------------------------===//
+  // Callback mode: To use a callback, connect with a callback function which
+  // will get called with incoming data. This function can be called from any
+  // thread. It shall return true to indicate that the data was consumed. False
+  // if it could not accept the data and should be tried again at some point in
+  // the future. Callback is not allowed to block and needs to execute quickly.
+  //
+  // TODO: Have the callback return something upon which the caller can check,
+  // wait, and be notified.
+  //===--------------------------------------------------------------------===//
+
+  virtual void connect(std::function<bool(MessageData)> callback,
+                       std::optional<unsigned> bufferSize = std::nullopt);
+
+  //===--------------------------------------------------------------------===//
+  // Polling mode methods: To use futures or blocking reads, connect without any
+  // arguments. You will then be able to use readAsync() or read().
+  //===--------------------------------------------------------------------===//
+
+  /// Default max data queue size set at connect time.
+  static constexpr uint64_t DefaultMaxDataQueueMsgs = 32;
+
+  /// Connect to the channel in polling mode.
+  virtual void
+  connect(std::optional<unsigned> bufferSize = std::nullopt) override;
+
+  /// Asynchronous read.
+  virtual std::future<MessageData> readAsync();
+
+  /// Specify a buffer to read into. Blocking. Basic API, will likely change
+  /// for performance and functionality reasons.
+  virtual void read(MessageData &outData) {
+    std::future<MessageData> f = readAsync();
+    f.wait();
+    outData = std::move(f.get());
+  }
+
+  /// Set maximum number of messages to store in the dataQueue. 0 means no
+  /// limit. This is only used in polling mode and is set to default of 32 upon
+  /// connect. While it may seem redundant to have this and bufferSize, there
+  /// may be (and are) backends which have a very small amount of memory which
+  /// are accelerator accessible and want to move messages out as quickly as
+  /// possible.
+  void setMaxDataQueueMsgs(uint64_t maxMsgs) { maxDataQueueMsgs = maxMsgs; }
+
+protected:
+  /// Indicates the current mode of the channel.
+  enum Mode { Disconnected, Callback, Polling };
+  volatile Mode mode;
+
+  /// Backends call this callback when new data is available.
+  std::function<bool(MessageData)> callback;
+
+  //===--------------------------------------------------------------------===//
+  // Polling mode members.
+  //===--------------------------------------------------------------------===//
+
+  /// Mutex to protect the two queues used for polling.
+  std::mutex pollingM;
+  /// Store incoming data here if there are no outstanding promises to be
+  /// fulfilled.
+  std::queue<MessageData> dataQueue;
+  /// Maximum number of messages to store in dataQueue. 0 means no limit.
+  uint64_t maxDataQueueMsgs;
+  /// Promises to be fulfilled when data is available.
+  std::queue<std::promise<MessageData>> promiseQueue;
+};
+
+/// Instantiated when a backend does not know how to create a read channel.
+class UnknownReadChannelPort : public ReadChannelPort {
+public:
+  UnknownReadChannelPort(const Type *type, std::string errmsg)
+      : ReadChannelPort(type), errmsg(errmsg) {}
+
+  void connect(std::function<bool(MessageData)> callback,
+               std::optional<unsigned> bufferSize = std::nullopt) override {
+    throw std::runtime_error(errmsg);
+  }
+  void connect(std::optional<unsigned> bufferSize = std::nullopt) override {
+    throw std::runtime_error(errmsg);
+  }
+  std::future<MessageData> readAsync() override {
+    throw std::runtime_error(errmsg);
+  }
+
+protected:
+  std::string errmsg;
+};
+
+/// Services provide connections to 'bundles' -- collections of named,
+/// unidirectional communication channels. This class provides access to those
+/// ChannelPorts.
+class BundlePort {
+public:
+  /// Compute the direction of a channel given the bundle direction and the
+  /// bundle port's direction.
+  static bool isWrite(BundleType::Direction bundleDir) {
+    return bundleDir == BundleType::Direction::To;
+  }
+
+  /// Construct a port.
+  BundlePort(AppID id, const BundleType *type, PortMap channels);
+  virtual ~BundlePort() = default;
+
+  /// Get the ID of the port.
+  AppID getID() const { return id; }
+
+  /// Get access to the raw byte streams of a channel. Intended for internal
+  /// usage and binding to other languages (e.g. Python) which have their own
+  /// message serialization code. Exposed publicly as an escape hatch, but
+  /// ordinary users should not use. You have been warned.
+  WriteChannelPort &getRawWrite(const std::string &name) const;
+  ReadChannelPort &getRawRead(const std::string &name) const;
+  const PortMap &getChannels() const { return channels; }
+
+  /// Cast this Bundle port to a subclass which is actually useful. Returns
+  /// nullptr if the cast fails.
+  // TODO: this probably shouldn't be 'const', but bundle ports' user access are
+  // const. Change that.
+  template <typename T>
+  T *getAs() const {
+    return const_cast<T *>(dynamic_cast<const T *>(this));
+  }
+
+  /// Calls `poll` on all channels in the bundle and returns true if any of them
+  /// returned true.
+  bool poll() {
+    bool result = false;
+    for (auto &channel : channels)
+      result |= channel.second.poll();
+    return result;
+  }
+
+protected:
+  AppID id;
+  const BundleType *type;
+  PortMap channels;
+};
+
+} // namespace esi
+
+#endif // ESI_PORTS_H

esiaccel/include/esi/Services.h

@@ -0,0 +1,404 @@
+//===- StdServices.h - ESI standard services C++ 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 APIs in this backend are all optionally implemented. The lower level
+// ones, however, are strongly recommended. 'Services' here refers to ESI
+// services. These are standard APIs into the standard ESI services.
+//
+// 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_RUNTIME_SERVICES_H
+#define ESI_RUNTIME_SERVICES_H
+
+#include "esi/Common.h"
+#include "esi/Context.h"
+#include "esi/Ports.h"
+
+#include <cstdint>
+
+namespace esi {
+class AcceleratorConnection;
+class Engine;
+namespace services {
+
+/// Add a custom interface to a service client at a particular point in the
+/// design hierarchy.
+class ServicePort : public BundlePort {
+public:
+  using BundlePort::BundlePort;
+  virtual ~ServicePort() = default;
+  // Get a description of the service port.
+  virtual std::optional<std::string> toString() const { return std::nullopt; }
+};
+
+/// Parent class of all APIs modeled as 'services'. May or may not map to a
+/// hardware side 'service'.
+class Service {
+public:
+  using Type = const std::type_info &;
+  Service(AcceleratorConnection &conn) : conn(conn) {}
+  virtual ~Service() = default;
+
+  virtual std::string getServiceSymbol() const = 0;
+
+  /// Create a "child" service of this service. Does not have to be the same
+  /// service type, but typically is. Used when a service already exists in the
+  /// active services table, but a new one wants to replace it. Useful for cases
+  /// where the child service needs to use the parent service. Defaults to
+  /// calling the `getService` method on `AcceleratorConnection` to get the
+  /// global service, implying that the child service does not need to use the
+  /// service it is replacing.
+  virtual Service *getChildService(Service::Type service, AppIDPath id = {},
+                                   std::string implName = {},
+                                   ServiceImplDetails details = {},
+                                   HWClientDetails clients = {});
+
+  /// Get specialized port for this service to attach to the given appid path.
+  /// Null returns mean nothing to attach.
+  virtual BundlePort *getPort(AppIDPath id, const BundleType *type) const {
+    return nullptr;
+  }
+
+  AcceleratorConnection &getConnection() const { return conn; }
+
+protected:
+  AcceleratorConnection &conn;
+};
+
+/// A service for which there are no standard services registered. Requires
+/// ports be added to the design hierarchy instead of high level interfaces like
+/// the ones in StdServices.h.
+class CustomService : public Service {
+public:
+  CustomService(AppIDPath idPath, AcceleratorConnection &,
+                const ServiceImplDetails &details,
+                const HWClientDetails &clients);
+  virtual ~CustomService() = default;
+
+  virtual std::string getServiceSymbol() const override {
+    return serviceSymbol;
+  }
+  virtual BundlePort *getPort(AppIDPath id,
+                              const BundleType *type) const override;
+
+protected:
+  std::string serviceSymbol;
+  AppIDPath id;
+};
+
+/// Information about the Accelerator system.
+class SysInfo : public Service {
+public:
+  using Service::Service;
+  virtual ~SysInfo() = default;
+
+  virtual std::string getServiceSymbol() const override;
+
+  /// Get the ESI version number to check version compatibility.
+  virtual uint32_t getEsiVersion() const = 0;
+
+  /// Return the JSON-formatted system manifest.
+  virtual std::string getJsonManifest() const;
+
+  /// Return the zlib compressed JSON system manifest.
+  virtual std::vector<uint8_t> getCompressedManifest() const = 0;
+};
+
+class MMIO : public Service {
+public:
+  static constexpr std::string_view StdName = "esi.service.std.mmio";
+
+  /// Describe a region (slice) of MMIO space.
+  struct RegionDescriptor {
+    uint32_t base;
+    uint32_t size;
+  };
+
+  MMIO(AcceleratorConnection &, const HWClientDetails &clients);
+  virtual ~MMIO() = default;
+
+  /// Read a 64-bit value from the global MMIO space.
+  virtual uint64_t read(uint32_t addr) const = 0;
+  /// Write a 64-bit value to the global MMIO space.
+  virtual void write(uint32_t addr, uint64_t data) = 0;
+  /// Get the regions of MMIO space that this service manages. Otherwise known
+  /// as the base address table.
+  const std::map<AppIDPath, RegionDescriptor> &getRegions() const {
+    return regions;
+  }
+
+  /// If the service is a MMIO service, return a region of the MMIO space which
+  /// peers into ours.
+  virtual Service *getChildService(Service::Type service, AppIDPath id = {},
+                                   std::string implName = {},
+                                   ServiceImplDetails details = {},
+                                   HWClientDetails clients = {}) override;
+
+  virtual std::string getServiceSymbol() const override;
+
+  /// Get a MMIO region port for a particular region descriptor.
+  virtual BundlePort *getPort(AppIDPath id,
+                              const BundleType *type) const override;
+
+private:
+  /// MMIO base address table.
+  std::map<AppIDPath, RegionDescriptor> regions;
+
+public:
+  /// A "slice" of some parent MMIO space.
+  class MMIORegion : public ServicePort {
+    friend class MMIO;
+    MMIORegion(AppID id, MMIO *parent, RegionDescriptor desc);
+
+  public:
+    /// Get the offset (and size) of the region in the parent (usually global)
+    /// MMIO address space.
+    virtual RegionDescriptor getDescriptor() const { return desc; };
+    /// Read a 64-bit value from this region, not the global address space.
+    virtual uint64_t read(uint32_t addr) const;
+    /// Write a 64-bit value to this region, not the global address space.
+    virtual void write(uint32_t addr, uint64_t data);
+
+    virtual std::optional<std::string> toString() const override {
+      return "MMIO region " + toHex(desc.base) + " - " +
+             toHex(desc.base + desc.size);
+    }
+
+  private:
+    MMIO *parent;
+    RegionDescriptor desc;
+  };
+};
+
+/// Implement the SysInfo API for a standard MMIO protocol.
+class MMIOSysInfo final : public SysInfo {
+public:
+  MMIOSysInfo(const MMIO *);
+
+  /// Get the ESI version number to check version compatibility.
+  uint32_t getEsiVersion() const override;
+
+  /// Return the zlib compressed JSON system manifest.
+  virtual std::vector<uint8_t> getCompressedManifest() const override;
+
+private:
+  const MMIO *mmio;
+};
+
+class HostMem : public Service {
+public:
+  static constexpr std::string_view StdName = "esi.service.std.hostmem";
+
+  using Service::Service;
+  virtual ~HostMem() = default;
+  virtual std::string getServiceSymbol() const override;
+
+  /// RAII memory region for host memory. Automatically frees the memory when
+  /// deconstructed.
+  struct HostMemRegion {
+    virtual ~HostMemRegion() = default;
+    /// Get a pointer to the host memory.
+    virtual void *getPtr() const = 0;
+    /// Sometimes the pointer the device sees is different from the pointer the
+    /// host sees. Call this functon to get the device pointer.
+    virtual void *getDevicePtr() const { return getPtr(); }
+    operator void *() const { return getPtr(); }
+    virtual std::size_t getSize() const = 0;
+    /// Flush the memory region to ensure that the device sees the latest
+    /// contents. Because some platforms require it before DMA transactions, it
+    /// is recommended to call this before any DMA on all platforms. On
+    /// platforms which don't require it, it is a cheap no-op virtual method
+    /// call.
+    virtual void flush() {}
+  };
+
+  /// Options for allocating host memory.
+  struct Options {
+    bool writeable = false;
+    bool useLargePages = false;
+  };
+
+  /// In cases where necessary, enable host memory services.
+  virtual void start() {}
+
+  /// Allocate a region of host memory in accelerator accessible address space.
+  virtual std::unique_ptr<HostMemRegion> allocate(std::size_t size,
+                                                  Options opts) const = 0;
+
+  /// Try to make a region of host memory accessible to the accelerator. Returns
+  /// 'false' on failure. It is optional for an accelerator backend to implement
+  /// this, so client code needs to have a fallback for when this returns
+  /// 'false'. On success, it is the client's responsibility to ensure that the
+  /// memory eventually gets unmapped.
+  virtual bool mapMemory(void *ptr, std::size_t size, Options opts) const {
+    return false;
+  }
+  /// Unmap memory which was previously mapped with 'mapMemory'. Undefined
+  /// behavior when called with a pointer which was not previously mapped.
+  virtual void unmapMemory(void *ptr) const {}
+};
+
+/// Service for calling functions.
+class FuncService : public Service {
+public:
+  FuncService(AppIDPath id, AcceleratorConnection &, ServiceImplDetails details,
+              HWClientDetails clients);
+
+  virtual std::string getServiceSymbol() const override;
+  virtual BundlePort *getPort(AppIDPath id,
+                              const BundleType *type) const override;
+
+  /// A function call which gets attached to a service port.
+  class Function : public ServicePort {
+    friend class FuncService;
+    using ServicePort::ServicePort;
+
+  public:
+    static Function *get(AppID id, BundleType *type, WriteChannelPort &arg,
+                         ReadChannelPort &result);
+
+    void connect();
+    std::future<MessageData> call(const MessageData &arg);
+
+    virtual std::optional<std::string> toString() const override {
+      const esi::Type *argType =
+          dynamic_cast<const ChannelType *>(type->findChannel("arg").first)
+              ->getInner();
+      const esi::Type *resultType =
+          dynamic_cast<const ChannelType *>(type->findChannel("result").first)
+              ->getInner();
+      return "function " + resultType->getID() + "(" + argType->getID() + ")";
+    }
+
+  private:
+    std::mutex callMutex;
+    WriteChannelPort *arg;
+    ReadChannelPort *result;
+  };
+
+private:
+  std::string symbol;
+};
+
+/// Service for servicing function calls from the accelerator.
+class CallService : public Service {
+public:
+  CallService(AcceleratorConnection &acc, AppIDPath id,
+              ServiceImplDetails details);
+
+  virtual std::string getServiceSymbol() const override;
+  virtual BundlePort *getPort(AppIDPath id,
+                              const BundleType *type) const override;
+
+  /// A function call which gets attached to a service port.
+  class Callback : public ServicePort {
+    friend class CallService;
+    Callback(AcceleratorConnection &acc, AppID id, const BundleType *,
+             PortMap channels);
+
+  public:
+    static Callback *get(AcceleratorConnection &acc, AppID id, BundleType *type,
+                         WriteChannelPort &result, ReadChannelPort &arg);
+
+    /// Connect a callback to code which will be executed when the accelerator
+    /// invokes the callback. The 'quick' flag indicates that the callback is
+    /// sufficiently fast that it could be called in the same thread as the
+    /// port callback.
+    void connect(std::function<MessageData(const MessageData &)> callback,
+                 bool quick = false);
+
+    virtual std::optional<std::string> toString() const override {
+      const esi::Type *argType =
+          dynamic_cast<const ChannelType *>(type->findChannel("arg").first)
+              ->getInner();
+      const esi::Type *resultType =
+          dynamic_cast<const ChannelType *>(type->findChannel("result").first)
+              ->getInner();
+      return "callback " + resultType->getID() + "(" + argType->getID() + ")";
+    }
+
+  private:
+    ReadChannelPort *arg;
+    WriteChannelPort *result;
+    AcceleratorConnection &acc;
+  };
+
+private:
+  std::string symbol;
+};
+
+/// Service for retrieving telemetry data from the accelerator.
+class TelemetryService : public Service {
+public:
+  static constexpr std::string_view StdName = "esi.service.std.telemetry";
+
+  TelemetryService(AppIDPath id, AcceleratorConnection &,
+                   ServiceImplDetails details, HWClientDetails clients);
+
+  virtual std::string getServiceSymbol() const override;
+  virtual BundlePort *getPort(AppIDPath id,
+                              const BundleType *type) const override;
+
+  /// A telemetry port which gets attached to a service port.
+  class Telemetry : public ServicePort {
+    friend class TelemetryService;
+    Telemetry(AppID id, const BundleType *type, PortMap channels);
+
+  public:
+    static Telemetry *get(AppID id, BundleType *type, WriteChannelPort &get,
+                          ReadChannelPort &data);
+
+    void connect();
+    std::future<MessageData> read();
+
+    virtual std::optional<std::string> toString() const override {
+      const esi::Type *dataType =
+          dynamic_cast<const ChannelType *>(type->findChannel("data").first)
+              ->getInner();
+      return "telemetry " + dataType->getID();
+    }
+
+  private:
+    WriteChannelPort *get_req;
+    ReadChannelPort *data;
+  };
+
+  const std::map<AppIDPath, Telemetry *> &getTelemetryPorts() {
+    return telemetryPorts;
+  }
+
+private:
+  mutable std::map<AppIDPath, Telemetry *> telemetryPorts;
+};
+
+/// Registry of services which can be instantiated directly by the Accelerator
+/// class if the backend doesn't do anything special with a service.
+class ServiceRegistry {
+public:
+  /// Create a service instance from the given details. Returns nullptr if
+  /// 'svcType' isn't registered.
+  static Service *createService(AcceleratorConnection *acc,
+                                Service::Type svcType, AppIDPath id,
+                                std::string implName,
+                                ServiceImplDetails details,
+                                HWClientDetails clients);
+
+  /// Resolve a service type from a string. If the string isn't recognized,
+  /// default to CustomService.
+  static Service::Type lookupServiceType(const std::string &);
+};
+
+} // namespace services
+} // namespace esi
+
+#endif // ESI_RUNTIME_SERVICES_H