Classes
class	ChannelMMIO

class	ESI_Manifest_ROM

class	ESI_Manifest_ROM_Wrapper

class	MMIOIndirection

Functions
Module	HeaderMMIO (int manifest_loc)

type["ChannelDemuxNImpl"]	ChannelDemuxN_HalfStage_ReadyBlocking (Type data_type, int num_outs, int next_sel_width)

type["ChannelDemuxTree"]	ChannelDemuxTree_HalfStage_ReadyBlocking (Type data_type, int num_outs, int branching_factor_log2)

type["DesignResetControllerImpl"]	DesignResetController (int delay_cycles)

type["SliceReadGearboxImpl"]	SliceReadGearbox (int input_bitwidth, int output_bitwidth)

type["ConcatReadGearboxImpl"]	ConcatReadGearbox (int input_bitwidth, int output_bitwidth)

type["DepackReadGearboxImpl"]	DepackReadGearbox (int input_bitwidth, int output_bitwidth)

type["ShiftReadGearboxImpl"]	ShiftReadGearbox (int input_bitwidth, int output_bitwidth)

	select_read_gearbox (bool is_list, int input_bitwidth, int output_bitwidth)

	HostMemReadReqSplitter (Channel req_channel_type, Channel resp_channel_type, int max_chunk_bytes)

	HostmemReadProcessor (int read_width, hostmem_module, List[esi._OutputBundleSetter] reqs, int max_read_request_bytes=DEFAULT_MAX_READ_REQUEST_BYTES)

type["TaggedWriteGearboxImpl"]	TaggedWriteGearbox (int input_bitwidth, int output_bitwidth, int max_burst_bytes)

type[ 'EmitEveryNImpl']	EmitEveryN (Type message_type, int N)

type["HostMemWriteProcessorImpl"]	HostMemWriteProcessor (int write_width, hostmem_module, List[esi._OutputBundleSetter] reqs, int max_write_payload_bytes=DEFAULT_MAX_WRITE_PAYLOAD_BYTES)

typing.Type[ 'ChannelHostMemImpl']	ChannelHostMem (int read_width, int write_width, int max_read_request_bytes=DEFAULT_MAX_READ_REQUEST_BYTES, int max_write_payload_bytes=DEFAULT_MAX_WRITE_PAYLOAD_BYTES)

type[ 'DummyToHostEngineImpl']	DummyToHostEngine (Type client_type)

type[ 'DummyFromHostEngineImpl']	DummyFromHostEngine (Type client_type)

Tuple[Callable, Callable]	_resolve_engine_pair (str path)

type[ 'ChannelEngineService']	ChannelEngineService (Callable to_host_engine_gen, Callable from_host_engine_gen)

Variables
int	MagicNumber = 0x207D98E5_E5100E51

int	VersionNumber = 0

int	IndirectionMagicNumber = 0x312bf0cc_E5100E51

int	IndirectionVersionNumber = 0

int	ResetMagicNumber = 0x00000E510000B007

int	ResetCycles = 8192

int	DEFAULT_MAX_READ_REQUEST_BYTES = 64 * 4

int	DEFAULT_MAX_WRITE_PAYLOAD_BYTES = 256

Function Documentation

◆ _resolve_engine_pair()

Tuple[Callable, Callable] esiaccel.bsp.common._resolve_engine_pair ( str path )

protected

Resolve a dotted Python import path to a
`(to_host_engine_gen, from_host_engine_gen)` tuple, used to override the
default engine pair for a specific service request.

The path may point at either:
  - a module-level 2-tuple attribute, e.g.
    `"mypkg.mymod.MyEnginePair"` where `MyEnginePair` is
    `(MyToHost, MyFromHost)`; or
  - a zero-arg factory callable returning such a tuple.

Definition at line 2034 of file common.py.

Referenced by esiaccel.bsp.common.ChannelEngineService().

◆ ChannelDemuxN_HalfStage_ReadyBlocking()

