SST New ELI Migration Guide

The new ELI for SST Version 7+ is contained in the header file sst/core/elementinfo.h. The API that will be supported going forward is made up of several macros. The way these macros are to be used to ensure future compatibility is documented here.

The macros are to be included in the definition of the class that implements the element. For consistency, these should be put as the first items in the class definition, and in all cases, must be put in a public section of the class.

Shared Documentation Macros


The following macros are used by multiple elements to document various features. Please note that a semicolon is not required after the macro call, but it will compile if supplied. Also, each element must call all macros that apply to it. If the element does not use a particular feature, the macro can be omitted or called with empty arguments.

Parameters


Available for: Components, SubComponents, Modules

Elements that have a Params object passed to them must document the parameters that will be used. This is done with the following macro:

SST_ELI_DOCUMENT_PARAMS(...)

A list of parameters is supplied to the macro and each parameter entry is defined by a triple of string literals, using the static initialization syntax:

{ “name”, “description”, “default value” }

If default value is entered as NULL, then there is no default and the parameter is required.

Examples:

SST_ELI_DOCUMENT_PARAMS(
    { “param1”, “first parameter”, NULL }, // required parameter
    { “param2”, “second parameter”, “1” }, // default value of 1 
)

SST_ELI_DOCUMENT_PARAMS() // No parameters (or call may be omitted)

Statistics


Available for: Components, SubComponents

Components and SubComponents must document their available statistics using the following macro:

SST_ELI_DOCUMENT_STATISTICS(...)

A list of available statistics is supplied to the macro and each statistic entry is defined using the following static initialization syntax:

{ “name”, “description”, “units”, enable level }

Where name, description and units are string literals and enable level is an integer.

Examples:

SST_ELI_DOCUMENT_STATISTICS(
    { “stat1”, “First statistic”, “unit”, 1 },
    { “stat2”, “Second statistic”, “unit”, 1} 
)

SST_ELI_DOCUMENT_STATISTICS() // No statistics supplied (or call may be omitted)

Ports


Available for: Components, SubComponents

Components and SubComponents must specify their ports using the following macro:

SST_ELI_DOCUMENT_PORTS(...)

A list of available ports is supplied to the macro and each statistic entry is defined using the following static initialization syntax:

{ “name”, “description”, vector of supported events }

Where name and description are string literals and “vector of supported events” is a std::vector<:string> of the names of supported event types, usually initialized as { “lib1.event1”, “lib1.event2”, “lib2.event3” }.

Examples:

SST_ELI_DOCUMENT_PORTS(
    { “port1”, “First port”, {“lib1.event1”, “lib1.event2”} }, 
    { “port2”, “Second port”, {“lib2.event3”} }
)

SST_ELI_DOCUMENT_PORTS() // No ports (or call may be omitted)

SubComponent Slots


Available for: Components, SubComponents

Components and SubComponents must specify their available SubComponentSlots using the following macro:

SST_ELI_DOCUMENT_SUBCOMPONENT_SLOTS(...)

A list of available SubComponentSlots is supplied to the macro and each entry is defined by a triple of string literals using static initialization syntax:

{ “slotname”, “description”, “name of superclass” }

Where the name of the superclass is specified as the fully qualified classname (for example “SST::ElementLibrary::SubComponentClass”). This is class that defines the API used by the slot. The superclass must inherit from SubComponent and any element attached to this slot must inherit from the superclass.

Examples:

SST_ELI_DOCUMENT_SUBCOMPONENT_SLOTS(
    { “slot1”, “First slot”, “SST::Core::Interfaces::SimpleNetwork” },
    { “slot2”, “Second slot”, “SST::Core::Interfaces::SimpleMem” } 
)

SST_ELI_DOCUMENT_SUBCOMPONENT_SLOTS() // No slots (or call may be omitted)



Element Registration Macros


The following macros are used to register specific element types. In each call, the version of the element is specified using the SST_ELI_ELEMENT_VERSION(primary, secondary, tertiary) macro.

Component


Components must inherit from the core class Component defined in sst/core/component.h. To register a Component with the ELI database, use the following macro:

SST_ELI_REGISTER_COMPONENT(class, “library”, “name”, version, “description”, category)

Where the parameters are:

Example:

SST_ELI_REGISTER_COMPONENT(hr_router, “merlin”, “hr_router”, 
SST_ELI_ELEMENT_VERSION(1,0,0), “High radix router model”, 
COMPONENT_CATEGORY_NETWORK)`

SubComponent


SubComponents must inherit from the core class SubComponent defined in sst/core/subcomponent.h, or must inherit from another class derived from SubComponent. To register a SubComponent with the ELI database, use the following macro:

SST_ELI_REGISTER_SUBCOMPONENT(class, “library”, “name”, version, “description”, “interface”)

Where the parameters are:

Example:

SST_ELI_REGISTER_SUBCOMPONENT(LinkControl, “merlin”, “linkcontrol”, 
SST_ELI_ELEMENT_VERSION(1,0,0), “Link Control module for building Merlin-enabled NICs", 
"SST::Interfaces::SimpleNetwork")

Module


Modules must inherit from the core class Module defined in sst/core/module.h, or must inherit from another class derived from Module. To register a Module with the ELI database, use the following macro:

SST_ELI_REGISTER_MODULE(class, “library”, “name”, version, “description”, “interface”)

Where the parameters are:

Example:

SST_ELI_REGISTER_SUBCOMPONENT(MemHierarchyInterface, “memHierarchy”, “memInterface”, 
SST_ELI_ELEMENT_VERSION(1,0,0), "Simplified interface to Memory Hierarchy", 
"SST::Interfaces::SimpleMem")

Partitioner


Partitioners must inherit from the SSTPartitioner class defined in sst/core/part/sstpart.h. To register a Partitioner with the ELI database, use the following macro:

SST_ELI_REGISTER_PARTITIONER(class, “library”, “name” , version, “description”)

Where the parameters are:

Example:

SST_ELI_REGISTER_Partitioner(SimplePart, “partitioners”, “simple”, 
SST_ELI_ELEMENT_VERSION(1,0,0), 
"Simple partitioner")

Python Module


Python Modules must inherit from the SSTElementPythonModule class defined in sst/core/model/element_python.h. Python Modules allow libraries to add functionality to the python configuration system. The functionality can be accessed by using “from sst.libname import *” in python configuration files. To register a Python Module with the ELI database, use the following macro:

SST_ELI_REGISTER_PYTHON_MODULE(class, “library”, version)

Where the parameters are:

Example:

SST_ELI_REGISTER_Partitioner(MerlinPyModule, “merlin”, 
SST_ELI_ELEMENT_VERSION(1,0,0))