switch_matrix

Switch matrix construct for the FABulous fabric model.

A tile’s switch matrix is the programmable interconnect: which sources may drive each destination inside the tile. The connectivity is declared in the tile’s matrix file (a .csv adjacency matrix or a .list of pairs) and read once into this dataclass in canonical port/BEL order. RTL generation lives in fabulous.fabric_generator.gen_fabric.gen_switchmatrix.

Classes

SwitchMatrix

Encapsulates a tile's switch matrix: source file and connectivity.

Functions

switch_matrix_signal_order(ports, bels)

Return the canonical (sources, dests) signal order for a switch matrix.

Module Contents

SwitchMatrix

class SwitchMatrix

Encapsulates a tile’s switch matrix: source file and connectivity.

Read once and immutable: the connectivity is fixed at construction, so the same object can be safely shared or deep-copied across fabric-grid placements.

Variables:

• matrix_file (Path) – Source file for the switch matrix (.csv, .list, or hand-written HDL).

• connections (dict[str, list[str]]) – Mux output port -> list of mux input signals. Empty for hand-written HDL.

• preserve_list_order (bool) – Whether the mux-input order is significant (MSB-first .list order) rather than the canonical dest-column order. Recorded once at read time and reused when exporting so a round trip is faithful. Default False.

• hdl_config_bits (int | None) – Config-bit count declared by a hand-written HDL matrix. None for parsed matrices, whose no_config_bits is derived from connections instead.

Properties

property no_config_bits: int

Number of configuration bits required by this switch matrix.

Derived on demand from connections (so it tracks any change to them); a hand-written HDL matrix has no parsed connections and instead reports the count declared in its header (hdl_config_bits).

Methods

classmethod from_file(path, tile_name, ports=None, bels=None, preserve_list_order=False) → SwitchMatrix

Construct a SwitchMatrix by parsing the given source file.

The matrix is read once into its canonical form. A .csv is already canonical (its authored row/column order is kept). A .list is read into the canonical port/BEL signal order when ports is supplied, matching what the old bootstrap-CSV pipeline produced; without ports it falls back to raw .list order (connectivity only, order not canonical). When ports is supplied every connection is validated against the tile’s signals (both .csv and .list); without it no validation is possible. Hand-written HDL (.v/.sv/.vhdl/ .vhd) is an escape hatch: only its NumberOfConfigBits is read and connectivity is left empty.

Parameters:

• path (Path) – Path to the switch matrix file. Supported extensions: .csv, .list, .v, .sv, .vhdl, .vhd.

• tile_name (str) – Tile name, used only in the hand-written-HDL warning message.

• ports (list[Port] | None, optional) – Tile ports, required to canonicalise a .list matrix.

• bels (list[Bel] | None, optional) – Tile BELs, used to canonicalise a .list matrix.

• preserve_list_order (bool, optional) – When True, a .list’s mux inputs keep the file order (reversed, MSB-first) instead of the canonical dest-column order. Defaults to False.

Returns:

Fully initialised switch matrix instance.

Raises:

InvalidFileType – If the file extension is not recognised.

to_csv_file(path, tile_name) → None

Write the switch matrix connections to a .csv file.

The file is written in the format consumed by parseMatrix: the header row contains mux-input signal names (column headers), each data row is mux_output_port, v0, v1, ..., and comment annotations (#,count) are appended for human readability. Each mux input is encoded with a 1-based descending index (not a bare 1) so parseMatrix recovers the exact per-mux order regardless of the column arrangement, making a .list -> .csv -> .list round trip order-faithful.

Parameters:

• path (Path) – Destination .csv file. Created (or overwritten) by this call.

• tile_name (str) – Tile name written to the top-left cell of the CSV header.

to_list_file(path) → None

Write the switch matrix connections to a .list file.

One line per mux output in the compact form {N}mux_output,[input0|input1|...] where N is the number of mux inputs. The {N} multiplier repeats the output so parseList pairs it with each bracketed input. Outputs with no inputs are omitted.

The inputs are always written reversed (MSB-first), independent of preserve_list_order - the file always encodes the full order, and the reader decides how to interpret it: a preserve_list_order read recovers this exact order, while a plain read re-derives it from the tile’s ports.

Parameters:

path (Path) – Destination .list file. Created (or overwritten) by this call.

switch_matrix_signal_order(ports, bels) → tuple[list[str], list[str]]

Return the canonical (sources, dests) signal order for a switch matrix.

This is the ordering the switch matrix uses for its mux outputs (sources) and mux inputs (dests): non-JUMP wire signals first (in tile port order), then BEL signals, then JUMP wire signals, each de-duplicated first-seen. It depends only on the tile’s ports and BELs, so a .list matrix can be read straight into this canonical order without a CSV round trip.

Parameters:

• ports (list[Port]) – The tile’s ports (tile.portsInfo).

• bels (list[Bel]) – The tile’s BELs (tile.bels).

Returns:

(sources, dests) - the ordered, de-duplicated mux-output and mux-input signal names.