Common.h

Go to the documentation of this file.

//===- Common.h - Commonly used classes w/o dependencies --------*- 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_COMMON_H
#define ESI_COMMON_H
 
#include <any>
#include <cstdint>
#include <map>
#include <memory>
#include <optional>
#include <span>
#include <stdexcept>
#include <string>
#include <vector>
 
namespace esi {
class Type;
 
//===----------------------------------------------------------------------===//
// Common accelerator description types.
//===----------------------------------------------------------------------===//
 
struct AppID {
  std::string name;
  std::optional<uint32_t> idx;
 
  AppID(const std::string &name, std::optional<uint32_t> idx = std::nullopt)
      : name(name), idx(idx) {}
 
  bool operator==(const AppID &other) const {
    return name == other.name && idx == other.idx;
  }
  bool operator!=(const AppID &other) const { return !(*this == other); }
  friend std::ostream &operator<<(std::ostream &os, const AppID &id);
 
  std::string toString() const {
    if (idx.has_value())
      return name + "[" + std::to_string(idx.value()) + "]";
    return name;
  }
};
bool operator<(const AppID &a, const AppID &b);
 
class AppIDPath : public std::vector<AppID> {
public:
  using std::vector<AppID>::vector;
 
  AppIDPath operator+(const AppIDPath &b) const;
  AppIDPath parent() const;
  std::string toStr() const;
  friend std::ostream &operator<<(std::ostream &os, const AppIDPath &path);
};
bool operator<(const AppIDPath &a, const AppIDPath &b);
 
struct Constant {
  std::any value;
  std::optional<const Type *> type;
};
 
struct ModuleInfo {
  std::optional<std::string> name;
  std::optional<std::string> summary;
  std::optional<std::string> version;
  std::optional<std::string> repo;
  std::optional<std::string> commitHash;
  std::map<std::string, Constant> constants;
  std::map<std::string, std::any> extra;
};
 
/// A description of a service port. Used pretty exclusively in setting up the
/// design.
struct ServicePortDesc {
  std::string name;
  std::string portName;
};
 
/// Details about how to connect to a particular channel.
struct ChannelAssignment {
  /// The name of the type of connection. Typically, the name of the DMA engine
  /// or "cosim" if a cosimulation channel is being used.
  std::string type;
  /// Implementation-specific options.
  std::map<std::string, std::any> implOptions;
};
using ChannelAssignments = std::map<std::string, ChannelAssignment>;
 
/// A description of a hardware client. Used pretty exclusively in setting up
/// the design.
struct HWClientDetail {
  AppIDPath relPath;
  ServicePortDesc port;
  ChannelAssignments channelAssignments;
  std::map<std::string, std::any> implOptions;
};
using HWClientDetails = std::vector<HWClientDetail>;
using ServiceImplDetails = std::map<std::string, std::any>;
 
class MessageData;
namespace services {
struct HostMemRegion;
} // namespace services
 
//===----------------------------------------------------------------------===//
// SegmentedMessageData -- multi-segment message support.
//===----------------------------------------------------------------------===//
 
/// A contiguous, non-owning view of bytes within a SegmentedMessageData.
/// Valid only while the owning SegmentedMessageData is alive.
struct Segment {
  const uint8_t *data;
  size_t size;
  /// The HostMem region (from services::HostMem::allocate()) which holds
  /// [data, data + size), if any. Several segments may share a region.
  /// Non-owning: the SegmentedMessageData keeps the region alive; backends may
  /// be able to obtain ownership via SegmentedMessageData::take().
  services::HostMemRegion *region = nullptr;
 
  std::span<const uint8_t> span() const { return {data, size}; }
  bool empty() const { return size == 0; }
 
  /// Device address of this segment's bytes, if `region` is set and contains
  /// them; std::nullopt otherwise.
  std::optional<uint64_t> getDeviceAddress() const;
};
 
/// Abstract multi-segment message. Generated types subclass this to expose
/// header + list segments without flattening into a contiguous buffer.
///
/// MessageData is the canonical flat, one-segment implementation of this
/// interface. Other subclasses represent naturally segmented layouts.
///
/// Subclasses MUST own all data that their segments point to. Read and write
/// APIs can hold the message across async boundaries / retries. Subclasses
/// which hold data in HostMem regions must keep those regions alive for the
/// lifetime of the message (e.g. by owning them as unique_ptr<HostMemRegion>)
/// and point their segments' `region` at them. Subclasses which own their
/// regions exclusively may override take() to hand them to the backend.
class SegmentedMessageData {
public:
  virtual ~SegmentedMessageData() = default;
 
  /// Number of segments in the message.
  virtual size_t numSegments() const = 0;
  /// Get a segment by index. Throws if the segment has been take()n.
  virtual Segment segment(size_t idx) const = 0;
 
