esiaccel 0.0.17.dev447__cp310-cp310-win_amd64.whl → 0.1.5.dev406__cp310-cp310-win_amd64.whl

esiaccel/include/esi/Ports.h

@@ -25,6 +25,9 @@
 
 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 --
@@ -96,6 +99,24 @@ 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()
@@ -178,6 +199,27 @@ protected:
   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.
@@ -190,7 +232,7 @@ public:
   }
 
   /// Construct a port.
-  BundlePort(AppID id, std::map<std::string, ChannelPort &> channels);
+  BundlePort(AppID id, const BundleType *type, PortMap channels);
   virtual ~BundlePort() = default;
 
   /// Get the ID of the port.
@@ -202,9 +244,7 @@ public:
   /// ordinary users should not use. You have been warned.
   WriteChannelPort &getRawWrite(const std::string &name) const;
   ReadChannelPort &getRawRead(const std::string &name) const;
-  const std::map<std::string, ChannelPort &> &getChannels() const {
-    return channels;
-  }
+  const PortMap &getChannels() const { return channels; }
 
   /// Cast this Bundle port to a subclass which is actually useful. Returns
   /// nullptr if the cast fails.
@@ -224,9 +264,10 @@ public:
     return result;
   }
 
-private:
+protected:
   AppID id;
-  std::map<std::string, ChannelPort &> channels;
+  const BundleType *type;
+  PortMap channels;
 };
 
 } // namespace esi

esiaccel/include/esi/Services.h