type["ChannelDemuxNImpl"] esiaccel.bsp.common.ChannelDemuxN_HalfStage_ReadyBlocking	(	Type	data_type,
		int	num_outs,
		int	next_sel_width
	)

N-way channel demultiplexer for valid/ready signaling. Contains
  valid/ready registers on the output channels. The selection signal is now
  embedded in the input channel payload as a struct {sel, data}. Input
  signals ready when the selected output register is empty.

Definition at line 171 of file common.py.

References wrap().

Referenced by esiaccel.bsp.common.ChannelDemuxTree_HalfStage_ReadyBlocking().

◆ ChannelDemuxTree_HalfStage_ReadyBlocking()

type["ChannelDemuxTree"] esiaccel.bsp.common.ChannelDemuxTree_HalfStage_ReadyBlocking	(	Type	data_type,
		int	num_outs,
		int	branching_factor_log2
	)

Pipelined N-way channel demultiplexer for valid/ready signaling. This
  implementation uses a tree structure of
  ChannelDemuxN_HalfStage_ReadyBlocking modules to reduce fanout pressure.
  Supports maximum half-throughput to save complexity and area.

Definition at line 264 of file common.py.

References esiaccel.bsp.common.ChannelDemuxN_HalfStage_ReadyBlocking().

Referenced by esiaccel.bsp.common.ChannelMMIO.build_read().

◆ ChannelEngineService()

type['ChannelEngineService'] esiaccel.bsp.common.ChannelEngineService	(	Callable	to_host_engine_gen,
		Callable	from_host_engine_gen
	)

Returns a channel service implementation which calls
to_host_engine_gen(<client_type>) or from_host_engine_gen(<client_type>) to
generate the to_host and from_host engines for each channel. Does not support
engines which can service multiple clients at once.

Individual service requests may override the default engine pair by passing
`options={"engine": "pkg.mod.attr"}` at the service-request call site (e.g.
`HostComms.some_bundle(AppID(...), options={"engine": "..."})`). The path
is resolved by `_resolve_engine_pair` and must yield a
`(to_host_engine_gen, from_host_engine_gen)` tuple with the same call shape
as the defaults; the override applies to every channel of that request's
bundle.

Definition at line 2071 of file common.py.

References esiaccel.bsp.common._resolve_engine_pair().

◆ ChannelHostMem()

typing.Type['ChannelHostMemImpl'] esiaccel.bsp.common.ChannelHostMem	(	int	read_width,
		int	write_width,
		int	max_read_request_bytes = `DEFAULT_MAX_READ_REQUEST_BYTES`,
		int	max_write_payload_bytes = `DEFAULT_MAX_WRITE_PAYLOAD_BYTES`
	)

Definition at line 1912 of file common.py.

References esiaccel.bsp.common.HostmemReadProcessor(), and esiaccel.bsp.common.HostMemWriteProcessor().

◆ ConcatReadGearbox()

type["ConcatReadGearboxImpl"] esiaccel.bsp.common.ConcatReadGearbox	(	int	input_bitwidth,
		int	output_bitwidth
	)

Concatenate ``ceil(OUT/IN)`` consecutive engine words into one client
element wider than the word (``OUT > IN``). Serves single-message reads (any
``OUT > IN``; the low ``OUT`` bits of the concatenation are the element) and
contiguous list reads whose element is a whole number of output_bitwidth
(``OUT % IN == 0``, so elements never straddle). ``valid_bytes`` is unused:
such lists have no partial words and a single element is one flit. Straddling
lists use `ShiftReadGearbox`.

Definition at line 769 of file common.py.

Referenced by esiaccel.bsp.common.select_read_gearbox().

◆ DepackReadGearbox()

type["DepackReadGearboxImpl"] esiaccel.bsp.common.DepackReadGearbox	(	int	input_bitwidth,
		int	output_bitwidth
	)

