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.