A ChannelPort which reads data from the accelerator. More...

#include <Ports.h>

Inheritance diagram for esi::ReadChannelPort:

[legend]

Collaboration diagram for esi::ReadChannelPort:

[legend]

Public Types
using	ReadCallback = std::function< bool(std::unique_ptr< SegmentedMessageData > &)>
	Primary callback API for raw reads.

using	FlatReadCallback = std::function< bool(MessageData)>
	Compatibility callback API for callers which want flattened message bytes instead of the owning segmented message object.

Public Member Functions
	ReadChannelPort (const Type *type)

virtual void	disconnect () override
	Disconnect the channel.

virtual bool	isConnected () const override

virtual void	connect (ReadCallback callback, const ConnectOptions &options={})

virtual void	connect (FlatReadCallback callback, const ConnectOptions &options={})
	Connect a compatibility callback which receives flattened `MessageData` objects.

virtual void	connect (const ConnectOptions &options={}) override
	Connect to the channel in polling mode.

virtual std::future< MessageData >	readAsync ()
	Asynchronous polling read.

virtual void	read (MessageData &outData)
	Specify a buffer to read into.

void	setMaxDataQueueMsgs (uint64_t maxMsgs)
	Set maximum number of messages to store in the dataQueue.

Public Member Functions inherited from esi::ChannelPort
	ChannelPort (const Type *type)

virtual	~ChannelPort ()

bool	poll ()
	Poll for incoming data.

size_t	getFrameSizeBytes () const
	Get the size of each frame in bytes.

const Type *	getType () const

const WindowType *	getWindowType () const
	If this port carries a windowed type, return the original WindowType (whose `intoType` is what `getType()` returns).

Static Public Attributes
static constexpr uint64_t	DefaultMaxDataQueueMsgs = 32
	Default max data queue size set at connect time.

Protected Types
enum	Mode { Disconnected , Callback , Polling }
	Indicates the current mode of the channel. More...

Protected Member Functions
bool	invokeCallback (std::unique_ptr< SegmentedMessageData > &msg)
	Invoke the currently registered callback.

void	resetTranslationState ()
	Reset translation state buffers and indices.

bool	translateIncoming (MessageData &data)
	Translate incoming data if the port type is a window type.

Protected Member Functions inherited from esi::ChannelPort
virtual bool	pollImpl ()
	Method called by poll() to actually poll the channel if the channel is connected.

virtual void	connectImpl (const ConnectOptions &options)
	Called by all connect methods to let backends initiate the underlying connections.

Protected Attributes
volatile Mode	mode

std::unique_ptr< SegmentedMessageData >	translatedMessage
	If a translated message has been assembled but not yet consumed, retain ownership here so retries present the same message object.

std::vector< uint8_t >	translationBuffer
	Window translation support.

size_t	nextFrameIndex = 0
	Index of the next expected frame (for multi-frame windows).

std::vector< uint8_t >	listDataBuffer
	For list fields: accumulated list data across frames.

bool	accumulatingListData = false
	Flag to track whether we're in the middle of accumulating list data.

uint64_t	maxDataQueueMsgs = DefaultMaxDataQueueMsgs

std::optional< detail::PollingBuffer< MessageData > >	pollingState

std::mutex	callbackMutex
	Synchronizes callback revocation during disconnect.

std::condition_variable	callbackCv

size_t	activeCallbacks = 0

Protected Attributes inherited from esi::ChannelPort
const Type *	type

std::unique_ptr< TranslationInfo >	translationInfo

Private Attributes
ReadCallback	callback
	Backends should not call this directly.

Detailed Description

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() again. When the port is disconnected, it will backpressure hardware.

Definition at line 453 of file Ports.h.

Member Typedef Documentation

◆ FlatReadCallback

using esi::ReadChannelPort::FlatReadCallback = std::function<bool(MessageData)>

Compatibility callback API for callers which want flattened message bytes instead of the owning segmented message object.

Definition at line 466 of file Ports.h.

◆ ReadCallback

using esi::ReadChannelPort::ReadCallback = std::function<bool(std::unique_ptr<SegmentedMessageData> &)>

Primary callback API for raw reads.

The message is passed by owning reference so the callee can consume it, move storage out of it, or leave it intact when returning false to request a retry with the same message object.

Definition at line 461 of file Ports.h.

Member Enumeration Documentation

◆ Mode

enum esi::ReadChannelPort::Mode

protected

Indicates the current mode of the channel.

Enumerator
Disconnected
Callback
Polling

Definition at line 549 of file Ports.h.

Constructor & Destructor Documentation

◆ ReadChannelPort()

esi::ReadChannelPort::ReadChannelPort ( const Type * type )

inline

Definition at line 468 of file Ports.h.

Member Function Documentation

◆ connect() [1/3]

void ReadChannelPort::connect ( const ConnectOptions & options = {} )

overridevirtual

Connect to the channel in polling mode.

Implements esi::ChannelPort.

Reimplemented in esi::UnknownReadChannelPort.

Definition at line 183 of file Ports.cpp.

