esiaccel 0.1.4.dev31__cp310-cp310-win_amd64.whl → 0.2.3.dev80__cp310-cp310-win_amd64.whl

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;
 
@@ -124,7 +145,8 @@ public:
     uint32_t size;
   };
 
-  MMIO(AcceleratorConnection &, const HWClientDetails &clients);
+  MMIO(AcceleratorConnection &, const AppIDPath &idPath,
+       const HWClientDetails &clients);
   virtual ~MMIO() = default;
 
   /// Read a 64-bit value from the global MMIO space.
@@ -169,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);
     }
@@ -188,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;
 
@@ -270,14 +299,23 @@ public:
     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() + ")";
+    const esi::Type *getArgType() const {
+      return dynamic_cast<const ChannelType *>(type->findChannel("arg").first)
+          ->getInner();
+    }
+
+    const esi::Type *getResultType() const {
+      return dynamic_cast<const ChannelType *>(
+                 type->findChannel("result").first)
+          ->getInner();
+    }
+
+    virtual std::optional<std::string>
+    toString(bool oneLine = false) const override {
+      const esi::Type *argType = getArgType();
+      const esi::Type *resultType = getResultType();
+      return "function " + resultType->toString(oneLine) + "(" +
+             argType->toString(oneLine) + ")";
     }
 
   private:
@@ -319,14 +357,23 @@ public:
     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() + ")";
+    const esi::Type *getArgType() const {
+      return dynamic_cast<const ChannelType *>(type->findChannel("arg").first)
+          ->getInner();
+    }
+
+    const esi::Type *getResultType() const {
+      return dynamic_cast<const ChannelType *>(
+                 type->findChannel("result").first)
+          ->getInner();
+    }
+
+    virtual std::optional<std::string>
+    toString(bool oneLine = false) const override {
+      const esi::Type *argType = getArgType();
+      const esi::Type *resultType = getResultType();
+      return "callback " + resultType->toString(oneLine) + "(" +
+             argType->toString(oneLine) + ")";
     }
 
   private:
@@ -350,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

@@ -16,11 +16,18 @@
 #ifndef ESI_TYPES_H
 #define ESI_TYPES_H
 
+#include <algorithm>
+#include <any>
 #include <cstdint>
 #include <map>
+#include <span>
+#include <stdexcept>
 #include <string>
 #include <vector>
 
+#include "esi/Common.h"
+#include "esi/Values.h" // For BitVector / Int / UInt
+
 namespace esi {
 
 /// Root class of the ESI type system.
@@ -33,6 +40,52 @@ public:
   ID getID() const { return id; }
   virtual std::ptrdiff_t getBitWidth() const { return -1; }
 
+  /// Serialize an object to a MutableBitVector (LSB-first stream). The object
+  /// should be passed via std::any. Implementations append fields in the order
+  /// they are iterated (the first serialized field occupies the
+  /// least-significant bits of the result).
+  virtual MutableBitVector serialize(const std::any &obj) const {
+    throw std::runtime_error("Serialization not implemented for type " + id);
+  }
+
+  /// Deserialize from a BitVector stream (LSB-first). Implementations consume
+  /// bits from 'data' in-place (via logical right shifts) and return the
+  /// reconstructed value. Remaining bits stay in 'data'.
+  virtual std::any deserialize(BitVector &data) const {
+    throw std::runtime_error("Deserialization not implemented for type " + id);
+  }
+
+  // Deserialize from a MessageData buffer. Maps the MessageData onto a
+  // MutableBitVector, and proceeds with regular MutableBitVector
+  // deserialization.
+  std::any deserialize(const MessageData &data) const {
+    auto bv = MutableBitVector(std::vector<uint8_t>(data.getData()));
+    return deserialize(bv);
+  }
+
+  /// Ensure that a std::any object is valid for this type. Throws
+  /// std::runtime_error if the object is not valid.
+  virtual void ensureValid(const std::any &obj) const {
+    throw std::runtime_error("Validation not implemented for type " + id);
+  }
+
+  // Check if a std::any object is valid for this type. Returns an optional
+  // error message if the object is not valid, else, std::nullopt.
+  std::optional<std::string> isValid(const std::any &obj) const {
+    try {
+      ensureValid(obj);
+      return std::nullopt;
+    } catch (const std::runtime_error &e) {
+      return e.what();
+    }
+  }
+
+  // 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;
 };
