CIRCT 24.0.0git
Loading...
Searching...
No Matches
esi Namespace Reference

Namespaces

namespace  registry
namespace  backends
namespace  cosim
namespace  detail
namespace  services
namespace  utils

Classes

class  ChannelSignaling
class  RequestConnectionOp
class  RandomAccessMemoryDeclOp
class  ESIPureModuleOp
class  Accelerator
 Top level accelerator class. More...
class  AcceleratorConnection
 Abstract class representing a connection to an accelerator. More...
class  AcceleratorServiceThread
 Background thread which services various requests. More...
class  CliParser
 Common options and code for ESI runtime tools. More...
struct  AppID
class  AppIDPath
struct  Constant
struct  ModuleInfo
struct  ServicePortDesc
 A description of a service port. More...
struct  ChannelAssignment
 Details about how to connect to a particular channel. More...
struct  HWClientDetail
 A description of a hardware client. More...
struct  Segment
 A contiguous, non-owning view of bytes within a SegmentedMessageData. More...
class  SegmentedMessageData
 Abstract multi-segment message. More...
class  MessageData
 A concrete flat message backed by a single vector of bytes. More...
class  SegmentedMessageDataCursor
 Cursor for incremental consumption of a SegmentedMessageData. More...
class  Context
 AcceleratorConnections, Accelerators, and Manifests must all share a context. More...
class  HWModule
 Represents either the top level or an instance of a hardware module. More...
class  Instance
 Subclass of HWModule which represents a submodule instance. More...
class  Engine
 Engines implement the actual channel communication between the host and the accelerator. More...
class  BundleEngineMap
 Since engines can support multiple channels BUT not necessarily all of the channels in a bundle, a mapping from bundle channels to engines is needed. More...
class  Logger
class  TSLogger
 A thread-safe logger which calls functions implemented by subclasses. More...
class  StreamLogger
 A logger that writes to a C++ std::ostream. More...
class  ConsoleLogger
 A logger that writes to the console. Includes color support. More...
class  NullLogger
 A logger that does nothing. More...
class  Manifest
 Class to parse a manifest. More...
class  ChannelPort
 Unidirectional channels are the basic communication primitive between the host and accelerator. More...
class  WriteChannelPort
 A ChannelPort which sends data to the accelerator. More...
class  UnknownWriteChannelPort
 Instantiated when a backend does not know how to create a write channel. More...
class  ReadChannelPort
 A ChannelPort which reads data from the accelerator. More...
class  UnknownReadChannelPort
 Instantiated when a backend does not know how to create a read channel. More...
class  BundlePort
 Services provide connections to 'bundles' – collections of named, unidirectional communication channels. More...
class  AcceleratorMismatchError
struct  WireInfo
 Compute the wire byte count for a port type. More...
class  QueuedDecodeTypeDeserializer
 Helper base class for stateful deserializers which may emit zero, one, or many typed outputs for each raw input message. More...
class  SerialListTypeDeserializer
 Reusable serial-list window deserializer. More...
struct  has_esi_id
struct  has_esi_id< T, std::void_t< decltype(T::_ESI_ID)> >
struct  has_esi_window_id
struct  has_esi_window_id< T, std::void_t< decltype(T::_ESI_WINDOW_ID)> >
struct  is_std_array
struct  is_std_array< std::array< T, N > >
class  TypedWritePort
class  TypedWritePort< void >
 Specialization for void — write takes no data argument. More...
class  TypedReadPort
 Strongly typed wrapper around a raw read channel. More...
class  TypedReadPort< void >
 Specialization for void — read discards data and returns nothing. More...
class  TypedFunction
class  TypedFunction< void, ResultT, SkipTypeCheck >
 Partial specialization: void argument, typed result. More...
class  TypedFunction< ArgT, void, SkipTypeCheck >
 Partial specialization: typed argument, void result. More...
class  TypedFunction< void, void, SkipTypeCheck >
 Full specialization: void argument, void result. More...
class  TypedCallback
class  TypedCallback< void, ResultT, SkipTypeCheck >
 Partial specialization: void argument, typed result. More...
class  TypedCallback< ArgT, void, SkipTypeCheck >
 Partial specialization: typed argument, void result. More...
class  TypedCallback< void, void, SkipTypeCheck >
 Full specialization: void argument, void result. More...
class  IndexedPorts
class  Type
 Root class of the ESI type system. More...
class  BundleType
 Bundles represent a collection of channels. More...
class  ChannelType
 Channels are the basic communication primitives. More...
