Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Ports

A component will have a number of ports which provide its interfaces to other components.

Output / Input

Ports can either be “output” or “input”. A connection must always be made between one output and one input port.

Data Types

The type of the port is specialised by the data type that it carries. Ports have to be of the same type to be connected together.

Component Ports

Components provide functions that allow the connection of their ports. Ports can either be connected directly to a component or to a subcomponent. It is therefore up to the component writer to provide the relevant functions and connect the ports as required.

Ports are commonly stored as RefCell<Option<InPort<T>>> or RefCell<Option<OutPort<T>>>. During setup, connection methods borrow the component through &self and connect the port state. When the component’s run() task starts, it takes the port out of the Option and owns it for the life of that task. Connectivity is checked separately when the task first uses the port. If the Option is already empty, the port has previously been taken, usually because run() was invoked more than once or ownership was transferred too early.

There are two forms of port connections: those that name a single port and those that take an index into a port array. Each function has a unique name based on the port name and the direction of data flow.

Input port functions are of the form port_<NAME> or port_<NAME>_i for ports that expose an array of connections. Output port functions are of the form connect_port_<NAME> and connect_port_<NAME>_i.

Some examples are provided below.

Input Ports

The method for an input port will return a shared reference to a shared state that is then passed to the output to complete the connection.

Here are a few examples:

A component with a single input port called rx will have:

use std::marker::PhantomData;
use gwr_engine::port::PortStateResult;
use gwr_engine::traits::SimObject;
struct TestBlock<T> { phantom: PhantomData<T> }
impl<T: SimObject> TestBlock<T> {
pub fn port_rx(&self) -> PortStateResult<T>
{ todo!() }
}
fn main() {}

A component with an array of input ports called in will have:

use std::marker::PhantomData;
use gwr_engine::port::PortStateResult;
use gwr_engine::traits::SimObject;
struct TestBlock<T> { phantom: PhantomData<T> }
impl<T: SimObject> TestBlock<T> {
pub fn port_in_i(&self, i: usize) -> PortStateResult<T>
{ todo!() }
}
fn main() {}

Output Ports

Output ports are connected by passing in the shared state that both sides of the interface use. If the port is already connected then a panic! will be raised.

A component with a single output port called tx will have:

use std::marker::PhantomData;
use gwr_engine::port::PortStateResult;
use gwr_engine::traits::SimObject;
use gwr_engine::types::SimResult;
struct TestBlock<T> { phantom: PhantomData<T> }
impl<T: SimObject> TestBlock<T> {
pub fn connect_port_tx(&self, port_state: PortStateResult<T>) -> SimResult
{ todo!() }
}
fn main() {}

A component with an array of output ports called out will have:

use std::marker::PhantomData;
use gwr_engine::port::PortStateResult;
use gwr_engine::traits::SimObject;
use gwr_engine::types::SimResult;
struct TestBlock<T> { phantom: PhantomData<T> }
impl<T: SimObject> TestBlock<T> {
pub fn connect_port_out_i(&self, i: usize, port_state: PortStateResult<T>) -> SimResult
{ todo!() }
}
fn main() {}

Connecting Ports

Connections are always made in the direction of flow of data (tx -> rx). For example:

use gwr_components::sink::Sink;
use gwr_components::source::Source;
use gwr_components::{connect_port, option_box_repeat};
use gwr_engine::engine::Engine;
fn main() {
let num_puts = 10;
let mut engine = Engine::default();
let clock = engine.default_clock();
let mut source = Source::new_and_register(&engine, engine.top(), "source", option_box_repeat!(0x123 ; num_puts));
let sink = Sink::new_and_register(&engine, &clock, engine.top(), "sink");
connect_port!(source, tx => sink, rx)
    .expect("should be able to connect `Source` to `Sink`");
}

Errors

If attempting to connect ports that don’t exist on the source/dest components then there will be a compile error.

use gwr_components::sink::Sink;
use gwr_components::source::Source;
use gwr_components::{connect_port, option_box_repeat};
use gwr_engine::engine::Engine;
fn main() {
let num_puts = 10;
let mut engine = Engine::default();
let clock = engine.default_clock();
let mut source = Source::new_and_register(&engine, engine.top(), "source", option_box_repeat!(0x123 ; num_puts));
let sink = Sink::new_and_register(&engine, &clock, engine.top(), "sink");
connect_port!(source, tx => sink, invalid)
    .expect("should be able to connect `Source` to `Sink`");
}

The Flaky component also provides an example of a custom component.