Skip to content

Routing Reference

PortDirection = Annotated[int, BeforeValidator(_as_direction, json_schema_input_type=(int | Literal['North', 'East', 'South', 'West', 'Eject']))] module-attribute

A router port, given either as an index or as a direction name.

AddrRange

Bases: ConfigModel

Address range class.

Attributes:

Name Type Description
start int

Absolute start address of the range.
end int

Absolute end address of the range.
base Optional[int]

Base address used for calculating ranges in endpoint arrays.
en_collective bool

If true, marks this range as a multicast/collective destination.

size is additionally accepted as an input key in place of start or end, but is not stored as a field - it is normalised away into end and read back through the derived size property.

rdl_addrmap_grp = None class-attribute instance-attribute

One or more SystemRDL addrmap group tags this address range belongs to.

rdl_params = None class-attribute instance-attribute

Parameters bound on the SystemRDL component named by rdl_name.

size property

Size of the address range.

Derived rather than stored: every accepted input shape defines the range as end - start, so keeping a separate field would only add state to hold in sync. size remains a valid input key - see validate_input - it is simply normalised away into end.

from_base_size(base, size, **kwargs) classmethod

Create a range from an array base address and a per-element size.

from_start_size(start, size, **kwargs) classmethod

Create a range from a start address and a size.

set_arr(arr_idx, arr_dim)

Update the address range with the given index.

validate_input()

Validate the address range.

validate_output()

Validate the address range.

CollectiveCfg

Bases: ConfigModel

User-facing collective operation configuration.

The five high-level knobs map to collective_cfg_t in floo_pkg.

Attributes:

Name Type Description
en_narrow_multicast bool

Enables multicast on the narrow link (OpCfg.EnNarrowMulticast).
en_wide_multicast bool

Enables multicast on the wide link (OpCfg.EnWideMulticast).
en_barrier bool

Enables barrier synchronization (OpCfg.EnLsbAnd).
en_narrow_reduction Optional[NarrowReductionCfg]

Configuration for integer ALU reduction operations available on the narrow router (OpCfg.EnA_{Add,Mul,MinS,MinU,MaxS,MaxU}).
en_wide_reduction Optional[WideReductionCfg]

Configuration for floating-point reduction operations available on the wide router (OpCfg.EnF_{Add,Mul,Min,Max}).

Reduction Configuration Options

For en_narrow_reduction and en_wide_reduction, the following YAML values are supported:

  • false / omitted: Disabled (default)
  • true: All operations enabled, default hardware configuration
  • [Add, Mul, ...]: Only the listed operations enabled, default hardware configuration
  • {ops: [...], rd_pipeline_depth: N, cut_offload_intf: true}: Full per-channel control

en_collective property

True when any collective feature is enabled (multicast, barrier, or reduction).

get_collective_cfg property

Return a dict representing collective_cfg_t for sv_struct_render.

render_reduction_typedefs(cfg_n, cfg_w)

Render offload reduction channel/link typedefs for enabled channels.

Coord

Bases: ConfigModel

2D coordinate class.

x and y default to 0 so that a partial offset (e.g. {x: 2}) is accepted wherever a coordinate is read from a config file.

get_dir(node, neighbor) staticmethod

Get the direction from node to neighbor.

render(as_index=False)

Render the SystemVerilog coordinate.

NarrowReductionCfg

Bases: ReductionCfg

Reduction configuration for the narrow link.

get_reduction_cfg()

Return a dict representing reduction_cfg_t for sv_struct_render.

NarrowReductionOp

Bases: ConfigEnum

Integer ALU reduction operations available on the narrow router.

__get_pydantic_json_schema__(core_schema, handler) classmethod

Advertise the accepted names alongside the values.

Pydantic derives enum from the member values, which would reject the by-name spellings that _missing_ resolves and that most configs actually use. Only the canonical spellings are listed; _missing_ additionally accepts them case-insensitively.

ReductionCfg

Bases: ConfigModel

Base reduction hardware configuration shared by narrow and wide channels.

get_reduction_cfg()

Return a dict representing reduction_cfg_t for sv_struct_render.

RouteAlgo

Bases: ConfigEnum

Routing algorithm enum.

Attributes:

Name Type Description
XY

Dimension-ordered XY routing algorithm.
YX

Dimension-ordered YX routing algorithm.
ID

Routing algorithm based on router ID tables.
SRC