class  VoidType
 The "void" type is a special type which can be used to represent no type. More...
class  AnyType
 The "any" type is a special type which can be used to represent any type, as identified by the type id. More...
class  TypeAliasType
 Type aliases provide a named type which forwards to an inner type. More...
class  BitVectorType
 Bit vectors include signed, unsigned, and signless integers. More...
class  BitsType
 Bits are just an array of bits. More...
class  IntegerType
 Integers are bit vectors which may be signed or unsigned and are interpreted as numbers. More...
class  SIntType
 Signed integer. More...
class  UIntType
 Unsigned integer. More...
class  StructType
 Structs are an ordered collection of fields, each with a name and a type. More...
class  ArrayType
 Arrays have a compile time specified (static) size and an element type. More...
class  WindowType
 Windows represent a fixed-size sliding window over a stream of data. More...
class  UnionType
 Unions contain one active field without storing a tag. More...
class  ListType
 Lists represent variable-length sequences of elements of a single type. More...
class  BitVector
 A lightweight, non-owning bit vector view backed by a byte array span. More...
class  UIntView
 Non-owning view of an unsigned bit vector with toUI64() and implicit conversions to unsigned scalar types. More...
class  IntView
 Non-owning view of a signed bit vector with toI64() and implicit conversions to signed scalar types. More...
class  MutableBitVector
 A mutable bit vector that owns its underlying storage. More...
class  Int
class  UInt

Typedefs

using ChannelAssignments = std::map<std::string, ChannelAssignment>
using HWClientDetails = std::vector<HWClientDetail>
using ServiceImplDetails = std::map<std::string, std::any>
using PortMap = std::map<std::string, ChannelPort &>
using ServiceTable = std::map<std::string, services::Service *>

Functions

bool operator< (const AppID &a, const AppID &b)
bool operator< (const AppIDPath &a, const AppIDPath &b)
std::string toHex (void *val)
std::string toHex (uint64_t val)
std::string toString (const std::any &a)
 'Stringify' a std::any. This is used to log std::any values by some loggers.
WireInfo getWireInfo (const Type *portType)
template<typename T>
MessageData toMessageData (const T &data, WireInfo wi)
 Pack a C++ integral value into a MessageData with the given wire byte count.
template<typename T>
MessageData toMessageData (const T &data, const Type *portType)
template<typename T>
T fromMessageData (const MessageData &msg, WireInfo wi)
 Unpack a MessageData into a C++ integral value with the given wire info.
template<typename T>
T fromMessageData (const MessageData &msg, const Type *portType)
template<typename T>
void verifyTypeCompatibility (const Type *portType)
template<typename T>
void verifyTypeCompatibility (const ChannelPort *port)
BundlePort & findPortOrThrow (HWModule *module, const AppID &id)
 Look up a BundlePort by AppID in module.
template<typename T>
T * findPortAsOrThrow (HWModule *module, const AppID &id)
 Look up a BundlePort by AppID and cast it to T.
std::vector< uint32_t > findPortIndices (HWModule *module, const std::string &name)
 Return a sorted vector of the idx values for every port whose AppID name matches name.
const Type * unwrapTypeAlias (const Type *type)
 Unwrap TypeAliasType (possibly recursively) to get the underlying type.
template<typename T>
const T * getUnwrappedAs (const Type *type)
 Unwrap aliases and channels, then cast the payload to T.
std::ostream & operator<< (std::ostream &os, const BitVector &bv)
static std::filesystem::path getExePath ()
 Get the path to the currently running executable.
static std::filesystem::path getLibPath ()
 Get the path to the currently running shared library.
static std::vector< std::filesystem::path > getESIBackendDirectories ()
 Get the list of directories to search for backend plugins.
static void loadBackend (Context &ctxt, std::string backend)
 Load a backend plugin dynamically.
static std::map< AppID, Instance * > buildIndex (const std::vector< std::unique_ptr< Instance > > &insts)
 Build an index of children by AppID.
static std::map< AppID, BundlePort & > buildIndex (const std::vector< std::unique_ptr< BundlePort > > &ports)
 Build an index of ports by AppID.
std::ostream & operator<< (std::ostream &os, const AppID &id)
std::ostream & operator<< (std::ostream &os, const AppIDPath &path)
static void dumpType (std::ostream &os, const esi::Type *type, int level=0, bool oneLine=false)
static Int getIntLikeFromAny (const std::any &obj, unsigned widthHint)
static UInt getUIntLikeFromAny (const std::any &obj, unsigned widthHint)

