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

esiaccel/include/esi/Values.h

@@ -0,0 +1,313 @@
+//===- values.h - ESI value system -------------------------------* 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 arbitrary width bitvector and integer types.
+// These types are not meant to be highly optimized. Rather, its a simple
+// implementation to support arbitrary bit widths for ESI runtime values.
+//
+//===----------------------------------------------------------------------===//
+// 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_VALUES_H
+#define ESI_VALUES_H
+
+#include <cstdint>
+#include <format>
+#include <memory> // (may be removable later)
+#include <optional>
+#include <ostream>
+#include <span>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+namespace esi {
+
+class MutableBitVector;
+
+/// A lightweight, non-owning bit vector view backed by a byte array span.
+/// BitVector is immutable wrt. modifying the underlying bits, and provides
+/// read-only access to bits. It supports bit-level access and returns new views
+/// for operations.
+class BitVector {
+public:
+  using byte = uint8_t;
+
+  /// Construct from an existing span. Width defaults to the number of bits in
+  /// the span (size * 8). The BitVector does not take ownership.
+  BitVector(std::span<const byte> bytes,
+            std::optional<size_t> width = std::nullopt, uint8_t bitIndex = 0);
+  BitVector() = default;
+  BitVector(const BitVector &other);
+  BitVector &operator=(const BitVector &other);
+
+  size_t width() const { return bitWidth; }
+  size_t size() const { return width(); }
+
+  /// Return the i-th bit (0 = LSB) as boolean.
+  bool getBit(size_t i) const;
+
+  /// Return a handle to the underlying span. Throws if the current bit index
+  /// is not 0 (since a non-zero bit offset breaks raw byte alignment).
+  std::span<const byte> getSpan() const {
+    if (bitIndex != 0)
+      throw std::runtime_error("Cannot get data span with non-zero bit index");
+    return data;
+  }
+
+  /// Logical right shift that drops the least-significant n bits by advancing
+  /// the byte/bit index and reducing width. Returns a new immutable
+  /// view. Does not modify the underlying storage contents.
+  BitVector operator>>(size_t n) const;
+  BitVector &operator>>=(size_t n);
+
+  /// Create a new immutable view of a contiguous bit slice [offset,
+  /// offset+sliceWidth). The returned BitVector is a view (not an owning copy)
+  /// into the same underlying span. Throws if the requested slice exceeds the
+  /// current width.
+  BitVector slice(size_t offset, size_t sliceWidth) const;
+
+  /// Return a view of the N least-significant bits.
+  BitVector lsb(size_t n) const { return slice(0, n); }
+
+  /// Return a view of the N most-significant bits.
+  BitVector msb(size_t n) const {
+    if (n > bitWidth)
+      throw std::invalid_argument("msb width exceeds bit width");
+    return slice(bitWidth - n, n);
+  }
+
+  std::string toString(unsigned base = 16) const;
+
+  bool operator==(const BitVector &rhs) const;
+  bool operator!=(const BitVector &rhs) const { return !(*this == rhs); }
+
+  /// Bitwise AND: creates a new MutableBitVector with the result.
+  friend MutableBitVector operator&(const BitVector &a, const BitVector &b);
+
+  /// Bitwise OR: creates a new MutableBitVector with the result.
+  friend MutableBitVector operator|(const BitVector &a, const BitVector &b);
+
+  /// Bitwise XOR: creates a new MutableBitVector with the result.
+  friend MutableBitVector operator^(const BitVector &a, const BitVector &b);
+
+  /// Forward iterator for iterating over bits from LSB (index 0) to MSB.
+  class bit_iterator {
+  public:
+    using difference_type = std::ptrdiff_t;
+    using value_type = bool;
+    using pointer = const bool *;
+    using reference = bool;
+    using iterator_category = std::forward_iterator_tag;
+
+    /// Default constructor.
+    bit_iterator() = default;
+
+    /// Construct an iterator at the given bit position.
+    bit_iterator(const BitVector *bv, size_t pos = 0)
+        : bitVector(bv), position(pos) {}
+
+    /// Dereference: returns the bit value at the current position.
+    bool operator*() const {
+      if (bitVector == nullptr || position >= bitVector->bitWidth)
+        throw std::out_of_range("bit_iterator dereference out of range");
+      return bitVector->getBit(position);
+    }
+
+    /// Pre-increment: move to next bit.
+    bit_iterator &operator++() {
+      ++position;
+      return *this;
+    }
+
+    /// Post-increment: move to next bit.
+    bit_iterator operator++(int) {
+      bit_iterator tmp = *this;
+      ++position;
+      return tmp;
+    }
+
+    /// Equality comparison.
+    bool operator==(const bit_iterator &other) const {
+      return bitVector == other.bitVector && position == other.position;
+    }
+
+    /// Inequality comparison.
+    bool operator!=(const bit_iterator &other) const {
+      return !(*this == other);
+    }
+
+    /// Less-than comparison (for ranges support).
+    bool operator<(const bit_iterator &other) const {
+      return bitVector == other.bitVector && position < other.position;
+    }
+
+    /// Sentinel-compatible equality (for ranges support).
+    bool operator==(std::default_sentinel_t) const {
+      return bitVector == nullptr || position >= bitVector->bitWidth;
+    }
+
+    /// Sentinel-compatible inequality.
+    bool operator!=(std::default_sentinel_t sent) const {
+      return !(*this == sent);
+    }
+
+  private:
+    const BitVector *bitVector = nullptr;
+    size_t position = 0;
+  };
+
+  /// Return an iterator to the first bit (LSB).
+  bit_iterator begin() const { return bit_iterator(this, 0); }
+
+  /// Return an iterator past the last bit.
+  bit_iterator end() const { return bit_iterator(this, bitWidth); }
+
+protected:
+  // Underlying storage view. const, to allow for non-owning immutable views.
+  std::span<const byte> data{};
+  size_t bitWidth = 0;  // Number of valid bits.
+  uint8_t bitIndex = 0; // Starting bit offset in first byte.
+};
+
+/// A mutable bit vector that owns its underlying storage.
+/// It supports in-place modifications and mutable operations.
+class MutableBitVector : public BitVector {
+public:
+  /// Owning, zero-initialized constructor of a given width.
+  explicit MutableBitVector(size_t width);
+
+  /// Owning constructor from an rvalue vector (must move in).
+  MutableBitVector(std::vector<byte> &&bytes,
+                   std::optional<size_t> width = std::nullopt);
+
+  MutableBitVector() = default;
+
+  // Copy constructor: duplicate storage.
+  MutableBitVector(const MutableBitVector &other);
+
+  // Copy constructor from immutable BitVector: creates owning copy.
+  MutableBitVector(const BitVector &other);
+
+  // Move constructor: transfer ownership.
+  MutableBitVector(MutableBitVector &&other) noexcept;
+
+  // Move constructor from immutable BitVector: creates owning copy.
+  MutableBitVector(BitVector &&other);
+
+  MutableBitVector &operator=(const MutableBitVector &other);
+
+  MutableBitVector &operator=(MutableBitVector &&other) noexcept;
+
+  /// Set the i-th bit.
+  void setBit(size_t i, bool v);
+
+  /// Return a handle to the underlying span (always aligned since bitIndex=0).
+  std::span<const byte> getSpan() const { return data; }
+
+  /// Return and transfer ownership of the underlying storage.
+  std::vector<uint8_t> takeStorage() { return std::move(owner); }
+
+  /// In-place logical right shift that drops the least-significant n bits.
+  /// Reduces width and updates internal state. Does not modify underlying
+  /// storage.
+  MutableBitVector &operator>>=(size_t n);
+
+  /// In-place logical left shift shifts in n zero bits at LSB, shifting
+  /// existing bits upward.
+  MutableBitVector &operator<<=(size_t n);
+
+  /// In-place concatenate: appends bits from other to this.
+  MutableBitVector &operator<<=(const MutableBitVector &other);
+
+  MutableBitVector &operator|=(const MutableBitVector &other);
+  MutableBitVector &operator&=(const MutableBitVector &other);
+  MutableBitVector &operator^=(const MutableBitVector &other);
+  MutableBitVector operator~() const;
+  MutableBitVector operator|(const MutableBitVector &other) const;
+  MutableBitVector operator&(const MutableBitVector &other) const;
+  MutableBitVector operator^(const MutableBitVector &other) const;
+
+private:
+  // Storage owned by this MutableBitVector.
+  std::vector<byte> owner;
+};
+
+std::ostream &operator<<(std::ostream &os, const BitVector &bv);
+
+// Arbitrary width signed integer type built on MutableBitVector.
+class Int : public MutableBitVector {
+public:
+  using MutableBitVector::MutableBitVector;
+  Int() = default;
+  Int(int64_t v, unsigned width = 64);
+  operator int64_t() const { return toI64(); }
+  operator int32_t() const { return toInt<int32_t>(); }
+  operator int16_t() const { return toInt<int16_t>(); }
+  operator int8_t() const { return toInt<int8_t>(); }
+
+private:
+  template <typename T>
+  T toInt() const {
+    static_assert(std::is_integral<T>::value && std::is_signed<T>::value,
+                  "T must be a signed integral type");
+    int64_t v = toI64();
+    fits(v, sizeof(T) * 8);
+    return static_cast<T>(v);
+  }
+
+  // Convert the bitvector to a signed intN_t, throwing if the value doesn't
+  // fit.
+  int64_t toI64() const;
+
+  // Check if the given value fits in the specified bit width.
+  static void fits(int64_t v, unsigned n);
+};
+
+// Arbitrary width unsigned integer type built on MutableBitVector.
+class UInt : public MutableBitVector {
+public:
+  using MutableBitVector::MutableBitVector;
+  UInt() = default;
+  UInt(uint64_t v, unsigned width = 64);
+  operator uint64_t() const { return toUI64(); }
+  operator uint32_t() const { return toUInt<uint32_t>(); }
+  operator uint16_t() const { return toUInt<uint16_t>(); }
+  operator uint8_t() const { return toUInt<uint8_t>(); }
+
+private:
+  uint64_t toUI64() const;
+
+  static void fits(uint64_t v, unsigned n);
+
+  template <typename T>
+  T toUInt() const {
+    static_assert(std::is_integral<T>::value && std::is_unsigned<T>::value,
+                  "T must be an unsigned integral type");
+    uint64_t v = toUI64();
+    fits(v, sizeof(T) * 8);
+    return static_cast<T>(v);
+  }
+};
+
+} // namespace esi
+
+// Enable BitVector and MutableBitVector to work with std::ranges algorithms
+template <>
+inline constexpr bool std::ranges::enable_borrowed_range<esi::BitVector> = true;
+
+template <>
+inline constexpr bool
+    std::ranges::enable_borrowed_range<esi::MutableBitVector> = true;
+
+#endif // ESI_VALUES_H