Unpack a byte-aligned element that divides the engine word
(``OUT % 8 == 0`` and ``IN % OUT == 0``) from a contiguous list response. Each
word holds ``IN/OUT`` gap-free elements that never straddle, so a counter
drives a parts:1 element mux -- no shifter (e.g. 32b/64b, 64b/256b).
``valid_bytes`` locates the last element in the burst's (possibly partial)
final word. Straddling relationships use `ShiftReadGearbox`.

Definition at line 874 of file common.py.

Referenced by esiaccel.bsp.common.select_read_gearbox().

◆ DesignResetController()

type["DesignResetControllerImpl"] esiaccel.bsp.common.DesignResetController ( int delay_cycles )

Counts `delay_cycles` clock cycles after a reset request is observed, then
asserts `design_reset` for one cycle. This module must be driven by the
*external* reset only (not the reset it generates) so that the countdown is
not disturbed by the reset it produces.

`reset_pending` is asserted from the moment a reset is requested until it
fires. It is intended to be used to quiesce the design (e.g. stop accepting
new transactions) so that nothing is in flight when the reset is asserted.

Definition at line 375 of file common.py.

◆ DummyFromHostEngine()

type['DummyFromHostEngineImpl'] esiaccel.bsp.common.DummyFromHostEngine ( Type client_type )

Create a fake DMA engine which just never produces messages.

Definition at line 2011 of file common.py.

References wrap().

◆ DummyToHostEngine()

type['DummyToHostEngineImpl'] esiaccel.bsp.common.DummyToHostEngine ( Type client_type )

Create a fake DMA engine which just throws everything away.

Definition at line 1990 of file common.py.

◆ EmitEveryN()

type['EmitEveryNImpl'] esiaccel.bsp.common.EmitEveryN	(	Type	message_type,
		int	N
	)

Emit (forward) one message for every N input messages. The emitted message
is the last one of the N received. N must be >= 1.

Definition at line 1684 of file common.py.

Referenced by esiaccel.bsp.common.HostMemWriteProcessor().

◆ HeaderMMIO()

Module esiaccel.bsp.common.HeaderMMIO ( int manifest_loc )

Definition at line 72 of file common.py.

References wrap().

Referenced by esiaccel.bsp.common.ChannelMMIO.build_read().

◆ HostmemReadProcessor()

esiaccel.bsp.common.HostmemReadProcessor	(	int	read_width,
			hostmem_module,
		List[esi._OutputBundleSetter]	reqs,
		int	max_read_request_bytes = `DEFAULT_MAX_READ_REQUEST_BYTES`
	)

Construct a host memory read request module to orchestrate the the read
connections. Responsible for both gearboxing the data, multiplexing the
requests, reassembling out-of-order responses and routing the responses to the
correct clients.

Generate this module dynamically to allow for multiple read clients of
multiple types to be directly accomodated.

Definition at line 1342 of file common.py.

References esiaccel.bsp.common.HostMemReadReqSplitter(), esiaccel.bsp.common.select_read_gearbox(), and wrap().

Referenced by esiaccel.bsp.common.ChannelHostMem().

◆ HostMemReadReqSplitter()

esiaccel.bsp.common.HostMemReadReqSplitter	(	Channel	req_channel_type,
		Channel	resp_channel_type,
		int	max_chunk_bytes
	)

Split oversized host memory read requests into request-sized chunks before
arbitration and reassemble the per-chunk responses into a single logical
burst.

A burst read (`read_list`) can request many more bytes than a single upstream
read request can carry. This module breaks such a request into
`max_chunk_bytes`-sized (word-aligned) chunks addressed sequentially from the
base. Splitting here -- *before* the requests
are arbitrated onto the shared upstream read channel -- lets each client's
chunks interleave with other clients' requests, so one large burst does not
monopolize host memory bandwidth.

On the response path the per-chunk end-of-list markers are dropped and a
single burst-final `last` is re-derived from the total transfer length, so the
gearbox and client see one contiguous response stream identical to an unsplit
read.