Source-based routing algorithm.
XY_MIRRORED

Request path uses XY, response uses YX
YX_MIRRORED

Request path uses YX, response uses XY

is_dor_algo property

True for any dimension-ordered routing algorithm (XY, YX, or one of the mirrored variants), i.e. any algorithm that needs XY coordinates rather than a routing table or a route list.

__get_pydantic_json_schema__(core_schema, handler) classmethod

Advertise the accepted names alongside the values.

Pydantic derives enum from the member values, which would reject the by-name spellings that _missing_ resolves and that most configs actually use. Only the canonical spellings are listed; _missing_ additionally accepts them case-insensitively.

RouteMap

Bases: BaseModel

Route Map class, which can represent the system address map (SAM), or a routing table of a router.

check_no_overlapping_ranges()

Check if there are no overlapping ranges.

distinct_groups()

Return the sorted list of distinct RDL addrmap groups used by any rule.

filter_by_group(group)

Return a new RouteMap with only rules in group (untagged rules included).

pprint()

Pretty print the routing table.

render(aw=None)

Render the SystemVerilog routing table.

render_rdl(rdl_as_mem=False, rdl_memwidth=8)

Render the SystemRDL addrmap internals.

render_rdl_inc()

Render the SystemRDL include header.

rule_type()

Return the type of the rules.

trim()

Optimize the routing table.

RouteMapRule

Bases: BaseModel

Routing rule class.

get_rdl(instance_name, rdl_as_mem=False, rdl_memwidth=8)

Render the SystemRDL routing rule.

render(aw=None)

Render the SystemVerilog routing rule.

render_desc()

Render the description of the routing rule.

RouteMapRuleCollective

Bases: RouteMapRule

Routing rule class for collective operations (multicast, reduction, barrier).

get_rdl(instance_name, rdl_as_mem=False, rdl_memwidth=8)

Render the SystemRDL routing rule.

render(aw=None)

Render the SystemVerilog routing rule.

render_desc()

Render the description of the routing rule.

RouteRule

Bases: BaseModel

Routing rule class.

render(num_route_bits)

Render the SystemVerilog route.

RouteTable

Bases: BaseModel

Route Table class, which can hold the route entries to each destination

render(num_route_bits, no_decl=False)

Render the SystemVerilog route table.

sort_and_pad()

Sort by destination and fill in missing entries.

Routing

Bases: RoutingDesc

A RoutingDesc together with everything Network.gen_routing_info() derives.

Constructed once the graph is elaborated, so sam, addr_width and the endpoint counts are always present. The remaining widths stay optional because which of them exists is decided by route_algo; render_* raises if one is read that the configured algorithm never produces.

addr_offset_bits = None class-attribute instance-attribute

The number of bits to decode the X and Y coordinates from the address. Only used if use_id_table is False and route_algo is XY.

addr_width instance-attribute

The width of the address bus, taken from the network's protocols.

collective_sam = None class-attribute instance-attribute

The collective system address map. Only used if collective is enabled.

decouple_rw = None class-attribute instance-attribute

Read/write decoupling of the wide link. Left unset, no WideRwDecouple parameter is emitted and the hardware default applies.

en_collective property

True when any collective feature is enabled (multicast, barrier, or reduction).

num_endpoints instance-attribute

The number of endpoints in the network.

num_id_bits instance-attribute

The number of bits to represent the ID.

num_route_bits = None class-attribute instance-attribute

The number of bits to represent the route. Only used if route_algo is SRC.

num_x_bits = None class-attribute instance-attribute

The number of bits to represent the X coordinate. Only used if route_algo is XY.

num_y_bits = None class-attribute instance-attribute

The number of bits to represent the Y coordinate. Only used if route_algo is XY.

port_id_bits = 1 class-attribute instance-attribute

The number of bits to represent the local port ID.

sam instance-attribute

The system address map.

vc_impl = None class-attribute instance-attribute

Virtual channel implementation. Left unset, no VcImpl parameter is emitted and the hardware default applies.

xy_id_offset = None class-attribute instance-attribute

A constant offset to add to the X and Y coordinates. Only used if route_algo is XY.

from_desc(desc, **generated) classmethod

Build the elaborated routing from its configuration and the derived values.

render_hdr_typedef(network_type)

Render the SystemVerilog flit header.

render_param_decl()

Render the SystemVerilog parameter declaration.