esiaccel/include/esi/backends/Cosim.h

@@ -0,0 +1,78 @@
+//===- Cosim.h - ESI C++ cosimulation backend -------------------*- 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 is a specialization of the ESI C++ API (backend) for connection into a
+// simulation of an ESI system. Currently uses gRPC, but that could change.
+// Requires gRPC C++ library.
+//
+// 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_BACKENDS_COSIM_H
+#define ESI_BACKENDS_COSIM_H
+
+#include "esi/Accelerator.h"
+
+#include <memory>
+#include <set>
+
+namespace esi {
+namespace backends {
+namespace cosim {
+
+class CosimEngine;
+class RpcClient;
+
+/// Connect to an ESI simulation.
+class CosimAccelerator : public esi::AcceleratorConnection {
+  friend class CosimEngine;
+
+public:
+  CosimAccelerator(Context &, std::string hostname, uint16_t port);
+  ~CosimAccelerator();
+
+  static std::unique_ptr<AcceleratorConnection>
+  connect(Context &, std::string connectionString);
+
+  // Different ways to retrieve the manifest in Cosimulation.
+  enum ManifestMethod {
+    Cosim, // Use the backdoor cosim interface. Default.
+    MMIO,  // Use MMIO emulation.
+  };
+  // Set the way this connection will retrieve the manifest.
+  void setManifestMethod(ManifestMethod method);
+
+  void createEngine(const std::string &engineTypeName, AppIDPath idPath,
+                    const ServiceImplDetails &details,
+                    const HWClientDetails &clients) override;
+
+protected:
+  virtual Service *createService(Service::Type service, AppIDPath path,
+                                 std::string implName,
+                                 const ServiceImplDetails &details,
+                                 const HWClientDetails &clients) override;
+
+private:
+  std::unique_ptr<RpcClient> rpcClient;
+
+  // We own all channels connected to rpcClient since their lifetime is tied to
+  // rpcClient.
+  std::set<std::unique_ptr<ChannelPort>> channels;
+
+  ManifestMethod manifestMethod = Cosim;
+};
+
+} // namespace cosim
+} // namespace backends
+} // namespace esi
+
+#endif // ESI_BACKENDS_COSIM_H

