gwr_models/fabric/

routed.rs

// Copyright (c) 2025 Graphcore Ltd. All rights reserved.

//! A functional implementation of a fabric with very basic timing.
//!
//! Assumes that all traffic will move a Manhattan distance through the fabric
//! to get from ingress to egress.
//!
//! The fabric is assumed to be rectangular with a configurable `num_columns`
//! and `num_rows`. The grid has a configurable number of ports at each node
//! within the fabric grid.
//!
//! # Ports
//!
//! Each point in the fabric grid (col, row) has N ingress and egress ports:
//!  - N [ingress ports](gwr_engine::port::InPort): `ingress[col][row][0, N-1]`
//!  - N [egress ports](gwr_engine::port::OutPort): `egress[col][row][0, N-1]`
//!
//! In order to connect to the fabric use the
//! `col_row_port_to_fabric_port_index()` function in the configuration
//! structure to get the index of the port you want to connect to.

use std::rc::Rc;

use async_trait::async_trait;
use gwr_components::delay::Delay;
use gwr_components::{connect_dummy_rx, connect_dummy_tx, connect_port};
use gwr_engine::engine::Engine;
use gwr_engine::port::PortStateResult;
use gwr_engine::sim_error;
use gwr_engine::time::clock::Clock;
use gwr_engine::traits::{Routable, SimObject};
use gwr_engine::types::{SimError, SimResult};
use gwr_model_builder::{EntityDisplay, EntityGet, Runnable};
use gwr_track::entity::Entity;
use gwr_track::tracker::aka::{Aka, populate_aka_from_string};

use crate::fabric::node::{FabricNode, FabricRoutingAlgorithm};
use crate::fabric::{Fabric, FabricConfig};

#[derive(EntityGet, EntityDisplay, Runnable)]
pub struct RoutedFabric<T>
where
    T: SimObject + Routable,
{
    entity: Rc<Entity>,
    nodes: Vec<Vec<Rc<FabricNode<T>>>>,
    config: Rc<FabricConfig>,
}

fn build_node_aka(
    entity: &Rc<Entity>,
    aka: Option<&Aka>,
    new_aka: &mut Aka,
    col: usize,
    row: usize,
    config: &Rc<FabricConfig>,
) {
    let mut renames = Vec::new();
    for port in 0..config.num_ports_per_node() {
        let fabric_port_index = config.col_row_port_to_fabric_port_index(col, row, port);
        renames.push((
            format!("ingress_{fabric_port_index}"),
            format!("ingress_{port}"),
        ));
        renames.push((
            format!("egress_{fabric_port_index}"),
            format!("egress_{port}"),
        ));
    }
    populate_aka_from_string(aka, Some(new_aka), entity, &renames);
}

type FabricNodesResult<T> = Result<Vec<Vec<Rc<FabricNode<T>>>>, SimError>;

fn create_nodes<T>(
    engine: &Engine,
    clock: &Clock,
    entity: &Rc<Entity>,
    aka: Option<&Aka>,
    config: &Rc<FabricConfig>,
    fabric_algorithm: FabricRoutingAlgorithm,
) -> FabricNodesResult<T>
where
    T: SimObject + Routable,
{
    let num_columns = config.num_columns();
    let num_rows = config.num_rows();
    let mut nodes = Vec::with_capacity(num_columns);

    for c in 0..num_columns {
        let mut col_nodes = Vec::with_capacity(num_rows);
        for r in 0..num_rows {
            let mut new_aka = Aka::default();
            build_node_aka(entity, aka, &mut new_aka, c, r, config);
            let node = FabricNode::new_and_register_with_renames(
                engine,
                clock,
                entity,
                &format!("node_{c}_{r}"),
                Some(&new_aka),
                c,
                r,
                config,
                fabric_algorithm,
            )?;
            col_nodes.push(node);
        }
        nodes.push(col_nodes);
    }
    Ok(nodes)
}

/// Create connections between columns
fn connect_columns<T>(
    engine: &Engine,
    clock: &Clock,
    entity: &Rc<Entity>,
    config: &Rc<FabricConfig>,
    nodes: &[Vec<Rc<FabricNode<T>>>],
    delay_ticks: usize,
) where
    T: SimObject + Routable,
{
    for c in 1..config.num_columns {
        let c_m1 = c - 1;
        // Clippy suggestion to avoid needless_range_loop results in an unused
        // variable from the iterator and therefore a larger refactor is likely
        // required here. There may be hazards to be aware of when attempting
        // to resolve this, such as highlighted in
        // https://github.com/rust-lang/rust-clippy/issues/16344.
        #[expect(clippy::needless_range_loop)]
        for r in 0..config.num_rows {
            let delay = Delay::new_and_register(
                engine,
                clock,
                entity,
                &format!("{c_m1}_{r}_to_{c}_{r}"),
                delay_ticks,
            );
            connect_port!(nodes[c_m1][r], col_plus => delay, rx)
                .expect("Internal ports should connect without error");
            connect_port!(delay, tx => nodes[c][r], col_minus)
                .expect("Internal ports should connect without error");

            let delay = Delay::new_and_register(
                engine,
                clock,
                entity,
                &format!("{c}_{r}_to_{c_m1}_{r}"),
                delay_ticks,
            );
            connect_port!(nodes[c][r], col_minus => delay, rx)
                .expect("Internal ports should connect without error");
            connect_port!(delay, tx => nodes[c_m1][r], col_plus)
                .expect("Internal ports should connect without error");
        }
    }
}