@@ -25,9 +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
@@ -45,6 +57,7 @@ public:
 class Service {
 public:
   using Type = const std::type_info &;
+  Service(AcceleratorConnection &conn) : conn(conn) {}
   virtual ~Service() = default;
 
   virtual std::string getServiceSymbol() const = 0;
@@ -56,19 +69,21 @@ public:
   /// 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(AcceleratorConnection *conn,
-                                   Service::Type service, AppIDPath id = {},
+  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 ServicePort *getPort(AppIDPath id, const BundleType *type,
-                               const std::map<std::string, ChannelPort &> &,
-                               AcceleratorConnection &) const {
+  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
@@ -76,13 +91,16 @@ public:
 /// the ones in StdServices.h.
 class CustomService : public Service {
 public:
-  CustomService(AppIDPath idPath, const ServiceImplDetails &details,
+  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;
@@ -92,6 +110,7 @@ protected:
 /// Information about the Accelerator system.
 class SysInfo : public Service {
 public:
+  using Service::Service;
   virtual ~SysInfo() = default;
 
   virtual std::string getServiceSymbol() const override;
@@ -116,9 +135,8 @@ public:
     uint32_t size;
   };
 
-  MMIO(Context &ctxt, AppIDPath idPath, std::string implName,
-       const ServiceImplDetails &details, const HWClientDetails &clients);
-  MMIO() = default;
+  MMIO(AcceleratorConnection &, const AppIDPath &idPath,
+       const HWClientDetails &clients);
   virtual ~MMIO() = default;
 
   /// Read a 64-bit value from the global MMIO space.
@@ -133,8 +151,7 @@ public:
 
   /// If the service is a MMIO service, return a region of the MMIO space which
   /// peers into ours.
-  virtual Service *getChildService(AcceleratorConnection *conn,
-                                   Service::Type service, AppIDPath id = {},
+  virtual Service *getChildService(Service::Type service, AppIDPath id = {},
                                    std::string implName = {},
                                    ServiceImplDetails details = {},
                                    HWClientDetails clients = {}) override;
@@ -142,9 +159,8 @@ public:
   virtual std::string getServiceSymbol() const override;
 
   /// Get a MMIO region port for a particular region descriptor.
-  virtual ServicePort *getPort(AppIDPath id, const BundleType *type,
-                               const std::map<std::string, ChannelPort &> &,
-                               AcceleratorConnection &) const override;
+  virtual BundlePort *getPort(AppIDPath id,
+                              const BundleType *type) const override;
 
 private:
   /// MMIO base address table.
@@ -193,6 +209,9 @@ private:
 
 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;
 
@@ -200,9 +219,19 @@ public:
   /// 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.
@@ -234,39 +263,47 @@ public:
 /// Service for calling functions.
 class FuncService : public Service {
 public:
-  FuncService(AcceleratorConnection *acc, AppIDPath id,
-              const std::string &implName, ServiceImplDetails details,
+  FuncService(AppIDPath id, AcceleratorConnection &, ServiceImplDetails details,
               HWClientDetails clients);
 
   virtual std::string getServiceSymbol() const override;
-  virtual ServicePort *getPort(AppIDPath id, const BundleType *type,
-                               const std::map<std::string, ChannelPort &> &,
-                               AcceleratorConnection &) 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;
-    Function(AppID id, const std::map<std::string, ChannelPort &> &channels);
+    using ServicePort::ServicePort;
 
   public:
-    static Function *get(AppID id, WriteChannelPort &arg,
+    static Function *get(AppID id, BundleType *type, WriteChannelPort &arg,
                          ReadChannelPort &result);
 
     void connect();
     std::future<MessageData> call(const MessageData &arg);
 
+    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() const override {
-      const esi::Type *argType =
-          dynamic_cast<const ChannelType *>(arg.getType())->getInner();
-      const esi::Type *resultType =
-          dynamic_cast<const ChannelType *>(result.getType())->getInner();
+      const esi::Type *argType = getArgType();
+      const esi::Type *resultType = getResultType();
       return "function " + resultType->getID() + "(" + argType->getID() + ")";
     }
 
   private:
     std::mutex callMutex;
-    WriteChannelPort &arg;
-    ReadChannelPort &result;
+    WriteChannelPort *arg;
+    ReadChannelPort *result;
+    bool connected = false;
   };
 
 private:
@@ -276,23 +313,23 @@ private:
 /// Service for servicing function calls from the accelerator.
 class CallService : public Service {
 public:
-  CallService(AcceleratorConnection *acc, AppIDPath id, std::string implName,
-              ServiceImplDetails details, HWClientDetails clients);
+  CallService(AcceleratorConnection &acc, AppIDPath id,
+              ServiceImplDetails details);
 
   virtual std::string getServiceSymbol() const override;
-  virtual ServicePort *getPort(AppIDPath id, const BundleType *type,
-                               const std::map<std::string, ChannelPort &> &,
-                               AcceleratorConnection &) 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 std::map<std::string, ChannelPort &> &channels);
+    Callback(AcceleratorConnection &acc, AppID id, const BundleType *,
+             PortMap channels);
 
   public:
     static Callback *get(AcceleratorConnection &acc, AppID id,
-                         WriteChannelPort &result, ReadChannelPort &arg);
+                         const 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
@@ -301,17 +338,26 @@ public:
     void connect(std::function<MessageData(const MessageData &)> callback,
                  bool quick = false);
 
+    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() const override {
-      const esi::Type *argType =
-          dynamic_cast<const ChannelType *>(arg.getType())->getInner();
-      const esi::Type *resultType =
-          dynamic_cast<const ChannelType *>(result.getType())->getInner();
+      const esi::Type *argType = getArgType();
+      const esi::Type *resultType = getResultType();
       return "callback " + resultType->getID() + "(" + argType->getID() + ")";
     }
 
   private:
-    ReadChannelPort &arg;
-    WriteChannelPort &result;
+    ReadChannelPort *arg;
+    WriteChannelPort *result;
     AcceleratorConnection &acc;
   };
 
@@ -319,6 +365,63 @@ 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;
+  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 Metric : public ServicePort {
+    friend class TelemetryService;
+    Metric(AppID id, const BundleType *type, PortMap channels,
+           const TelemetryService *telemetryService,
+           std::optional<uint64_t> offset);
+
+  public:
+    void connect();
+    std::future<MessageData> read();
+    uint64_t readInt();
+
+    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:
+    const TelemetryService *telemetryService;
+    MMIO::MMIORegion *mmio;
+    std::optional<uint64_t> offset;
+  };
+
+  std::map<AppIDPath, Metric *> getTelemetryPorts() {
+    std::map<AppIDPath, Metric *> ports;
+    getTelemetryPorts(ports);
+    return ports;
+  }
+  void getTelemetryPorts(std::map<AppIDPath, Metric *> &ports);
+
+private:
+  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
 /// class if the backend doesn't do anything special with a service.
 class ServiceRegistry {

esiaccel/include/esi/Types.h

@@ -16,11 +16,18 @@
 #ifndef ESI_TYPES_H
 #define ESI_TYPES_H
 
-#include <map>
+#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,46 @@ 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();
+    }
+  }
+
 protected:
   ID id;
 };
@@ -54,6 +101,8 @@ 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;
+
 protected:
   ChannelVector channels;
 };
@@ -62,10 +111,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;
 };
@@ -73,9 +127,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
@@ -105,6 +164,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
@@ -118,21 +182,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 {
@@ -146,18 +221,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)
@@ -165,9 +255,17 @@ 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;
 };
 
 } // namespace esi