esiaccel/include/esi/backends/RpcClient.h

@@ -0,0 +1,97 @@
+//===- RpcClient.h - ESI Cosim RPC client -----------------------*- 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 gRPC client implementation for ESI cosimulation.
+// It wraps all gRPC/protobuf dependencies so they don't leak into other
+// headers.
+//
+// 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_BACKENDS_RPCCLIENT_H
+#define ESI_BACKENDS_RPCCLIENT_H
+
+#include "esi/Common.h"
+
+#include <functional>
+#include <memory>
+#include <string>
+#include <vector>
+
+namespace esi {
+namespace backends {
+namespace cosim {
+
+/// A gRPC client for communicating with the cosimulation server.
+/// This class wraps all gRPC/protobuf dependencies.
+class RpcClient {
+public:
+  RpcClient(const std::string &hostname, uint16_t port);
+  ~RpcClient();
+
+  // Non-copyable.
+  RpcClient(const RpcClient &) = delete;
+  RpcClient &operator=(const RpcClient &) = delete;
+
+  /// Get the ESI version from the manifest.
+  uint32_t getEsiVersion() const;
+
+  /// Get the compressed manifest from the server.
+  std::vector<uint8_t> getCompressedManifest() const;
+
+  /// Channel direction as reported by the server.
+  enum class ChannelDirection { ToServer, ToClient };
+
+  /// Description of a channel from the server.
+  struct ChannelDesc {
+    std::string name;
+    std::string type;
+    ChannelDirection dir;
+  };
+
+  /// Get the channel description for a channel name.
+  /// Returns true if the channel was found.
+  bool getChannelDesc(const std::string &channelName, ChannelDesc &desc) const;
+
+  /// List all channels available on the server.
+  std::vector<ChannelDesc> listChannels() const;
+
+  /// Send a message to a server-bound channel.
+  void writeToServer(const std::string &channelName, const MessageData &data);
+
+  /// Callback type for receiving messages from a client-bound channel.
+  /// Return true if the message was consumed, false to retry.
+  using ReadCallback = std::function<bool(const MessageData &)>;
+
+  /// Abstract handle for a read channel connection.
+  /// Destructor disconnects from the channel.
+  class ReadChannelConnection {
+  public:
+    virtual ~ReadChannelConnection() = default;
+    virtual void disconnect() = 0;
+  };
+
+  /// Connect to a client-bound channel and receive messages via callback.
+  /// Returns a handle that disconnects when destroyed.
+  std::unique_ptr<ReadChannelConnection>
+  connectClientReceiver(const std::string &channelName, ReadCallback callback);
+
+private:
+  class Impl;
+  std::unique_ptr<Impl> impl;
+};
+
+} // namespace cosim
+} // namespace backends
+} // namespace esi
+
+#endif // ESI_BACKENDS_RPCCLIENT_H