Variables

constexpr uint32_t MetadataOffset = 8
constexpr uint64_t MagicNumberLo = 0xE5100E51
constexpr uint64_t MagicNumberHi = 0x207D98E5
constexpr uint64_t MagicNumber = MagicNumberLo | (MagicNumberHi << 32)
constexpr uint64_t MagicNumberOffset = 0
constexpr uint32_t ExpectedVersionNumber = 1
 Keep in sync with circt::esi::esiApiVersion and the PyCDE BSP.
constexpr uint64_t VersionNumberOffset = 8
constexpr uint32_t ManifestPtrOffset = 0x10
constexpr uint32_t CycleCountOffset = 0x20
constexpr uint32_t CoreFreqOffset = 0x28
constexpr uint64_t ResetMagicNumber = 0x00000E510000B007
 Magic value which, when written to MMIO offset ResetRequestOffset, requests a design reset.
constexpr uint32_t ResetRequestOffset = 0x38
 Offset into the (global) MMIO space at which to request a design reset.
template<typename T>
constexpr bool has_esi_id_v = has_esi_id<T>::value
template<typename T>
constexpr bool has_esi_window_id_v = has_esi_window_id<T>::value
template<typename T>
constexpr bool is_std_array_v = is_std_array<T>::value

Typedef Documentation

◆ ChannelAssignments

using esi.ChannelAssignments = std::map<std::string, ChannelAssignment>

Definition at line 98 of file Common.h.

◆ HWClientDetails

using esi.HWClientDetails = std::vector<HWClientDetail>

Definition at line 108 of file Common.h.

◆ PortMap

using esi.PortMap = std::map<std::string, ChannelPort &>

Definition at line 33 of file Ports.h.

◆ ServiceImplDetails

using esi.ServiceImplDetails = std::map<std::string, std::any>

Definition at line 109 of file Common.h.

◆ ServiceTable

using esi.ServiceTable = std::map<std::string, services::Service *>

Definition at line 41 of file Services.h.

Function Documentation

◆ buildIndex() [1/2]

std::map< AppID, BundlePort & > esi::buildIndex ( const std::vector< std::unique_ptr< BundlePort > > & ports)
static

Build an index of ports by AppID.

Definition at line 35 of file Design.cpp.

◆ buildIndex() [2/2]

std::map< AppID, Instance * > esi::buildIndex ( const std::vector< std::unique_ptr< Instance > > & insts)
static

Build an index of children by AppID.

Definition at line 26 of file Design.cpp.

Referenced by esi::HWModule::HWModule().

◆ dumpType()

void esi::dumpType ( std::ostream & os,
const esi::Type * type,
int level = 0,
bool oneLine = false )
static

Definition at line 26 of file Types.cpp.

References dumpType(), esi::Type::getID(), and esi::BundleType::To.

Referenced by esi::Type::dump(), and dumpType().

◆ findPortAsOrThrow()

template<typename T>
T * esi::findPortAsOrThrow ( HWModule * module,
const AppID & id )

Look up a BundlePort by AppID and cast it to T.

Throws AcceleratorMismatchError if the port is missing or has the wrong runtime type. The returned pointer is mutable.

Definition at line 1504 of file TypedPorts.h.

References findPortOrThrow(), esi::BundlePort::getAs(), and toString().

◆ findPortIndices()

std::vector< uint32_t > esi::findPortIndices ( HWModule * module,
const std::string & name )
inline

Return a sorted vector of the idx values for every port whose AppID name matches name.

Ports without an index are ignored.

Definition at line 1516 of file TypedPorts.h.

References esi::HWModule::getPorts().

◆ findPortOrThrow()

BundlePort & esi::findPortOrThrow ( HWModule * module,
const AppID & id )
inline

Look up a BundlePort by AppID in module.

Throws AcceleratorMismatchError if the port is not found. The returned reference is mutable: even though HWModule::resolvePort is a const method, the underlying port map stores BundlePort& references, so callers can invoke non-const methods on the returned port (e.g. getRawRead, connect).

Definition at line 1491 of file TypedPorts.h.

References toString().

Referenced by findPortAsOrThrow().

◆ fromMessageData() [1/2]

template<typename T>
T esi::fromMessageData ( const MessageData & msg,
const Type * portType )

Definition at line 128 of file TypedPorts.h.

References fromMessageData(), and getWireInfo().

◆ fromMessageData() [2/2]

template<typename T>
T esi::fromMessageData ( const MessageData & msg,
WireInfo wi )

