esiaccel 0.1.5.dev347__cp310-cp310-win_amd64.whl → 0.2.3.dev80__cp310-cp310-win_amd64.whl

esiaccel/include/esi/Ports.h

@@ -35,13 +35,81 @@ using PortMap = std::map<std::string, ChannelPort &>;
 /// but used by higher level APIs which add types.
 class ChannelPort {
 public:
-  ChannelPort(const Type *type) : type(type) {}
+  ChannelPort(const 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;
+  struct ConnectOptions {
+    /// 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.
+    std::optional<unsigned> bufferSize = std::nullopt;
+
+    /// If the type of this port is a window, translate the incoming/outgoing
+    /// data into its underlying ('into') type. For 'into' types without lists,
+    /// just re-arranges the data fields from the lowered type to the 'into'
+    /// type.
+    ///
+    /// If this option is false, no translation is done and the data is
+    /// passed through as-is. Same is true for non-windowed types.
+    ///
+    /// For messages with lists, only two types are supported:
+    ///   1) Parallel encoding includes any 'header' data with each frame. Said
+    ///      header data is the same across all frames, so this encoding is
+    ///      inefficient but is commonly used for on-chip streaming interfaces.
+    ///      Each frame contains a 'last' field to indicate the end of the list.
+    ///      In cases where 'numItems' is greater than 1, a field named
+    ///      '<listField>_size' indicates the number of valid items in that
+    ///      frame.
+    ///   2) Serial (bulk transfer) encoding, where a 'header' frame precedes
+    ///      the list data frame. Said header frame contains a 'count' field
+    ///      indicating the number of items in the list.  Importantly, the
+    ///      header frame is always re-transmitted after the specified number of
+    ///      list items have been sent. If the 'count' field is zero, the end of
+    ///      the list has been reached. If it is non-zero, the message has not
+    ///      been completely transmitted and reading should continue until a
+    ///      'count' of zero is received.
+    ///
+    /// In both cases, the host-side MessageData contains the complete header
+    /// followed by the list data. In other words, header data is not duplicated
+    /// in the returned message. So for a windowed type with header fields and
+    /// a list of (x,y) coordinates, the host memory layout would be:
+    /// ```
+    /// struct ExampleList {
+    ///   uint32_t headerField2; // SystemVerilog ordering
+    ///   uint32_t headerField1;
+    ///   size_t   list_length; // Number list items
+    ///   struct { uint16_t y, x; } list_data[];
+    /// }
+    /// ```
+    ///
+    /// In a parallel encoding, each frame's wire format (from hardware) is:
+    /// ```
+    /// struct ExampleListFrame {
+    ///   uint8_t list_last; // Non-zero indicates last item in list
+    ///   struct { uint16_t y, x; } list_data[numItems]; // SV field ordering
+    ///   uint32_t headerField2; // SV struct ordering (reversed)
+    ///   uint32_t headerField1;
+    /// }
+    /// ```
+    ///
+    /// Important note: for consistency, preserves SystemVerilog struct field
+    /// ordering! So it's the opposite of C struct ordering.
+    ///
+    /// Implementation status:
+    ///   - Only parallel list encoding is supported.
+    ///   - Fields must be byte-aligned.
+    ///
+    /// See the CIRCT documentation (or td files) for more details on windowed
+    /// messages.
+    bool translateMessage = true;
+
+    ConnectOptions(std::optional<unsigned> bufferSize = std::nullopt,
+                   bool translateMessage = true)
+        : bufferSize(bufferSize), translateMessage(translateMessage) {}
+  };
+
+  /// Set up a connection to the accelerator.
+  virtual void connect(const ConnectOptions &options = ConnectOptions()) = 0;
   virtual void disconnect() = 0;
   virtual bool isConnected() const = 0;
 
@@ -64,13 +132,74 @@ public:
 protected:
   const Type *type;
 
+  /// Instructions for translating windowed types. Precomputes and optimizes a
+  /// list of copy operations.
+  struct TranslationInfo {
+    TranslationInfo(const WindowType *windowType) : windowType(windowType) {}
+
+    /// Precompute and optimize the copy operations for translating frames.
+    void precomputeFrameInfo();
+
+    /// The window type being translated.
+    const WindowType *windowType;
+
+    /// A copy operation for translating between frame data and the translation.
+    /// Run this during the translation.
+    struct CopyOp {
+      /// Offset in the incoming/outgoing frame data.
+      size_t frameOffset;
+      /// Offset in the translation buffer.
+      size_t bufferOffset;
+      /// Number of bytes to copy.
+      size_t size;
+    };
+
+    /// Information about a list field within a frame (for parallel encoding).
+    /// Note: Currently only numItems == 1 is supported (one list element per
+    /// frame).
+    struct ListFieldInfo {
+      /// Name of the list field.
+      std::string fieldName;
+      /// Offset of the list data array in the frame.
+      size_t dataOffset;
+      /// Size of each list element in bytes.
+      size_t elementSize;
+      /// Offset of the 'last' field in the frame.
+      size_t lastFieldOffset;
+      /// Offset in the translation buffer where list length is stored.
+      size_t listLengthBufferOffset;
+      /// Offset in the translation buffer where list data starts.
+      size_t listDataBufferOffset;
+    };
+
+    /// Information about each frame in the windowed type.
+    struct FrameInfo {
+      /// The total size of a frame in bytes.
+      size_t expectedSize;
+      /// Precomputed copy operations for translating this frame (non-list
+      /// fields).
+      std::vector<CopyOp> copyOps;
+      /// Information about list fields in this frame (parallel encoding).
+      /// Currently only one list field per frame is supported.
+      std::optional<ListFieldInfo> listField;
+    };
+    /// Precomputed information about each frame.
+    std::vector<FrameInfo> frames;
+    /// Size of the 'into' type in bytes (for fixed-size types).
+    /// For types with lists, this is the size of the fixed header portion.
+    size_t intoTypeBytes = 0;
+    /// True if the window contains a list field (variable-size message).
+    bool hasListField = false;
+  };
+  std::unique_ptr<TranslationInfo> translationInfo;
+
   /// 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) {}
+  virtual void connectImpl(const ConnectOptions &options) {}
 };
 
 /// A ChannelPort which sends data to the accelerator.
@@ -78,9 +207,11 @@ class WriteChannelPort : public ChannelPort {
 public:
   using ChannelPort::ChannelPort;
 
-  virtual void
-  connect(std::optional<unsigned> bufferSize = std::nullopt) override {
-    connectImpl(bufferSize);
+  virtual void connect(const ConnectOptions &options = {}) override {
+    translateMessages = options.translateMessage && translationInfo;
+    if (translateMessages)
+      translationInfo->precomputeFrameInfo();
+    connectImpl(options);
     connected = true;
   }
   virtual void disconnect() override { connected = false; }
@@ -88,12 +219,72 @@ public:
 
   /// A very basic blocking write API. Will likely change for performance
   /// reasons.
-  virtual void write(const MessageData &) = 0;
+  void write(const MessageData &data) {
+    if (translateMessages) {
+      assert(translationBuffer.empty() &&
+             "Cannot call write() with pending translated messages");
+      translateOutgoing(data);
+      for (auto &msg : translationBuffer)
+        writeImpl(msg);
+      translationBuffer.clear();
+    } else {
+      writeImpl(data);
+    }
+  }
+
+  /// A basic non-blocking write API. Returns true if any of the data was queued
+  /// and/or sent. If the data type is a window a 'true' return does not
+  /// indicate that the message has been completely written. The 'flush' method
+  /// can be used to check that the entire buffer has been written. It is
+  /// invalid for backends to always return false (i.e. backends must eventually
+  /// ensure that writes may succeed).
+  bool tryWrite(const MessageData &data) {
+    if (translateMessages) {
+      // Do not accept a new message if there are pending messages to flush.
+      if (!flush())
+        return false;
+      assert(translationBuffer.empty() &&
+             "Translation buffer should be empty after successful flush");
+      translateOutgoing(data);
+      flush();
+      return true;
+    } else {
+      return tryWriteImpl(data);
+    }
+  }
+  /// Flush any buffered data. Returns true if all data was flushed.
+  ///
+  /// If `translateMessages` is false, calling `flush()` will immediately return
+  /// true and perform no action, as there is no buffered data to flush.
+  bool flush() {
+    while (translationBufferIdx < translationBuffer.size()) {
+      if (!tryWriteImpl(translationBuffer[translationBufferIdx]))
+        return false;
+      ++translationBufferIdx;
+    }
+    translationBuffer.clear();
+    translationBufferIdx = 0;
+    return true;
+  }
 
-  /// 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;
+protected:
+  /// Implementation for write(). Subclasses must implement this.
+  virtual void writeImpl(const MessageData &) = 0;
+
+  /// Implementation for tryWrite(). Subclasses must implement this.
+  virtual bool tryWriteImpl(const MessageData &data) = 0;
+
+  /// Whether to translate outgoing data if the port type is a window type. Set
+  /// by the connect() method.
+  bool translateMessages = false;
+  /// If tryWrite cannot write all the messages of a windowed type at once, it
+  /// stores them here and writes them out one by one on subsequent calls.
+  std::vector<MessageData> translationBuffer;
+  /// Index of the next message to write in translationBuffer.
+  size_t translationBufferIdx = 0;
+  /// Translate outgoing data if the port type is a window type. Append the new
+  /// message 'chunks' to translationBuffer.
+  void translateOutgoing(const MessageData &data);
 
 private:
   volatile bool connected = false;
@@ -105,15 +296,18 @@ public:
   UnknownWriteChannelPort(const Type *type, std::string errmsg)
       : WriteChannelPort(type), errmsg(errmsg) {}
 
-  void connect(std::optional<unsigned> bufferSize = std::nullopt) override {
+  void connect(const ConnectOptions &options = {}) override {
     throw std::runtime_error(errmsg);
   }
-  void write(const MessageData &) override { throw std::runtime_error(errmsg); }
-  bool tryWrite(const MessageData &) override {
+
+protected:
+  void writeImpl(const MessageData &) override {
+    throw std::runtime_error(errmsg);
+  }
+  bool tryWriteImpl(const MessageData &) override {
     throw std::runtime_error(errmsg);
   }
 
-protected:
   std::string errmsg;
 };
 
@@ -143,7 +337,7 @@ public:
   //===--------------------------------------------------------------------===//
 
   virtual void connect(std::function<bool(MessageData)> callback,
-                       std::optional<unsigned> bufferSize = std::nullopt);
+                       const ConnectOptions &options = {});
 
   //===--------------------------------------------------------------------===//
   // Polling mode methods: To use futures or blocking reads, connect without any
@@ -154,8 +348,7 @@ public:
   static constexpr uint64_t DefaultMaxDataQueueMsgs = 32;
 
   /// Connect to the channel in polling mode.
-  virtual void
-  connect(std::optional<unsigned> bufferSize = std::nullopt) override;
+  virtual void connect(const ConnectOptions &options = {}) override;
 
   /// Asynchronous read.
   virtual std::future<MessageData> readAsync();
@@ -184,6 +377,20 @@ protected:
   /// Backends call this callback when new data is available.
   std::function<bool(MessageData)> callback;
 
+  /// Window translation support.
+  std::vector<uint8_t> translationBuffer;
+  /// Index of the next expected frame (for multi-frame windows).
+  size_t nextFrameIndex = 0;
+  /// For list fields: accumulated list data across frames.
+  std::vector<uint8_t> listDataBuffer;
+  /// Flag to track whether we're in the middle of accumulating list data.
+  bool accumulatingListData = false;
+  /// Reset translation state buffers and indices.
+  void resetTranslationState();
+  /// Translate incoming data if the port type is a window type. Returns true if
+  /// the message has been completely received.
+  bool translateIncoming(MessageData &data);
+
   //===--------------------------------------------------------------------===//
   // Polling mode members.
   //===--------------------------------------------------------------------===//
@@ -206,10 +413,10 @@ public:
       : ReadChannelPort(type), errmsg(errmsg) {}
 
   void connect(std::function<bool(MessageData)> callback,
-               std::optional<unsigned> bufferSize = std::nullopt) override {
+               const ConnectOptions &options = ConnectOptions()) override {
     throw std::runtime_error(errmsg);
   }
-  void connect(std::optional<unsigned> bufferSize = std::nullopt) override {
+  void connect(const ConnectOptions &options = ConnectOptions()) override {
     throw std::runtime_error(errmsg);
   }
   std::future<MessageData> readAsync() override {

esiaccel/include/esi/Services.h

@@ -25,10 +25,21 @@
 #include "esi/Ports.h"
 
 #include <cstdint>
+#include <list>
 
 namespace esi {
 class AcceleratorConnection;
 class Engine;
+namespace services {
+class Service;
+}
+
+// While building the design, keep around a std::map of active services indexed
+// by the service name. When a new service is encountered during descent, add it
+// to the table (perhaps overwriting one). Modifications to the table only apply
+// to the current branch, so copy this and update it at each level of the tree.
+using ServiceTable = std::map<std::string, services::Service *>;
+
 namespace services {
 
 /// Add a custom interface to a service client at a particular point in the
@@ -38,7 +49,9 @@ public:
   using BundlePort::BundlePort;
   virtual ~ServicePort() = default;
   // Get a description of the service port.
-  virtual std::optional<std::string> toString() const { return std::nullopt; }
+  virtual std::optional<std::string> toString(bool oneLine = false) const {
+    return std::nullopt;
+  }
 };
 
 /// Parent class of all APIs modeled as 'services'. May or may not map to a
@@ -107,6 +120,14 @@ public:
   /// Get the ESI version number to check version compatibility.
   virtual uint32_t getEsiVersion() const = 0;
 
+  /// Get the current cycle count of the accelerator system.
+  virtual std::optional<uint64_t> getCycleCount() const { return std::nullopt; }
+  /// Get the "core" clock frequency of the accelerator system in Hz. Returns
+  /// nullopt if the accelerator does not provide this information.
+  virtual std::optional<uint64_t> getCoreClockFrequency() const {
+    return std::nullopt;
+  }
+
   /// Return the JSON-formatted system manifest.
   virtual std::string getJsonManifest() const;
 
@@ -170,7 +191,8 @@ public:
     /// 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 {
+    virtual std::optional<std::string>
+    toString(bool oneLine = false) const override {
       return "MMIO region " + toHex(desc.base) + " - " +
              toHex(desc.base + desc.size);
     }
@@ -189,6 +211,12 @@ public:
   /// Get the ESI version number to check version compatibility.
   uint32_t getEsiVersion() const override;
 
+  /// Get the current cycle count of the accelerator system's core clock.
+  std::optional<uint64_t> getCycleCount() const override;
+  /// Get the "core" clock frequency of the accelerator system in Hz. Returns
+  /// nullopt if the accelerator does not provide this information.
+  std::optional<uint64_t> getCoreClockFrequency() const override;
+
   /// Return the zlib compressed JSON system manifest.
   virtual std::vector<uint8_t> getCompressedManifest() const override;
 
@@ -282,10 +310,12 @@ public:
           ->getInner();
     }
 
-    virtual std::optional<std::string> toString() const override {
+    virtual std::optional<std::string>
+    toString(bool oneLine = false) const override {
       const esi::Type *argType = getArgType();
       const esi::Type *resultType = getResultType();
-      return "function " + resultType->getID() + "(" + argType->getID() + ")";
+      return "function " + resultType->toString(oneLine) + "(" +
+             argType->toString(oneLine) + ")";
     }
 
   private:
@@ -338,10 +368,12 @@ public:
           ->getInner();
     }
 
-    virtual std::optional<std::string> toString() const override {
+    virtual std::optional<std::string>
+    toString(bool oneLine = false) const override {
       const esi::Type *argType = getArgType();
       const esi::Type *resultType = getResultType();
-      return "callback " + resultType->getID() + "(" + argType->getID() + ")";
+      return "callback " + resultType->toString(oneLine) + "(" +
+             argType->toString(oneLine) + ")";
     }
 
   private:
@@ -365,37 +397,51 @@ public:
   virtual std::string getServiceSymbol() const override;
   virtual BundlePort *getPort(AppIDPath id,
                               const BundleType *type) const override;
+  virtual Service *getChildService(Service::Type service, AppIDPath id = {},
+                                   std::string implName = {},
+                                   ServiceImplDetails details = {},
+                                   HWClientDetails clients = {}) override;
+  MMIO::MMIORegion *getMMIORegion() const;
 
   /// A telemetry port which gets attached to a service port.
-  class Telemetry : public ServicePort {
+  class Metric : public ServicePort {
     friend class TelemetryService;
-    Telemetry(AppID id, const BundleType *type, PortMap channels);
+    Metric(AppID id, const BundleType *type, PortMap channels,
+           const TelemetryService *telemetryService,
+           std::optional<uint64_t> offset);
 
   public:
-    static Telemetry *get(AppID id, BundleType *type, WriteChannelPort &get,
-                          ReadChannelPort &data);
-
     void connect();
     std::future<MessageData> read();
+    uint64_t readInt();
 
-    virtual std::optional<std::string> toString() const override {
+    virtual std::optional<std::string>
+    toString(bool oneLine = false) const override {
       const esi::Type *dataType =
           dynamic_cast<const ChannelType *>(type->findChannel("data").first)
               ->getInner();
-      return "telemetry " + dataType->getID();
+      return "telemetry " + dataType->toString(oneLine);
     }
 
   private:
-    WriteChannelPort *get_req;
-    ReadChannelPort *data;
+    const TelemetryService *telemetryService;
+    MMIO::MMIORegion *mmio;
+    std::optional<uint64_t> offset;
   };
 
-  const std::map<AppIDPath, Telemetry *> &getTelemetryPorts() {
-    return telemetryPorts;
+  std::map<AppIDPath, Metric *> getTelemetryPorts() {
+    std::map<AppIDPath, Metric *> ports;
+    getTelemetryPorts(ports);
+    return ports;
   }
+  void getTelemetryPorts(std::map<AppIDPath, Metric *> &ports);
 
 private:
-  mutable std::map<AppIDPath, Telemetry *> telemetryPorts;
+  AppIDPath id;
+  mutable MMIO::MMIORegion *mmio;
+  std::map<AppIDPath, uint64_t> portAddressAssignments;
+  mutable std::map<AppIDPath, Metric *> telemetryPorts;
+  std::list<TelemetryService *> children;
 };
 
 /// Registry of services which can be instantiated directly by the Accelerator

esiaccel/include/esi/Types.h

@@ -80,6 +80,12 @@ public:
     }
   }
 
+  // Dump a textual representation of this type to the provided stream.
+  void dump(std::ostream &os, bool oneLine = false) const;
+
+  // Return a textual representation of this type.
+  std::string toString(bool oneLine = false) const;
+
 protected:
   ID id;
 };
@@ -268,6 +274,61 @@ private:
   bool reverse;
 };
 
+/// Windows represent a fixed-size sliding window over a stream of data.
+/// They define an "into" type (the data structure being windowed) and a
+/// "loweredType" (the hardware representation including control signals).
+class WindowType : public Type {
+public:
+  /// Field information describing a field within a frame.
+  struct Field {
+    std::string name;
+    uint64_t numItems = 0;       // 0 means not specified (use all items)
+    uint64_t bulkCountWidth = 0; // 0 means parallel encoding, >0 means serial
+  };
+
+  /// Frame information describing which fields are included in a particular
+  /// frame.
+  struct Frame {
+    std::string name;
+    std::vector<Field> fields;
+  };
+
+  WindowType(const ID &id, const std::string &name, const Type *intoType,
+             const Type *loweredType, const std::vector<Frame> &frames)
+      : Type(id), name(name), intoType(intoType), loweredType(loweredType),
+        frames(frames) {}
+
+  const std::string &getName() const { return name; }
+  const Type *getIntoType() const { return intoType; }
+  const Type *getLoweredType() const { return loweredType; }
+  const std::vector<Frame> &getFrames() const { return frames; }
+
+  std::ptrdiff_t getBitWidth() const override {
+    return loweredType->getBitWidth();
+  }
+
+private:
+  std::string name;
+  const Type *intoType;
+  const Type *loweredType;
+  std::vector<Frame> frames;
+};
+
+/// Lists represent variable-length sequences of elements of a single type.
+/// Unlike arrays which have a fixed size, lists can have any length.
+class ListType : public Type {
+public:
+  ListType(const ID &id, const Type *elementType)
+      : Type(id), elementType(elementType) {}
+
+  const Type *getElementType() const { return elementType; }
+
+  std::ptrdiff_t getBitWidth() const override { return -1; }
+
+private:
+  const Type *elementType;
+};
+
 } // namespace esi
 
 #endif // ESI_TYPES_H

esiaccel/include/esi/backends/Cosim.h

@@ -7,8 +7,8 @@
 //===----------------------------------------------------------------------===//
 //
 // 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.
+// 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
@@ -26,13 +26,11 @@
 #include <set>
 
 namespace esi {
-namespace cosim {
-class ChannelDesc;
-}
-
 namespace backends {
 namespace cosim {
+
 class CosimEngine;
+class RpcClient;
 
 /// Connect to an ESI simulation.
 class CosimAccelerator : public esi::AcceleratorConnection {
@@ -53,11 +51,6 @@ public:
   // 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;
@@ -69,7 +62,7 @@ protected:
                                  const HWClientDetails &clients) override;
 
 private:
-  StubContainer *rpcClient;
+  std::unique_ptr<RpcClient> rpcClient;
 
   // We own all channels connected to rpcClient since their lifetime is tied to
   // rpcClient.