References esi::ChannelPort::ConnectOptions::bufferSize, callback, esi::ChannelPort::connectImpl(), Disconnected, maxDataQueueMsgs, mode, Polling, pollingState, resetTranslationState(), esi::MessageData::toMessageData(), translatedMessage, translateIncoming(), esi::ChannelPort::ConnectOptions::translateMessage, translationBuffer, and esi::ChannelPort::translationInfo.

◆ connect() [2/3]

void ReadChannelPort::connect	(	FlatReadCallback	callback,
		const ConnectOptions &	options = `{}`
	)

virtual

Connect a compatibility callback which receives flattened MessageData objects.

This adapts the primary segmented callback path.

Reimplemented in esi::UnknownReadChannelPort.

Definition at line 175 of file Ports.cpp.

References callback, and connect().

◆ connect() [3/3]

void ReadChannelPort::connect	(	ReadCallback	callback,
		const ConnectOptions &	options = `{}`
	)

virtual

Reimplemented in esi::UnknownReadChannelPort.

Definition at line 140 of file Ports.cpp.

References callback, Callback, esi::ChannelPort::connectImpl(), Disconnected, mode, resetTranslationState(), translatedMessage, translateIncoming(), esi::ChannelPort::ConnectOptions::translateMessage, translationBuffer, and esi::ChannelPort::translationInfo.

Referenced by autoSerialCoordTranslateTest(), bandwidthReadTest(), connect(), dmaReadTest(), runLoopbackI8(), serialCoordTranslateTest(), serialCoordTranslateTest(), streamingAddTest(), streamingAddTranslatedTest(), and sv2cCosimserverEpRegister().

◆ disconnect()

void ReadChannelPort::disconnect ( )

overridevirtual

Disconnect the channel.

Warning: this method may block until all callbacks have returned. Do not call it anywhere which could be in a callback control path otherwise deadlock will occur.

Implements esi::ChannelPort.

Definition at line 70 of file Ports.cpp.

References activeCallbacks, callback, callbackCv, callbackMutex, Disconnected, mode, pollingState, and resetTranslationState().

Referenced by autoSerialCoordTranslateTest(), esi::TypedReadPort< T, SkipTypeCheck >::disconnect(), esi::TypedReadPort< void >::disconnect(), dmaReadTest(), serialCoordTranslateTest(), streamingAddTest(), and streamingAddTranslatedTest().

◆ invokeCallback()

bool ReadChannelPort::invokeCallback ( std::unique_ptr< SegmentedMessageData > & msg )

protected

Invoke the currently registered callback.

Handles synchronization race conditions with disconnects. Backends should use this helper instead of calling callback directly.

Definition at line 87 of file Ports.cpp.

References activeCallbacks, assert(), callback, callbackCv, callbackMutex, Disconnected, and mode.

◆ isConnected()

virtual bool esi::ReadChannelPort::isConnected ( ) const

inlineoverridevirtual

Implements esi::ChannelPort.

Definition at line 475 of file Ports.h.

References Disconnected, and mode.

Referenced by esi::TypedReadPort< T, SkipTypeCheck >::isConnected(), esi::TypedReadPort< void >::isConnected(), and esi::TypedReadPort< void >::~TypedReadPort().

◆ read()

virtual void esi::ReadChannelPort::read ( MessageData & outData )

inlinevirtual

Specify a buffer to read into.

Blocking. Basic API, will likely change for performance and functionality reasons.

Definition at line 517 of file Ports.h.

References readAsync().

Referenced by autoSerialCoordTranslateTest(), bandwidthReadTest(), esiaccel.bsp.common.ESI_Manifest_ROM_Wrapper::build(), dmaReadTest(), esi::TypedReadPort< void >::read(), runLoopbackI8(), serialCoordTranslateTest(), serialCoordTranslateTest(), streamingAddTest(), and streamingAddTranslatedTest().

◆ readAsync()

std::future< MessageData > ReadChannelPort::readAsync ( )

virtual

Asynchronous polling read.

Throws if the port is disconnected or currently connected in callback mode.

Reimplemented in esi::UnknownReadChannelPort.

Definition at line 225 of file Ports.cpp.

References assert(), Callback, Disconnected, mode, Polling, and pollingState.

Referenced by NB_MODULE(), read(), esi::TypedReadPort< void >::readAsync(), sv2cCosimserverEpRegister(), and sv2cCosimserverEpTryGet().

◆ resetTranslationState()

void ReadChannelPort::resetTranslationState ( )

protected

Reset translation state buffers and indices.

Definition at line 62 of file Ports.cpp.

References accumulatingListData, listDataBuffer, nextFrameIndex, translatedMessage, and translationBuffer.

Referenced by connect(), connect(), and disconnect().

◆ setMaxDataQueueMsgs()

void esi::ReadChannelPort::setMaxDataQueueMsgs ( uint64_t maxMsgs )

inline

Set maximum number of messages to store in the dataQueue.

