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 <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>;
 
/// A logical chunk of data representing serialized data. Currently, just a
/// wrapper for a vector of bytes, which is not efficient in terms of memory
/// copying. This will change in the future as will the API.
class MessageData {
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;
 
private:
  std::vector<uint8_t> data;
};
 
//===----------------------------------------------------------------------===//
// SegmentedMessageData — multi-segment message for generated types.
//===----------------------------------------------------------------------===//
 
/// 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;
  std::span<const uint8_t> span() const { return {data, size}; }
  bool empty() const { return size == 0; }
};
 
/// Abstract multi-segment message. Generated types subclass this to expose
/// header + list segments without flattening into a contiguous buffer.
///
/// This class does NOT replace MessageData. It lives alongside it.
///
/// Subclasses MUST own all data that their segments point to. The write API
/// takes ownership (unique_ptr<SegmentedMessageData>) and a backend may hold
/// the message across async boundaries / partial writes.
class SegmentedMessageData {
public:
  virtual ~SegmentedMessageData() = default;
 
  /// Number of segments in the message.
  virtual size_t numSegments() const = 0;
  /// Get a segment by index.
  virtual Segment segment(size_t idx) const = 0;
 
  /// Total size across all segments.
  size_t totalSize() const;
  /// True if totalSize() == 0.
  bool empty() const;
 
  /// Flatten all segments into a standard MessageData.
  MessageData toMessageData() const;
};
 
/// Cursor for incremental consumption of a SegmentedMessageData.
/// Tracks position across segment boundaries. Backends store this alongside
/// a unique_ptr<SegmentedMessageData> for partial writes.
///
/// 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;
 
  /// Advance by `n` bytes, crossing segment boundaries as needed.
  void advance(size_t n);
 
  /// True when all segments have been consumed.
  bool done() const;
 
  /// Reset to the beginning.
  void reset();
 
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