port¶

Port class hierarchy for FPGA fabric.

This module contains the port class hierarchy for representing different types of ports in the FPGA fabric:

Port: Base class for all port types
TilePort: Port on a tile with side and termination information
BelPort: Port on a BEL (Basic Element of Logic)
SlicedPort: A sliced portion of another port
SharedPort: A port shared between multiple BELs
ConfigPort: A configuration port with features

Attributes¶

`GenericPort`
`NULL_PORT_NAME`

Classes¶

`BelPort`	A port on a BEL (Basic Element of Logic).
`ConfigPort`	A configuration port with features.
`Port`	Base class for all port types.
`SharedPort`	A port shared between multiple BELs.
`SlicedPort`	A port that represents a slice of another port.
`TilePort`	TilePort represents a port on a tile with a side and termination status.

Module Contents¶

BelPort¶

class BelPort(name, io_direction, width, prefix='', external=False, control=False, is_clock=False, is_global=False, net='')[source]¶

Bases: Port

A port on a BEL (Basic Element of Logic).

Parameters:

name (str) – The name of the port.
io_direction (IO) – The I/O direction (INPUT, OUTPUT, INOUT).
width (int) – The bit width of the port.
prefix (str) – Prefix added to the port name. Defaults to “”.
external (bool) – Whether the port is exposed externally. Defaults to False.
control (bool) – Whether the port is a control signal. Defaults to False.
is_clock (bool) – Whether the port carries a clock. Defaults to False.
is_global (bool) – Whether the port is driven by a fabric-wide signal. Defaults to False.
net (str) – The net the port belongs to. Defaults to “”, the global net.

Properties¶

property control: bool[source]¶

Whether the port is a control signal.

property external: bool[source]¶

Whether the port is exposed externally.

property name: str[source]¶

The port name including its prefix.

property prefix: str[source]¶

The prefix added to the port name.

Methods¶

expand() → list[str][source]¶

Expand the port name into a list of strings based on the width.

Returns:: A list of expanded port names.

serialize() → dict[source]¶

Serialize the BEL port to a dictionary.

ConfigPort¶

class ConfigPort(name, io_direction, width, features=None, feature_type=FeatureType.ENUMERATE)[source]¶

Bases: Port

A configuration port with features.

Parameters:

name (str) – The name of the port.
io_direction (IO) – The I/O direction (INPUT, OUTPUT, INOUT).
width (int) – The bit width of the port.
features (list[FeatureValue] | None) – List of features associated with this port. Defaults to None, which resolves to an empty list.
feature_type (FeatureType) – The type of feature encoding. Defaults to FeatureType.ENUMERATE.

Properties¶

property feature_type: FeatureType[source]¶

The type of feature encoding.

property features: list[FeatureValue][source]¶

The list of features associated with this port.

Methods¶

serialize() → dict[source]¶

Serialize the config port to a dictionary.

GenericPort[source]¶

NULL_PORT_NAME = 'NULL'[source]¶

Port¶

class Port(name, io_direction, width, is_clock=False, is_global=False, net='')[source]¶

Base class for all port types.

Parameters:

name (str) – The name of the port.
io_direction (IO) – The I/O direction (INPUT, OUTPUT, INOUT).
width (int) – The bit width of the port.
is_clock (bool) – Whether the port carries a clock. Defaults to False.
is_global (bool) – Whether the port is driven by a fabric-wide signal, such as the global user clock, rather than a locally generated one. Defaults to False.
net (str) – The net the port belongs to. Defaults to “”, the global net.

Raises:

ValueError – If the width is not greater than 0.
TypeError – If io_direction is not an instance of IO, if name is not a string, or if is_clock or is_global is not a bool.

Properties¶

property io_direction: IO[source]¶

Return the I/O direction.

property is_clock: bool[source]¶

Whether the port carries a clock.

property is_global: bool[source]¶

Whether the port is driven by a fabric-wide signal.

property is_inout: bool[source]¶

Whether the port is bidirectional.

property is_input: bool[source]¶

Whether the port is an input. An INOUT port is not an input.

property is_output: bool[source]¶

Whether the port is an output. An INOUT port is not an output.

property name: str[source]¶

Return the port name.

property name_is_null: bool[source]¶

Whether the port name is the NULL placeholder.

Only the port’s own name is considered. A wire’s source_name and destination_name are NULL independently of it and of each other.

property net: str[source]¶

The net the port belongs to; “” is the global net.

property width: int[source]¶

Return the bit width.

Methods¶

expand() → list[str][source]¶

Expand the port name into a list of strings based on the width.

Returns:: A list of expanded port names.

serialize() → dict[source]¶

Serialize the port to a dictionary.

SharedPort¶

class SharedPort(name, io_direction, width, shared_with='')[source]¶

Bases: Port

A port shared between multiple BELs.

Parameters:

name (str) – The name of the port.
io_direction (IO) – The I/O direction (INPUT, OUTPUT, INOUT).
width (int) – The bit width of the port.
shared_with (str) – Name of the entity this port is shared with. Defaults to “”.

Properties¶

property shared_with: str[source]¶

Name of the entity this port is shared with.

Methods¶

serialize() → dict[source]¶

Serialize the shared port to a dictionary.

share_expand() → list[str][source]¶

Expand the port name into a list of strings based on the width.

Returns:: A list of expanded port names using the shared_with name.

SlicedPort¶

class SlicedPort(original_port, high, low)[source]¶

Bases: Port

