sst-it 1.0.1

SST Interoperability Toolkit

SST Interoperability Toolkit

A toolkit to provide interoperability between Structural Simulation Toolkit (SST) and external hardware description languages (HDL).

Note: For the sake of simplicity and consistency in the nomenclature, the languages, toolkits or libraries in the following categories will be simply labeled as HDL:

• hardware description languages (SystemVerilog, Verilog, VHDL, etc.)
• hardware level modeling languages (Chisel, PyRTL, SystemC, etc.)

For interoperability with supported HDLs, see their corresponding README:

• PyRTL
• SystemC
• Verilog

Table of Contents

• Usage
  • Black Box Code Generation
  • Architecture
  • Tests
• Installation
  • sit
  • CMake
  • SST Core
• Requirements
  • Languages, Compilers and Libraries
  • Systems

Usage

Black Box Code Generation

To establish interoperability between an SST model and an HDL module, a black box SST component and HDL driver must be generated. The black box establishes the configurations required for the interprocess communication (IPC) between the SST and the external HDL processes.

The Python module sit can be used to generate the black boxes.

Architecture

The following is the directory structure of an example component demo using CMake.

demo/                     # project directory
├── generate_bbox.py      # sit code generating script
├── blackboxes/           # black box interface
│   ├── demo_comp.cpp     # SST black box component
│   └── demo_driver.hdl   # HDL black box driver
├── demo.cpp              # SST parent component
├── demo.hdl              # HDL module
├── build/                # CMake executables
├── CMakeLists.txt        # local CMakeLists for demo
├── tests/                # SST Python scripts
│   └── run.py            # sample SST Python scripts
├── .                     # other files
│   .
│   .

The following snippets demonstrate an SST link transmitting a unidirectional signal from the SST environment to the black box interface.

// demo/demo.cpp

// register a string event in the class declaration
SST_ELI_DOCUMENT_PORTS(
    { "demo_din", "Demo model data in", { "sst.Interfaces.StringEvent" }},
    ...
)

// initialize the link in the class declaration
SST::Link *demo_din;

// set up the SST link in the constructor
demo_din = configureLink("demo_din");

// trigger the event in the clocked function
demo_din->send(new SST::Interfaces::StringEvent(...));

// demo/blackboxes/demo_comp.cpp

// register the same string event in the class declaration
SST_ELI_DOCUMENT_PORTS(
    { "demo_din", "Demo model data in", { "sst.Interfaces.StringEvent" }},
    ...
)

// initialize the same link in the class declaration
SST::Link *demo_din;

// set up the SST link in the constructor with an event handler
demo_din = configureLink(
    "demo_din",
    new SST::Event::Handler<demo>(this, &demo::handle_event)
);

// receive and parse the event in the event handler
void demo::handle_event(SST::Event *ev) {
    auto *se = dynamic_cast<SST::Interfaces::StringEvent *>(ev);
    if (se) {
        std::string _data_in = se->getString();
        ...
    }
    delete ev;
}

Once the SST Links are established between the black box interface and the parent component, the project should be ready to interface the HDL process.

Tests

Simple unit tests can be ran by the Makefile in the tests directory.

Installation

The toolkit itself is a collection of static header files and can be installed as an interface using CMake.

mkdir build
cd build
cmake ..
sudo make install

The requirements for the project are listed below.

sit

The sit module can be installed locally by running pip:

mkdir -p $(sst-config --prefix)/include/sst/sit

cd $(sst-config --prefix)/include/sst/sit
pip install .

See Black Box Code Generation for its purposes.

CMake

CMake is used to build the requirements as well as the toolkit. It is possible to build the project with other build tools, but CMake makes project management extremely convenient. Instructions on installing CMake can be found here.

SST Core

The following snippet details instructions on installing SST Core in the project's home directory.

# make directory to manage all dependencies
mkdir -p deps
# initialize empty file for SST configurations
mkdir -p ~/.sst && touch ~/.sst/sstsimulator.conf

# install OpenMPI and its dependencies
sudo apt install libhwloc-dev libopenmpi-dev libtool-bin

curl -L ${SST_CORE_URL} | tar xz -C deps
cd deps/sstcore-* && ./configure && make -j all && sudo make install

Requirements

The following tables summarize the minimum versions of the languages and libraries used in the project.

Languages, Compilers and Libraries

Language	Version
C++	11
Python	3.6

C++ Compilers

Version	7.0	8.0	9.0	10.0
Clang	✔️	✔️	✔️	✔️
GCC	✔️	✔️	✔️	✔️

Library	Version
CMake	3.14
SST	10.0.0

Systems

Due to limitations with SST, this toolkit currently only works on UNIX systems. A list of supported Ubuntu Linux distributions can be found in .github/workflows/clang.yml and .github/workflows/gcc.yml.