esiaccel/include/esi/backends/RpcServer.h

@@ -0,0 +1,73 @@
+//===- RpcServer.h - Run a cosim server -------------------------*- 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
+//
+//===----------------------------------------------------------------------===//
+//
+// Setup and run a server accepting connections via the 'cosim' RPC protocol.
+// Then, one can request ports to and from the clients.
+//
+// Abstract this out to support multi-party communication in the future.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef ESI_COSIM_RPCSERVER_H
+#define ESI_COSIM_RPCSERVER_H
+
+#include "esi/Context.h"
+#include "esi/Ports.h"
+
+namespace esi {
+namespace cosim {
+
+/// TODO: make this a proper backend (as much as possible).
+class RpcServer {
+public:
+  RpcServer(Context &ctxt);
+  ~RpcServer();
+
+  /// Get the context.
+  Context &getContext() { return ctxt; }
+
+  /// Set the manifest and version. There is a race condition here in that the
+  /// RPC server can be started and a connection from the client could happen
+  /// before the manifest is set. TODO: rework the DPI API to require that the
+  /// manifest gets set first.
+  void setManifest(int esiVersion,
+                   const std::vector<uint8_t> &compressedManifest);
+
+  /// Register a read or write port which communicates over RPC.
+  ReadChannelPort &registerReadPort(const std::string &name,
+                                    const std::string &type);
+  WriteChannelPort &registerWritePort(const std::string &name,
+                                      const std::string &type);
+
+  // Stop the RPC server.
+  // If a millisecond timeout is provided, will forcefully stop the underlying
+  // RPC server once the timeout expires. If not, the RPC server will attempt to
+  // stop gracefully, implying that any outstanding RPC calls must be served
+  // before the server actually stops (see grpc::ServerInterface::Shutdown for
+  // more).
+  void stop(uint32_t timeoutMS = 0);
+
+  // Start the RPC server. If no port is provided, the RPC server will let the
+  // OS pick a port.
+  void run(int port = -1);
+
+  // Return which port the RPC server is executing on.
+  int getPort();
+
+  /// Hide the implementation details from this header file.
+  class Impl;
+
+private:
+  Context &ctxt;
+  std::unique_ptr<Impl> impl;
+};
+
+} // namespace cosim
+} // namespace esi
+
+#endif // ESI_COSIM_RPCSERVER_H