  /// Optionally called by a backend once it has transmitted segment `segIdx`,
  /// to obtain ownership of the HostMem region backing it (e.g. to re-use the
  /// region or return it to a pool).
  ///
  /// Returns nullptr, leaving the segment accessible, if the segment isn't
  /// backed by a region or the message doesn't transfer region ownership.
  /// Otherwise, marks the segment as taken -- after which segment(segIdx) (and
  /// thus anything which reads the whole message, such as toMessageData()) and
  /// further calls to take(segIdx) throw -- and returns the region if no other
  /// untaken segment references it, or nullptr if some still do. Since several
  /// segments may share a region, a backend which calls take() on each segment
  /// as it is transmitted receives each region exactly once, after the last
  /// segment using it.
  ///
  /// Since SegmentedMessageDataCursor reads segments via segment(), a backend
  /// must not take a segment which a cursor over the message can still reach,
  /// and must not take a segment it may need to retransmit. Any cursor
  /// (including one created after the take()) throws when it reaches a taken
  /// segment. Segment copies of a taken segment obtained before the take() are
  /// invalid: their `data` may point into a region which has been re-used.
  ///
  /// The default implementation returns nullptr.
  virtual std::unique_ptr<services::HostMemRegion> take(size_t segIdx);
 
  /// Total size across all segments.
  size_t totalSize() const;
  /// True if totalSize() == 0.
  bool empty() const;
 
  /// Flatten all segments into a standard MessageData.
  virtual MessageData toMessageData() const;
};
 
/// A concrete flat message backed by a single vector of bytes.
///
/// This is also a one-segment SegmentedMessageData so flat and segmented
/// messages can flow through the same internal APIs.
class MessageData : public SegmentedMessageData {
public:
  /// Adopts the data vector buffer.
  MessageData() = default;
  MessageData(std::span<const uint8_t> data)
      : data(data.data(), data.data() + data.size()) {}
  MessageData(std::vector<uint8_t> &data) : data(std::move(data)) {}
  MessageData(std::vector<uint8_t> &&data) : data(std::move(data)) {}
  MessageData(const uint8_t *data, size_t size) : data(data, data + size) {}
  ~MessageData() = default;
 
  const uint8_t *getBytes() const { return data.data(); }
 
  /// Get the data as a vector of bytes.
  const std::vector<uint8_t> &getData() const { return data; }
 
  /// Implicit conversion to a vector/span of bytes, to play nice with other
  /// APIs that accept bytearray-like things.
  operator const std::vector<uint8_t> &() const { return data; }
  operator std::span<const uint8_t>() const { return data; }
 
  /// Move the data out of this object.
  std::vector<uint8_t> takeData() { return std::move(data); }
 
  /// Get the size of the data in bytes.
  size_t getSize() const { return data.size(); }
  size_t size() const { return getSize(); }
 
  /// Returns true if this message contains no data.
  bool empty() const { return data.empty(); }
 
  /// Cast to a type. Throws if the size of the data does not match the size of
  /// the message. The lifetime of the resulting pointer is tied to the lifetime
  /// of this object.
  template <typename T>
  const T *as() const {
    if (data.size() != sizeof(T))
      throw std::runtime_error("Data size does not match type size. Size is " +
                               std::to_string(data.size()) + ", expected " +
                               std::to_string(sizeof(T)) + ".");
    return reinterpret_cast<const T *>(data.data());
  }
 
  /// Cast from a type to its raw bytes.
  template <typename T>
  static MessageData from(T &t) {
    return MessageData(reinterpret_cast<const uint8_t *>(&t), sizeof(T));
  }
 
  /// Convert the data to a hex string.
  std::string toHex() const;
 
  size_t numSegments() const override { return 1; }
  Segment segment(size_t idx) const override {
    if (idx != 0)
      throw std::out_of_range("MessageData only has one segment");
    return {data.data(), data.size()};
  }
  MessageData toMessageData() const override { return *this; }
 
private:
  std::vector<uint8_t> data;
};
 
/// Cursor for incremental consumption of a SegmentedMessageData.
/// Tracks position across segment boundaries. Backends store this alongside
/// a unique_ptr<SegmentedMessageData> for partial writes.
///
/// The cursor reads segments through SegmentedMessageData::segment() on every
/// access and caches nothing, so it throws upon reaching a segment which has
/// been take()n -- regardless of whether it was created before or after the
/// take().
///
/// Deliberately a separate class (not embedded in SegmentedMessageData) so
/// that generated types have no hidden members — their layout matches the
/// hardware wire format exactly.
class SegmentedMessageDataCursor {
public:
  SegmentedMessageDataCursor(const SegmentedMessageData &msg) : msg(msg) {}
 
  /// Contiguous span from current position to end of current segment.
  std::span<const uint8_t> remaining() const;
 
  /// The unconsumed part of the current segment, with its `region`. `data` and
  /// `size` match remaining().
  Segment remainingSegment() const;
 
  /// Advance by `n` bytes, crossing segment boundaries as needed.
  void advance(size_t n);
 
  /// True when all segments have been consumed.
  bool done() const;
 
private:
  const SegmentedMessageData &msg;
  size_t segIdx = 0;
  size_t offset = 0;
};
 
} // namespace esi
 
std::ostream &operator<<(std::ostream &, const esi::ModuleInfo &);
 
//===----------------------------------------------------------------------===//
// Functions which should be in the standard library.
//===----------------------------------------------------------------------===//
 
namespace esi {
std::string toHex(void *val);
std::string toHex(uint64_t val);
} // namespace esi
 
#endif // ESI_COMMON_H