0 means no limit. This is only used in polling mode and is set to default of 32 upon connect. While it may seem redundant to have this and bufferSize, there may be (and are) backends which have a very small amount of memory which are accelerator accessible and want to move messages out as quickly as possible.

Definition at line 529 of file Ports.h.

References maxDataQueueMsgs, and pollingState.

◆ translateIncoming()

bool ReadChannelPort::translateIncoming ( MessageData & data )

protected

Translate incoming data if the port type is a window type.

Returns true if the message has been completely received.

Definition at line 489 of file Ports.cpp.

References assert(), and esi::ChannelPort::translationInfo.

Referenced by connect(), and connect().

Member Data Documentation

◆ accumulatingListData

bool esi::ReadChannelPort::accumulatingListData = false

protected

Flag to track whether we're in the middle of accumulating list data.

Definition at line 563 of file Ports.h.

Referenced by resetTranslationState().

◆ activeCallbacks

size_t esi::ReadChannelPort::activeCallbacks = 0

protected

Definition at line 580 of file Ports.h.

Referenced by disconnect(), and invokeCallback().

◆ callback

ReadCallback esi::ReadChannelPort::callback

private

Backends should not call this directly.

Use invokeCallback() instead, which handles synchronization with disconnects.

Definition at line 545 of file Ports.h.

Referenced by connect(), connect(), connect(), disconnect(), and invokeCallback().

◆ callbackCv

std::condition_variable esi::ReadChannelPort::callbackCv

protected

Definition at line 579 of file Ports.h.

Referenced by disconnect(), and invokeCallback().

◆ callbackMutex

std::mutex esi::ReadChannelPort::callbackMutex

protected

Synchronizes callback revocation during disconnect.

Definition at line 578 of file Ports.h.

Referenced by disconnect(), and invokeCallback().

◆ DefaultMaxDataQueueMsgs

constexpr uint64_t esi::ReadChannelPort::DefaultMaxDataQueueMsgs = 32

staticconstexpr

Default max data queue size set at connect time.

Definition at line 504 of file Ports.h.

◆ listDataBuffer

std::vector<uint8_t> esi::ReadChannelPort::listDataBuffer

protected

For list fields: accumulated list data across frames.

Definition at line 561 of file Ports.h.

Referenced by resetTranslationState().

◆ maxDataQueueMsgs

uint64_t esi::ReadChannelPort::maxDataQueueMsgs = DefaultMaxDataQueueMsgs

protected

Definition at line 574 of file Ports.h.

Referenced by connect(), and setMaxDataQueueMsgs().

◆ mode

volatile Mode esi::ReadChannelPort::mode

protected

Definition at line 550 of file Ports.h.

Referenced by connect(), connect(), disconnect(), invokeCallback(), isConnected(), and readAsync().

◆ nextFrameIndex

size_t esi::ReadChannelPort::nextFrameIndex = 0

protected

Index of the next expected frame (for multi-frame windows).

Definition at line 559 of file Ports.h.

Referenced by resetTranslationState().

◆ pollingState

std::optional<detail::PollingBuffer<MessageData> > esi::ReadChannelPort::pollingState

protected

Definition at line 575 of file Ports.h.

Referenced by connect(), disconnect(), readAsync(), and setMaxDataQueueMsgs().

◆ translatedMessage

std::unique_ptr<SegmentedMessageData> esi::ReadChannelPort::translatedMessage

protected

If a translated message has been assembled but not yet consumed, retain ownership here so retries present the same message object.

Definition at line 554 of file Ports.h.

Referenced by connect(), connect(), and resetTranslationState().

◆ translationBuffer

std::vector<uint8_t> esi::ReadChannelPort::translationBuffer

protected

Window translation support.

Definition at line 557 of file Ports.h.

Referenced by connect(), connect(), and resetTranslationState().

The documentation for this class was generated from the following files:

/home/runner/work/circt-www/circt-www/circt_src/lib/Dialect/ESI/runtime/cpp/include/esi/Ports.h
/home/runner/work/circt-www/circt-www/circt_src/lib/Dialect/ESI/runtime/cpp/lib/Ports.cpp

Public Types

Public Member Functions

Static Public Attributes

Protected Types

Protected Member Functions

Protected Attributes

Private Attributes

Detailed Description

Member Typedef Documentation

◆ FlatReadCallback

◆ ReadCallback

Member Enumeration Documentation

◆ Mode

Constructor & Destructor Documentation

◆ ReadChannelPort()

Member Function Documentation

◆ connect() [1/3]

◆ connect() [2/3]

◆ connect() [3/3]

◆ disconnect()

◆ invokeCallback()

◆ isConnected()

◆ read()

◆ readAsync()

◆ resetTranslationState()

◆ setMaxDataQueueMsgs()

◆ translateIncoming()

Member Data Documentation

◆ accumulatingListData

◆ activeCallbacks

◆ callback

◆ callbackCv

◆ callbackMutex

◆ DefaultMaxDataQueueMsgs

◆ listDataBuffer

◆ maxDataQueueMsgs

◆ mode

◆ nextFrameIndex

◆ pollingState

◆ translatedMessage

◆ translationBuffer