/// Create connections between rows
fn connect_rows<T>(
    engine: &Engine,
    clock: &Clock,
    entity: &Rc<Entity>,
    config: &Rc<FabricConfig>,
    nodes: &[Vec<Rc<FabricNode<T>>>],
    delay_ticks: usize,
) where
    T: SimObject + Routable,
{
    for (c, col) in nodes.iter().enumerate() {
        for r in 1..config.num_rows {
            let r_m1 = r - 1;
            let delay = Delay::new_and_register(
                engine,
                clock,
                entity,
                &format!("{c}_{r_m1}_to_{c}_{r}"),
                delay_ticks,
            );
            connect_port!(col[r_m1], row_plus => delay, rx)
                .expect("Internal ports should connect without error");
            connect_port!(delay, tx => col[r], row_minus)
                .expect("Internal ports should connect without error");

            let delay = Delay::new_and_register(
                engine,
                clock,
                entity,
                &format!("{c}_{r}_to_{c}_{r_m1}"),
                delay_ticks,
            );
            connect_port!(col[r], row_minus => delay, rx)
                .expect("Internal ports should connect without error");
            connect_port!(delay, tx => col[r_m1], row_plus)
                .expect("Internal ports should connect without error");
        }
    }
}

/// Connect up the edge ports that will otherwise be left dangling
fn create_dummy_ports<T>(
    engine: &Engine,
    clock: &Clock,
    entity: &Rc<Entity>,
    config: &Rc<FabricConfig>,
    nodes: &[Vec<Rc<FabricNode<T>>>],
) where
    T: SimObject + Routable,
{
    // Connect dummy ports left/right
    let right = config.num_columns - 1;
    // Clippy suggestion to avoid needless_range_loop doesn't account for the
    // way nodes is accessed, i.e. nodes[0][r] and nodes[right][r] and therefore
    // a larger refactor is likely required here.
    #[expect(clippy::needless_range_loop)]
    for r in 0..config.num_rows {
        connect_dummy_tx!(entity => nodes[0][r], col_minus)
            .expect("Internal ports should connect without error");
        connect_dummy_rx!(nodes[0][r], col_minus => engine, clock, entity)
            .expect("Internal ports should connect without error");
        connect_dummy_tx!(entity => nodes[right][r], col_plus)
            .expect("Internal ports should connect without error");
        connect_dummy_rx!(nodes[right][r], col_plus => engine, clock, entity)
            .expect("Internal ports should connect without error");
    }

    // Connect dummy ports top/bottom
    let bottom = config.num_rows - 1;
    for col in nodes {
        connect_dummy_tx!(entity => col[0], row_minus)
            .expect("Internal ports should connect without error");
        connect_dummy_rx!(col[0], row_minus => engine, clock, entity)
            .expect("Internal ports should connect without error");
        connect_dummy_tx!(entity => col[bottom], row_plus)
            .expect("Internal ports should connect without error");
        connect_dummy_rx!(col[bottom], row_plus => engine, clock, entity)
            .expect("Internal ports should connect without error");
    }
}

impl<T> RoutedFabric<T>
where
    T: SimObject + Routable,
{
    pub fn new_and_register_with_renames(
        engine: &Engine,
        clock: &Clock,
        parent: &Rc<Entity>,
        name: &str,
        aka: Option<&Aka>,
        config: Rc<FabricConfig>,
        fabric_algorithm: FabricRoutingAlgorithm,
    ) -> Result<Rc<Self>, SimError> {
        let entity = Rc::new(Entity::new(parent, name));
        let num_ports = config.num_columns * config.num_rows * config.num_ports_per_node;
        if num_ports < 2 {
            return sim_error!("Cannot create fabric with less than 2 ports");
        }

        let nodes = create_nodes(engine, clock, &entity, aka, &config, fabric_algorithm)?;
        connect_columns(
            engine,
            clock,
            &entity,
            &config,
            &nodes,
            config.cycles_per_hop,
        );
        connect_rows(
            engine,
            clock,
            &entity,
            &config,
            &nodes,
            config.cycles_per_hop,
        );
        create_dummy_ports(engine, clock, &entity, &config, &nodes);

        let rc_self = Rc::new(Self {
            entity,
            nodes,
            config,
        });

        engine.register(rc_self.clone());
        Ok(rc_self)
    }

    pub fn new_and_register(
        engine: &Engine,
        clock: &Clock,
        parent: &Rc<Entity>,
        name: &str,
        config: Rc<FabricConfig>,
        fabric_algorithm: FabricRoutingAlgorithm,
    ) -> Result<Rc<Self>, SimError> {
        Self::new_and_register_with_renames(
            engine,
            clock,
            parent,
            name,
            None,
            config,
            fabric_algorithm,
        )
    }
}

impl<T> Fabric<T> for RoutedFabric<T>
where
    T: SimObject + Routable,
{
    fn connect_port_egress_i(&self, i: usize, port_state: PortStateResult<T>) -> SimResult {
        let (c, r, p) = self.config.fabric_port_index_to_col_row_port(i);
        self.nodes[c][r].connect_port_egress_i(p, port_state)
    }

    fn port_ingress_i(&self, i: usize) -> PortStateResult<T> {
        let (c, r, p) = self.config.fabric_port_index_to_col_row_port(i);
        self.nodes[c][r].port_ingress_i(p)
    }

    fn col_row_port_to_fabric_port_index(&self, col: usize, row: usize, port: usize) -> usize {
        self.config
            .col_row_port_to_fabric_port_index(col, row, port)
    }
}