esiaccel 0.1.0__cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

esiaccel/include/esi/Types.h

@@ -0,0 +1,182 @@
+//===- Types.h - ESI type 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
+//
+//===----------------------------------------------------------------------===//
+//
+// 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_TYPES_H
+#define ESI_TYPES_H
+
+#include <cstdint>
+#include <map>
+#include <string>
+#include <vector>
+
+namespace esi {
+
+/// Root class of the ESI type system.
+class Type {
+public:
+  using ID = std::string;
+  Type(const ID &id) : id(id) {}
+  virtual ~Type() = default;
+
+  ID getID() const { return id; }
+  virtual std::ptrdiff_t getBitWidth() const { return -1; }
+
+protected:
+  ID id;
+};
+
+/// Bundles represent a collection of channels. Services exclusively expose
+/// bundles (sometimes of just one channel). As such, they are the type of
+/// accessible ports on an accelerator, from a host API perspective.
+/// TODO: Add a good description of direction?
+class BundleType : public Type {
+public:
+  enum Direction { To, From };
+
+  using ChannelVector =
+      std::vector<std::tuple<std::string, Direction, const Type *>>;
+
+  BundleType(const ID &id, const ChannelVector &channels)
+      : Type(id), channels(channels) {}
+
+  const ChannelVector &getChannels() const { return channels; }
+  std::ptrdiff_t getBitWidth() const override { return -1; };
+
+  std::pair<const Type *, Direction> findChannel(std::string name) const {
+    for (auto [channelName, dir, type] : channels)
+      if (channelName == name)
+        return std::make_pair(type, dir);
+    throw std::runtime_error("Channel '" + name + "' not found in bundle");
+  }
+
+protected:
+  ChannelVector channels;
+};
+
+/// Channels are the basic communication primitives. They are unidirectional and
+/// carry one values of one type.
+class ChannelType : public Type {
+public:
+  ChannelType(const ID &id, const Type *inner) : Type(id), inner(inner) {}
+  const Type *getInner() const { return inner; }
+  std::ptrdiff_t getBitWidth() const override { return inner->getBitWidth(); };
+
+private:
+  const Type *inner;
+};
+
+/// The "void" type is a special type which can be used to represent no type.
+class VoidType : public Type {
+public:
+  VoidType(const ID &id) : Type(id) {}
+  // 'void' is 1 bit by convention.
+  std::ptrdiff_t getBitWidth() const override { return 1; };
+};
+
+/// The "any" type is a special type which can be used to represent any type, as
+/// identified by the type id. Said type id is guaranteed to be present in the
+/// manifest. Importantly, the "any" type id over the wire may not be a string
+/// as it is in software.
+class AnyType : public Type {
+public:
+  AnyType(const ID &id) : Type(id) {}
+  std::ptrdiff_t getBitWidth() const override { return -1; };
+};
+
+/// Bit vectors include signed, unsigned, and signless integers.
+class BitVectorType : public Type {
+public:
+  BitVectorType(const ID &id, uint64_t width) : Type(id), width(width) {}
+
+  uint64_t getWidth() const { return width; }
+  std::ptrdiff_t getBitWidth() const override { return getWidth(); };
+
+private:
+  uint64_t width;
+};
+
+/// Bits are just an array of bits. They are not interpreted as a number but are
+/// identified in the manifest as "signless" ints.
+class BitsType : public BitVectorType {
+public:
+  using BitVectorType::BitVectorType;
+};
+
+/// Integers are bit vectors which may be signed or unsigned and are interpreted
+/// as numbers.
+class IntegerType : public BitVectorType {
+public:
+  using BitVectorType::BitVectorType;
+};
+
+/// Signed integer.
+class SIntType : public IntegerType {
+public:
+  using IntegerType::IntegerType;
+};
+
+/// Unsigned integer.
+class UIntType : public IntegerType {
+public:
+  using IntegerType::IntegerType;
+};
+
+/// Structs are an ordered collection of fields, each with a name and a type.
+class StructType : public Type {
+public:
+  using FieldVector = std::vector<std::pair<std::string, const Type *>>;
+
+  StructType(const ID &id, const FieldVector &fields)
+      : Type(id), fields(fields) {}
+
+  const FieldVector &getFields() const { return fields; }
+  std::ptrdiff_t getBitWidth() const override {
+    std::ptrdiff_t size = 0;
+    for (auto [name, ty] : getFields()) {
+      std::ptrdiff_t fieldSize = ty->getBitWidth();
+      if (fieldSize < 0)
+        return -1;
+      size += fieldSize;
+    }
+    return size;
+  }
+
+private:
+  FieldVector fields;
+};
+
+/// Arrays have a compile time specified (static) size and an element type.
+class ArrayType : public Type {
+public:
+  ArrayType(const ID &id, const Type *elementType, uint64_t size)
+      : Type(id), elementType(elementType), size(size) {}
+
+  const Type *getElementType() const { return elementType; }
+  uint64_t getSize() const { return size; }
+  std::ptrdiff_t getBitWidth() const override {
+    std::ptrdiff_t elementSize = elementType->getBitWidth();
+    if (elementSize < 0)
+      return -1;
+    return elementSize * size;
+  }
+
+private:
+  const Type *elementType;
+  uint64_t size;
+};
+
+} // namespace esi
+
+#endif // ESI_TYPES_H