Unpack a MessageData into a C++ integral value with the given wire info.

If the wire size differs from sizeof(T), copies available bytes into a zero-initialized value and sign-extends for signed types using the actual bit width to locate the sign bit.

Definition at line 103 of file TypedPorts.h.

References esi::MessageData::as(), esi::WireInfo::bitWidth, esi::WireInfo::bytes, esi::MessageData::getBytes(), and esi::MessageData::getSize().

Referenced by fromMessageData(), and esi::detail::PODTypeDeserializer< T >::push().

◆ getESIBackendDirectories()

std::vector< std::filesystem::path > esi::getESIBackendDirectories ( )
static

Get the list of directories to search for backend plugins.

Definition at line 178 of file Accelerator.cpp.

References getExePath(), and getLibPath().

Referenced by loadBackend().

◆ getExePath()

std::filesystem::path esi::getExePath ( )
static

Get the path to the currently running executable.

Definition at line 133 of file Accelerator.cpp.

Referenced by getESIBackendDirectories().

◆ getIntLikeFromAny()

Int esi::getIntLikeFromAny ( const std::any & obj,
unsigned widthHint )
static

Definition at line 226 of file Types.cpp.

Referenced by esi::SIntType::ensureValid(), and esi::SIntType::serialize().

◆ getLibPath()

std::filesystem::path esi::getLibPath ( )
static

Get the path to the currently running shared library.

Definition at line 152 of file Accelerator.cpp.

References getLibPath().

Referenced by getESIBackendDirectories(), and getLibPath().

◆ getUIntLikeFromAny()

UInt esi::getUIntLikeFromAny ( const std::any & obj,
unsigned widthHint )
static

Definition at line 245 of file Types.cpp.

Referenced by esi::UIntType::ensureValid(), and esi::UIntType::serialize().

◆ getUnwrappedAs()

template<typename T>
const T * esi::getUnwrappedAs ( const Type * type)

Unwrap aliases and channels, then cast the payload to T.

Returns nullptr for a null input or a payload that is not a T. Other containers are retained.

Definition at line 203 of file Types.h.

References unwrapTypeAlias().

◆ getWireInfo()

WireInfo esi::getWireInfo ( const Type * portType)
inline

◆ loadBackend()

void esi::loadBackend ( Context & ctxt,
std::string backend )
static

Load a backend plugin dynamically.

Plugins are expected to be named lib<BackendName>Backend.so and located in one of 1) CWD, 2) directories specified in ESI_BACKENDS environment variable, 3) in the same directory as the application, or 4) in the same directory as this library.

Definition at line 215 of file Accelerator.cpp.

References esi::Logger::debug(), esi::Logger::error(), found, getESIBackendDirectories(), esi::Context::getLogger(), and esi::Logger::info().

Referenced by esi::Context::connect().

◆ operator<() [1/2]

bool esi::operator< ( const AppID & a,
const AppID & b )

Definition at line 822 of file Manifest.cpp.

References esi::AppID::idx, esi::AppID::name, and operator<().

Referenced by operator<(), and operator<().

◆ operator<() [2/2]

bool esi::operator< ( const AppIDPath & a,
const AppIDPath & b )

Definition at line 827 of file Manifest.cpp.

References operator<().

◆ operator<<() [1/3]

std::ostream & esi::operator<< ( std::ostream & os,
const AppID & id )

Definition at line 836 of file Manifest.cpp.

◆ operator<<() [2/3]

std::ostream & esi::operator<< ( std::ostream & os,
const AppIDPath & path )

Definition at line 842 of file Manifest.cpp.

◆ operator<<() [3/3]

std::ostream & esi::operator<< ( std::ostream & os,
const BitVector & bv )

Definition at line 386 of file Values.cpp.

References toDecimalString(), toPowerOfTwoString(), and esi::BitVector::toString().

◆ toHex() [1/2]

std::string esi::toHex ( uint64_t val)

Definition at line 42 of file Common.cpp.

◆ toHex() [2/2]

◆ toMessageData() [1/2]

template<typename T>
MessageData esi::toMessageData ( const T & data,
const Type * portType )

Definition at line 94 of file TypedPorts.h.

References getWireInfo(), and toMessageData().

◆ toMessageData() [2/2]

template<typename T>
MessageData esi::toMessageData ( const T & data,
WireInfo wi )

Pack a C++ integral value into a MessageData with the given wire byte count.

If wi.bytes is 0, falls back to sizeof(T).

Definition at line 80 of file TypedPorts.h.