esiaccel/include/esi/backends/Trace.h

@@ -0,0 +1,87 @@
+//===- Trace.h - ESI trace backend ------------------------------*- 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 is a specialization of the ESI C++ API (backend) for trace-based
+// Accelerator interactions. This means that it will have the capability to read
+// trace files recorded from interactions with an actual connection. It also has
+// a mode wherein it will write to a file (for sends) and produce random data
+// (for receives). Both modes are intended for debugging without a simulation.
+//
+// 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_BACKENDS_COSIM_H
+#define ESI_BACKENDS_COSIM_H
+
+#include "esi/Accelerator.h"
+
+#include <filesystem>
+#include <memory>
+
+namespace esi {
+namespace backends {
+namespace trace {
+
+/// Connect to an ESI simulation.
+class TraceAccelerator : public esi::AcceleratorConnection {
+public:
+  enum Mode {
+    // Write data sent to the accelerator to the trace file. Produce random
+    // garbage data for reads from the accelerator.
+    Write,
+
+    // Sent data to the accelerator is compared against the trace file's record.
+    // Data read from the accelerator is read from the trace file.
+    // TODO: Full trace mode not yet supported.
+    // Read
+
+    // Discard all data sent to the accelerator. Disable trace file generation.
+    Discard,
+  };
+
+  /// Create a trace-based accelerator backend.
+  /// \param mode The mode of operation. See Mode.
+  /// \param manifestJson The path to the manifest JSON file.
+  /// \param traceFile The path to the trace file. For 'Write' mode, this file
+  ///   is opened for writing. For 'Read' mode, this file is opened for reading.
+  TraceAccelerator(Context &, Mode mode, std::filesystem::path manifestJson,
+                   std::filesystem::path traceFile);
+  ~TraceAccelerator() override;
+
+  /// Parse the connection string and instantiate the accelerator. Format is:
+  /// "<mode>:<manifest path>[:<traceFile>]".
+  static std::unique_ptr<AcceleratorConnection>
+  connect(Context &, std::string connectionString);
+
+  /// Internal implementation.
+  struct Impl;
+  Impl &getImpl();
+
+protected:
+  void createEngine(const std::string &engineTypeName, AppIDPath idPath,
+                    const ServiceImplDetails &details,
+                    const HWClientDetails &clients) override;
+
+  virtual Service *createService(Service::Type service, AppIDPath idPath,
+                                 std::string implName,
+                                 const ServiceImplDetails &details,
+                                 const HWClientDetails &clients) override;
+
+private:
+  std::unique_ptr<Impl> impl;
+};
+
+} // namespace trace
+} // namespace backends
+} // namespace esi
+
+#endif // ESI_BACKENDS_COSIM_H