esiaccel/include/esi/Utils.h

@@ -0,0 +1,102 @@
+//===- Utils.h - ESI runtime utility code -----------------------*- 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_UTILS_H
+#define ESI_UTILS_H
+
+#include <cstdint>
+#include <functional>
+#include <mutex>
+#include <optional>
+#include <queue>
+#include <string>
+
+namespace esi {
+namespace utils {
+// Very basic base64 encoding.
+void encodeBase64(const void *data, size_t size, std::string &out);
+
+/// C++'s stdlib doesn't have a hash_combine function. This is a simple one.
+inline size_t hash_combine(size_t h1, size_t h2) {
+  return h1 + 0x9e3779b9 + (h2 << 6) + (h2 >> 2);
+}
+
+/// Thread safe queue. Just wraps std::queue protected with a lock. Long term,
+/// we need to avoid copying data. It has a lot of data copies currently.
+template <typename T>
+class TSQueue {
+  using Lock = std::lock_guard<std::mutex>;
+
+  /// The queue and its mutex.
+  mutable std::mutex qM;
+  std::queue<T> q;
+
+  /// A mutex to ensure that only one 'pop' operation is happening at a time. It
+  /// is critical that locks be obtained on this and `qM` same order in both pop
+  /// methods. This lock should be obtained first since one of the pop methods
+  /// must unlock `qM` then relock it.
+  std::mutex popM;
+
+public:
+  /// Push onto the queue.
+  template <typename... E>
+  void push(E... t) {
+    Lock l(qM);
+    q.emplace(t...);
+  }
+
+  /// Pop something off the queue but return nullopt if the queue is empty. Why
+  /// doesn't std::queue have anything like this?
+  std::optional<T> pop() {
+    Lock pl(popM);
+    Lock ql(qM);
+    if (q.size() == 0)
+      return std::nullopt;
+    auto t = q.front();
+    q.pop();
+    return t;
+  }
+
+  /// Call the callback for the front of the queue (if anything is there). Only
+  /// pop it off the queue if the callback returns true.
+  void pop(std::function<bool(const T &)> callback) {
+    // Since we need to unlock the mutex to call the callback, the queue
+    // could be pushed on to and its memory layout could thusly change,
+    // invalidating the reference returned by `.front()`. The easy solution here
+    // is to copy the data. TODO: Avoid copying the data.
+    Lock pl(popM);
+    T t;
+    {
+      Lock l(qM);
+      if (q.size() == 0)
+        return;
+      t = q.front();
+    }
+    if (callback(t)) {
+      Lock l(qM);
+      q.pop();
+    }
+  }
+
+  /// Is the queue empty?
+  bool empty() const {
+    Lock l(qM);
+    return q.empty();
+  }
+};
+} // namespace utils
+} // namespace esi
+
+#endif // ESI_UTILS_H

esiaccel/include/esi/backends/Cosim.h

@@ -0,0 +1,85 @@
+//===- 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 Cap'nProto RPC, but that could
+// change. Requires Cap'nProto 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 cosim {
+class ChannelDesc;
+}
+
+namespace backends {
+namespace cosim {
+class CosimEngine;
+
+/// 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);
+
+  // C++ doesn't have a mechanism to forward declare a nested class and we don't
+  // want to include the generated header here. So we have to wrap it in a
+  // forward-declared struct we write ourselves.
+  struct StubContainer;
+
+  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:
+  StubContainer *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/RpcServer.h

@@ -0,0 +1,55 @@
+//===- 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/Ports.h"
+
+namespace esi {
+namespace cosim {
+
+/// TODO: make this a proper backend (as much as possible).
+class RpcServer {
+public:
+  ~RpcServer();
+
+  /// 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);
+
+  void stop();
+  void run(int port);
+
+  /// Hide the implementation details from this header file.
+  class Impl;
+
+private:
+  Impl *impl = nullptr;
+};
+
+} // 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