References esi::WireInfo::bytes.

Referenced by toMessageData(), esi::TypedWritePort< T, SkipTypeCheck >::tryWrite(), and esi::TypedWritePort< T, SkipTypeCheck >::write().

◆ toString()

std::string esi::toString ( const std::any & a)

'Stringify' a std::any. This is used to log std::any values by some loggers.

Definition at line 132 of file Logging.cpp.

Referenced by esi::services::TelemetryService::Metric::connect(), dmaWriteTest(), findPortAsOrThrow(), findPortOrThrow(), esi::ConsoleLogger::logImpl(), and esi::StreamLogger::logImpl().

◆ unwrapTypeAlias()

const Type * esi::unwrapTypeAlias ( const Type * type)
inline

Unwrap TypeAliasType (possibly recursively) to get the underlying type.

Definition at line 193 of file Types.h.

Referenced by getUnwrappedAs(), getWireInfo(), and verifyTypeCompatibility().

◆ verifyTypeCompatibility() [1/2]

template<typename T>
void esi::verifyTypeCompatibility ( const ChannelPort * port)

◆ verifyTypeCompatibility() [2/2]

Variable Documentation

◆ CoreFreqOffset

uint32_t esi.CoreFreqOffset = 0x28
constexpr

Definition at line 67 of file Accelerator.h.

Referenced by esi::services::MMIOSysInfo::getCoreClockFrequency().

◆ CycleCountOffset

uint32_t esi.CycleCountOffset = 0x20
constexpr

Definition at line 66 of file Accelerator.h.

Referenced by esi::services::MMIOSysInfo::getCycleCount().

◆ ExpectedVersionNumber

uint32_t esi.ExpectedVersionNumber = 1
constexpr

Keep in sync with circt::esi::esiApiVersion and the PyCDE BSP.

Definition at line 61 of file Accelerator.h.

Referenced by esi::services::MMIOSysInfo::getCompressedManifest().

◆ has_esi_id_v

template<typename T>
bool esi.has_esi_id_v = has_esi_id<T>::value
inlineconstexpr

◆ has_esi_window_id_v

template<typename T>
bool esi.has_esi_window_id_v = has_esi_window_id<T>::value
inlineconstexpr

Definition at line 437 of file TypedPorts.h.

Referenced by verifyTypeCompatibility(), and verifyTypeCompatibility().

◆ is_std_array_v

template<typename T>
bool esi.is_std_array_v = is_std_array<T>::value
inlineconstexpr

Definition at line 453 of file TypedPorts.h.

Referenced by verifyTypeCompatibility().

◆ MagicNumber

uint64_t esi.MagicNumber = MagicNumberLo | (MagicNumberHi << 32)
constexpr

Definition at line 57 of file Accelerator.h.

Referenced by esi::services::MMIOSysInfo::getEsiVersion().

◆ MagicNumberHi

uint64_t esi.MagicNumberHi = 0x207D98E5
constexpr

Definition at line 56 of file Accelerator.h.

◆ MagicNumberLo

uint64_t esi.MagicNumberLo = 0xE5100E51
constexpr

Definition at line 55 of file Accelerator.h.

◆ MagicNumberOffset

uint64_t esi.MagicNumberOffset = 0
constexpr

Definition at line 58 of file Accelerator.h.

Referenced by esi::services::MMIOSysInfo::getEsiVersion().

◆ ManifestPtrOffset

uint32_t esi.ManifestPtrOffset = 0x10
constexpr

Definition at line 64 of file Accelerator.h.

Referenced by esi::services::MMIOSysInfo::getCompressedManifest().

◆ MetadataOffset

◆ ResetMagicNumber

uint64_t esi.ResetMagicNumber = 0x00000E510000B007
constexpr

Magic value which, when written to MMIO offset ResetRequestOffset, requests a design reset.

Keep in sync with 'ResetMagicNumber' in the PyCDE BSP (python/esiaccel/bsp/common.py).

Definition at line 72 of file Accelerator.h.

Referenced by esi::AcceleratorConnection::reset().

◆ ResetRequestOffset

uint32_t esi.ResetRequestOffset = 0x38
constexpr

Offset into the (global) MMIO space at which to request a design reset.

Definition at line 74 of file Accelerator.h.

Referenced by esi::AcceleratorConnection::reset().

◆ VersionNumberOffset

uint64_t esi.VersionNumberOffset = 8
constexpr

Definition at line 62 of file Accelerator.h.

Referenced by esi::services::MMIOSysInfo::getEsiVersion().