render_route_cfg(name)

Render the SystemVerilog routing configuration.

render_typedefs()

Render the SystemVerilog typedefs.

render_vc_impl()

Render WideRwDecouple and VcImpl localparam declarations.

Only emitted when the configuration asked for them, so that a network that says nothing about either keeps the hardware defaults.

validate_collective_route_algo()

Collective operations are supported with dimension-ordered routing only.

validate_mirrored_route_algo()

XY_MIRRORED/YX_MIRRORED require a physically decoupled wide channel.

RoutingDesc

Bases: ConfigModel

The routing section of a configuration file.

This holds only what a configuration declares. The widths and address maps that Network.gen_routing_info() derives from the elaborated graph live on Routing, which extends this class, so that a configuration cannot set them and the two are not confused for one another.

Attributes:

Name Type Description
route_algo RouteAlgo

This determines the routing algorithm to use. You can find more information about the different routing algorithms in the routing algorithms documentation.
use_id_table bool

A boolean flag indicating that if set to true, a system address table will be generated in the package which is used to translate system addresses to endpoint IDs or coordinates. This is always used in table-based routing and can be used in XYRouting to translate system addresses to XY-coordinates. If XYRouting is used and this field is set to false, the XY coordinates are automatically derived as address offsets. This is much simpler but requires that all endpoint addresses are contiguous and of the same size.
rob_idx_bits int

The number of bits to allocate for the rob_idx field in the packet header. This is only relevant if reordering buffers are used in the network.
collective CollectiveCfg

Collective operation configuration (multicast, barrier, reduction).

decouple_rw = None class-attribute instance-attribute

Read/write decoupling of the wide link. Left unset, no WideRwDecouple parameter is emitted and the hardware default applies.

en_collective property

True when any collective feature is enabled (multicast, barrier, or reduction).

port_id_bits = 1 class-attribute instance-attribute

The number of bits to represent the local port ID.

vc_impl = None class-attribute instance-attribute

Virtual channel implementation. Left unset, no VcImpl parameter is emitted and the hardware default applies.

validate_collective_route_algo()

Collective operations are supported with dimension-ordered routing only.

validate_mirrored_route_algo()

XY_MIRRORED/YX_MIRRORED require a physically decoupled wide channel.

SimpleId

Bases: ConfigModel

ID class.

__add__(other)

Add the ID.

__lt__(other)

Less than comparison.

__sub__(other)

Subtract the ID.

render(as_index=False)

Render the SystemVerilog ID.

validate_id(v) classmethod

Validate the ID.

VcImpl

Bases: ConfigEnum

Virtual channel implementation enum (mirrors vc_impl_e in floo_pkg).

Only relevant when decouple_rw == WideRwDecouple.VC.

__get_pydantic_json_schema__(core_schema, handler) classmethod

Advertise the accepted names alongside the values.

Pydantic derives enum from the member values, which would reject the by-name spellings that _missing_ resolves and that most configs actually use. Only the canonical spellings are listed; _missing_ additionally accepts them case-insensitively.

WideReductionCfg

Bases: ReductionCfg

Reduction configuration for the wide link.

get_reduction_cfg()

Return a dict representing reduction_cfg_t for sv_struct_render.

WideReductionOp

Bases: ConfigEnum

Floating-point reduction operations available on the wide router.

__get_pydantic_json_schema__(core_schema, handler) classmethod

Advertise the accepted names alongside the values.

Pydantic derives enum from the member values, which would reject the by-name spellings that _missing_ resolves and that most configs actually use. Only the canonical spellings are listed; _missing_ additionally accepts them case-insensitively.

WideRwDecouple

Bases: ConfigEnum

Read/write decoupling mode for the wide link (mirrors wide_rw_decouple_e in floo_pkg).

NONE — shared wide link, no decoupling (default) VC — decouple using virtual channels (requires vc_impl) PHYS — decouple using separate physical wide links

__get_pydantic_json_schema__(core_schema, handler) classmethod

Advertise the accepted names alongside the values.

Pydantic derives enum from the member values, which would reject the by-name spellings that _missing_ resolves and that most configs actually use. Only the canonical spellings are listed; _missing_ additionally accepts them case-insensitively.

XYDirections

Bases: Enum

XY directions enum.

reverse(direction) classmethod

Reverse the direction.

to_coords(direction) classmethod

Convert the direction to coordinates.