@@ -54,12 +107,7 @@ public:
   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");
-  }
+  std::pair<const Type *, Direction> findChannel(std::string name) const;
 
 protected:
   ChannelVector channels;
@@ -69,10 +117,15 @@ protected:
 /// carry one values of one type.
 class ChannelType : public Type {
 public:
+  using Type::deserialize;
   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(); };
 
+  void ensureValid(const std::any &obj) const override;
+  MutableBitVector serialize(const std::any &obj) const override;
+  std::any deserialize(BitVector &data) const override;
+
 private:
   const Type *inner;
 };
@@ -80,9 +133,14 @@ private:
 /// The "void" type is a special type which can be used to represent no type.
 class VoidType : public Type {
 public:
+  using Type::deserialize;
   VoidType(const ID &id) : Type(id) {}
   // 'void' is 1 bit by convention.
   std::ptrdiff_t getBitWidth() const override { return 1; };
+
+  void ensureValid(const std::any &obj) const override;
+  MutableBitVector serialize(const std::any &obj) const override;
+  std::any deserialize(BitVector &data) const override;
 };
 
 /// The "any" type is a special type which can be used to represent any type, as
@@ -112,6 +170,11 @@ private:
 class BitsType : public BitVectorType {
 public:
   using BitVectorType::BitVectorType;
+  using Type::deserialize;
+
+  void ensureValid(const std::any &obj) const override;
+  MutableBitVector serialize(const std::any &obj) const override;
+  std::any deserialize(BitVector &data) const override;
 };
 
 /// Integers are bit vectors which may be signed or unsigned and are interpreted
@@ -125,21 +188,32 @@ public:
 class SIntType : public IntegerType {
 public:
   using IntegerType::IntegerType;
+  using Type::deserialize;
+
+  void ensureValid(const std::any &obj) const override;
+  MutableBitVector serialize(const std::any &obj) const override;
+  std::any deserialize(BitVector &data) const override;
 };
 
 /// Unsigned integer.
 class UIntType : public IntegerType {
 public:
   using IntegerType::IntegerType;
+  using Type::deserialize;
+
+  void ensureValid(const std::any &obj) const override;
+  MutableBitVector serialize(const std::any &obj) const override;
+  std::any deserialize(BitVector &data) const override;
 };
 
 /// 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 *>>;
+  using Type::deserialize;
 
-  StructType(const ID &id, const FieldVector &fields)
-      : Type(id), fields(fields) {}
+  StructType(const ID &id, const FieldVector &fields, bool reverse = true)
+      : Type(id), fields(fields), reverse(reverse) {}
 
   const FieldVector &getFields() const { return fields; }
   std::ptrdiff_t getBitWidth() const override {
@@ -153,18 +227,33 @@ public:
     return size;
   }
 
+  void ensureValid(const std::any &obj) const override;
+  MutableBitVector serialize(const std::any &obj) const override;
+  std::any deserialize(BitVector &data) const override;
+
+  // Returns whether this struct type should be reversed when
+  // serializing/deserializing.
+  // By default, a truthy value here makes StructType's compatible with system
+  // verilog, which has reversed struct field ordering, wrt. C/software struct
+  // ordering.
+  bool isReverse() const { return reverse; }
+
 private:
   FieldVector fields;
+  bool reverse;
 };
 
 /// 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) {}
+  ArrayType(const ID &id, const Type *elementType, uint64_t size,
+            bool reverse = true)
+      : Type(id), elementType(elementType), size(size), reverse(reverse) {}
+  using Type::deserialize;
 
   const Type *getElementType() const { return elementType; }
   uint64_t getSize() const { return size; }
+  bool isReverse() const { return reverse; }
   std::ptrdiff_t getBitWidth() const override {
     std::ptrdiff_t elementSize = elementType->getBitWidth();
     if (elementSize < 0)
@@ -172,9 +261,72 @@ public:
     return elementSize * size;
   }
 
+  void ensureValid(const std::any &obj) const override;
+  MutableBitVector serialize(const std::any &obj) const override;
+  std::any deserialize(BitVector &data) const override;
+
 private:
   const Type *elementType;
   uint64_t size;
+  // 'reverse' controls whether array elements are reversed during
+  // serialization/deserialization (to match SystemVerilog/Python ordering
+  // expectations).
+  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