Home » SSTDocumentation » SST New ELI Migration Guide

SST New ELI Migration Guide

SST New ELI Migration Guide
- Shared Documentation Macros
- Element Registration Macros

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<std::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:

class: Name of the class that is being registered. This should not be quoted, as it will be used in a template expansion.
library: String literal containing the name of the library.
name: String literal containing the name used to reference the component. The full name of the component will be library.name (example: if library = “merlin” and name = “hr_router”, then full name used to reference this element is “merlin.hr_router”).
version: Element version specified using the SST_ELI_ELEMENT_VERSION macro description: String literal containing a brief description of the component.
category: Value representing the category of this component. The definitions are found in elibase.h.

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:

class: Name of the class that is being registered. This should not be quoted, as it will be used in a template expansion.
library: String literal containing the name of the library.
name: String literal containing the name used to reference the subcomponent. The full name of the component will be library.name (example: if library = “merlin” and name = “linkcontrol”, then full name used to reference this element is “merlin.linkcontrol”).
version: Element version specified using the SST_ELI_ELEMENT_VERSION macro description: String literal containing a brief description of the subcomponent.
interface: String literal containing the fully qualified class name of the subcomponent that this class inherits from. Example: “SST::Interfaces::SimpleNetwork”.

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:

class: Name of the class that is being registered. This should not be quoted, as it will be used in a template expansion.
library: String literal containing the name of the library.
name: String literal containing the name used to reference the module. The full name of the component will be library.name (example: if library = “memHierarchy” and name = “memInterface”, then full name used to reference this element is “memHierarchy.memInterface”).
version: Element version specified using the SST_ELI_ELEMENT_VERSION macro description: String literal containing a brief description of the module.
interface: String literal containing the fully qualified class name of the subcomponent that this class inherits from. Example: “SST::Interfaces::SimpleMem”.

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:

class: Name of the class that is being registered. This should not be quoted, as it will be used in a template expansion.
library: String literal containing the name of the library.
name: String literal containing the name used to reference the partitioner. The full name of the component will be library.name (example: if library = “partitioners” and name = “simple”, then full name used to reference this element is “partitioners.simple”).
version: Element version specified using the SST_ELI_ELEMENT_VERSION macro
description: String literal containing a brief description of the partitioner.

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:

class: Name of the class that is being registered. This should not be quoted, as it will be used in a template expansion.
library: String literal containing the name of the library.
version: Element version specified using the SST_ELI_ELEMENT_VERSION macro

Example:

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