A port that represents a slice of another port.

The range is written high downto low, following VHDL: both endpoints are inclusive 0-based indices into the original port’s own expansion, and high selects the most significant bit. expand() still lists bits least significant first, matching Port.expand().

Parameters:

original_port (Port) – The original port being sliced.
high (int) – The most significant bit index of the slice, inclusive.
low (int) – The least significant bit index of the slice, inclusive.

Raises:

ValueError – If low is negative, if high is below low, or if high falls outside the original port’s width.

Properties¶

property high: int[source]¶

The most significant bit index of the slice, inclusive.

property low: int[source]¶

The least significant bit index of the slice, inclusive.

property original_port: Port[source]¶

The original port being sliced.

Methods¶

expand() → list[str][source]¶

Expand the slice into indexed wire names, least significant bit first.

serialize() → dict[source]¶

Serialize the sliced port to a dictionary.

TilePort¶

class TilePort(name, io_direction, width, side_of_tile, term=False, tile=None, wire_direction=None, source_name='', x_offset=0, y_offset=0, destination_name='', wire_count=1)[source]¶

Bases: Port

TilePort represents a port on a tile with a side and termination status.

It is an immutable and comparable class. When sorting a list of TilePort instances, the order is determined first by the side of the tile in order of [north, east, south, west] then by the IO type in the order of [output, input, inout].

Parameters:

name (str) – The name of the port.
io_direction (IO) – The I/O direction (INPUT, OUTPUT, INOUT).
width (int) – The bit width of the port.
side_of_tile (Side) – The side of the tile where the port is located.
term (bool) – Indicates if the port is a termination port. Defaults to False.
tile (Tile | None) – The tile this port belongs to. Set once at construction and read-only thereafter. Defaults to None, leaving the port unattached.
wire_direction (Direction | None) – The wire direction (for backward compatibility with legacy Port). Defaults to None, which resolves to Direction.JUMP.
source_name (str) – The source name of the wire connection. Defaults to “”.
x_offset (int) – The X-offset for wire routing. Defaults to 0.
y_offset (int) – The Y-offset for wire routing. Defaults to 0.
destination_name (str) – The destination name of the wire connection. Defaults to “”.
wire_count (int) – The number of wires. Defaults to 1.

Properties¶

property destination_name: str[source]¶

Destination name (backward compatibility).

property side_of_tile: Side[source]¶

The side of the tile where the port is located.

property source_name: str[source]¶

Source name (backward compatibility).

property term: bool[source]¶

Whether the port is a termination port.

property tile: Tile | None[source]¶

The tile this port belongs to, or None while the port is unattached.

property wire_count: int[source]¶

Wire count (backward compatibility).

property wire_direction: Direction[source]¶

Wire direction (backward compatibility).

property x_offset: int[source]¶

X-offset (backward compatibility).

property y_offset: int[source]¶

Y-offset (backward compatibility).

Methods¶

expand_port_info(mode='SwitchMatrix') → tuple[list[str], list[str]][source]¶

Expand the port information to the individual bit signal.

If ‘Indexed’ is in the mode, then brackets are added to the signal name.

Parameters:: mode (str, optional) – Mode for expansion. Defaults to “SwitchMatrix”. Possible modes are ‘all’, ‘allIndexed’, ‘Top’, ‘TopIndexed’, ‘AutoTop’, ‘AutoTopIndexed’, ‘SwitchMatrix’, ‘SwitchMatrixIndexed’, ‘AutoSwitchMatrix’, ‘AutoSwitchMatrixIndexed’
Returns:: A tuple of two lists. The first list contains the source names of the ports and the second list contains the destination names of the ports.

expand_port_info_by_name(indexed=False, prefix='', escape=False) → list[str][source]¶

Expand port information to individual wire names.

Generates a list of individual wire names for this port, accounting for wire count and offset calculations. For termination ports (NULL), the wire count is multiplied by the Manhattan distance.

Parameters:

indexed (bool, optional) – If True, wire names use bracket notation (e.g., port[0]). If False, wire names use simple concatenation (e.g., port0). Defaults to False.
prefix (str, optional) – A prefix to prepend to the port name, by default “”.
escape (bool, optional) – If True, escape special characters in the port names (e.g., for regex), by default False.

Returns:

List of individual wire names for this port.

expand_port_info_by_name_top(indexed=False, prefix='', escape=False) → list[str][source]¶

Expand port information for top-level connections.

Similar to expand_port_info_by_name but specifically for top-level tile connections. The start index is calculated differently to handle the top slice of wires for routing fabric connections.

Parameters:

indexed (bool, optional) – If True, wire names use bracket notation (e.g., port[0]). If False, wire names use simple concatenation (e.g., port0). Defaults to False.
prefix (str, optional) – A prefix to prepend to the port name, by default “”.
escape (bool, optional) – If True, escape special characters in the port names (e.g., for regex), by default False.

Returns:

List of individual wire names for top-level connections.

get_port_regex(indexed=False, prefix='') → str[source]¶

Expand port information to individual wire names.

Generates a regex expression for this port, accounting for wire count and offset calculations.

Parameters:

indexed (bool, optional) – If True, wire names use bracket notation (e.g., port[0]). If False, wire names use simple concatenation (e.g., port0). Defaults to False.
prefix (str, optional) – A prefix to prepend to the port name, by default “”.

Returns:

A regex expression matching the port’s wire names.

serialize() → dict[source]¶

Serialize the tile port to a dictionary.