Only one logical request is in flight at a time (matching the read processor's
one-outstanding-transaction-per-client model): a new request is not accepted
until the current burst's chunks have all been issued and its responses have
fully drained. This will be a performance limiter.
TODO: make this able to issue >1 one read at a time.

req_channel_type:  channel of the upstream read request {address, length
  (bytes), tag}.
resp_channel_type: channel of the upstream response {tag, data, last}.
max_chunk_bytes:   largest per-chunk byte count; must be > 0 and a multiple of
  the response word size.

Definition at line 1152 of file common.py.

Referenced by esiaccel.bsp.common.HostmemReadProcessor().

◆ HostMemWriteProcessor()

type["HostMemWriteProcessorImpl"] esiaccel.bsp.common.HostMemWriteProcessor	(	int	write_width,
			hostmem_module,
		List[esi._OutputBundleSetter]	reqs,
		int	max_write_payload_bytes = `DEFAULT_MAX_WRITE_PAYLOAD_BYTES`
	)

Construct a host memory write request module to orchestrate the the write
connections. Responsible for both gearboxing the data, multiplexing the
requests, reassembling out-of-order responses and routing the responses to the
correct clients.

Generate this module dynamically to allow for multiple write clients of
multiple types to be directly accomodated.

Definition at line 1736 of file common.py.

References esiaccel.bsp.common.EmitEveryN(), esiaccel.bsp.common.TaggedWriteGearbox(), and wrap().

Referenced by esiaccel.bsp.common.ChannelHostMem().

◆ select_read_gearbox()

esiaccel.bsp.common.select_read_gearbox	(	bool	is_list,
		int	input_bitwidth,
		int	output_bitwidth
	)

Pick the read-gearbox module for a client of the given kind and width
relationship. Every gearbox shares the {tag, data, valid_bytes, last} input
(from `HostMemReadReqSplitter`) and the {tag, data, last} output, so callers
wire them identically. `ShiftReadGearbox` is the correct-for-everything
fallback; the others avoid its barrel shifter for regular relationships.

Definition at line 1115 of file common.py.

References esiaccel.bsp.common.ConcatReadGearbox(), esiaccel.bsp.common.DepackReadGearbox(), esiaccel.bsp.common.ShiftReadGearbox(), and esiaccel.bsp.common.SliceReadGearbox().

Referenced by esiaccel.bsp.common.HostmemReadProcessor().

◆ ShiftReadGearbox()

type["ShiftReadGearboxImpl"] esiaccel.bsp.common.ShiftReadGearbox	(	int	input_bitwidth,
		int	output_bitwidth
	)

Universal fallback: unpack a contiguous, byte-packed element stream (a
`read_list` response) for ANY ``(input_bitwidth, output_bitwidth)`` pair.

Elements are packed at their natural byte stride ``stride = ceil(OUT/8)``
bytes, so element k begins at wire bit ``k*stride*8`` and, in general,
straddles engine-word boundaries at an arbitrary bit offset. A byte-addressed
shift-register accumulator realigns each element across words. This is correct
for every width relationship; `SliceReadGearbox`, `ConcatReadGearbox` and
`DepackReadGearbox` are optimizations that avoid this barrel shifter for the
regular (non-straddling) cases.

Each input word carries ``valid_bytes`` (how many of its bytes are real) and
``last``. Both are framed to one whole `read_list` request rather than to the
transport: `HostMemReadReqSplitter` drops the per-chunk framing of the reads
it issues and re-derives these from the request's total length, so only the
request's final word is ever partial. That length is ``num_elements *
stride``, so tracking real bytes lets the gearbox emit exactly the right
elements and place the list-terminating ``last`` on the final one -- no
padding element is ever emitted.

Definition at line 969 of file common.py.

Referenced by esiaccel.bsp.common.select_read_gearbox().

◆ SliceReadGearbox()

type["SliceReadGearboxImpl"] esiaccel.bsp.common.SliceReadGearbox	(	int	input_bitwidth,
		int	output_bitwidth
	)

Narrow one engine word to a single-message client element no wider than the
word (``OUT <= IN``). The element sits in the word's low bits, so the datapath
is a slice; ``valid_bytes`` is unused (a single element is never a partial
word). Wider single elements use `ConcatReadGearbox`; packed list reads use
`DepackReadGearbox`/`ShiftReadGearbox`.

Definition at line 719 of file common.py.

Referenced by esiaccel.bsp.common.select_read_gearbox().

◆ TaggedWriteGearbox()

type["TaggedWriteGearboxImpl"] esiaccel.bsp.common.TaggedWriteGearbox	(	int	input_bitwidth,
		int	output_bitwidth,
		int	max_burst_bytes
	)

Build a gearbox to convert the client data to upstream write chunks.
Assumes a struct {address, tag, data} and only gearboxes the data. Tag is
stored separately and the struct is re-assembled later on.

'max_burst_bytes' caps a single contiguous upstream write transaction (a
max-payload-size analog): when an element spans more than 'max_burst_bytes',
its engine words are split into multiple <= 'max_burst_bytes' transactions by
emitting the framing 'last' at each boundary. 0 disables the cap.

Definition at line 1531 of file common.py.

Referenced by esiaccel.bsp.common.HostMemWriteProcessor().

Variable Documentation

◆ DEFAULT_MAX_READ_REQUEST_BYTES

int esiaccel.bsp.common.DEFAULT_MAX_READ_REQUEST_BYTES = 64 * 4

Definition at line 1143 of file common.py.

◆ DEFAULT_MAX_WRITE_PAYLOAD_BYTES

int esiaccel.bsp.common.DEFAULT_MAX_WRITE_PAYLOAD_BYTES = 256

Definition at line 1148 of file common.py.

◆ IndirectionMagicNumber

int esiaccel.bsp.common.IndirectionMagicNumber = 0x312bf0cc_E5100E51

Definition at line 27 of file common.py.

◆ IndirectionVersionNumber

int esiaccel.bsp.common.IndirectionVersionNumber = 0

Definition at line 28 of file common.py.

◆ MagicNumber

int esiaccel.bsp.common.MagicNumber = 0x207D98E5_E5100E51

Definition at line 24 of file common.py.

◆ ResetCycles

int esiaccel.bsp.common.ResetCycles = 8192

Definition at line 37 of file common.py.

◆ ResetMagicNumber

int esiaccel.bsp.common.ResetMagicNumber = 0x00000E510000B007

Definition at line 34 of file common.py.

◆ VersionNumber

int esiaccel.bsp.common.VersionNumber = 0

Definition at line 25 of file common.py.

Classes

Functions

Variables

Function Documentation

◆ _resolve_engine_pair()

◆ ChannelDemuxN_HalfStage_ReadyBlocking()

◆ ChannelDemuxTree_HalfStage_ReadyBlocking()

◆ ChannelEngineService()

◆ ChannelHostMem()

◆ ConcatReadGearbox()

◆ DepackReadGearbox()

◆ DesignResetController()

◆ DummyFromHostEngine()

◆ DummyToHostEngine()

◆ EmitEveryN()

◆ HeaderMMIO()

◆ HostmemReadProcessor()

◆ HostMemReadReqSplitter()

◆ HostMemWriteProcessor()

◆ select_read_gearbox()

◆ ShiftReadGearbox()

◆ SliceReadGearbox()

◆ TaggedWriteGearbox()

Variable Documentation

◆ DEFAULT_MAX_READ_REQUEST_BYTES

◆ DEFAULT_MAX_WRITE_PAYLOAD_BYTES

◆ IndirectionMagicNumber

◆ IndirectionVersionNumber

◆ MagicNumber

◆ ResetCycles

◆ ResetMagicNumber

◆ VersionNumber