Metadata

Metadata are needed to serve different goals:

• automatically build modules,
• describe modules to automated netlisters,
• provide sideband information about the modules.

Concepts

A module is either an actual component, or an utility (a pure C++ class, a port definition, etc.) needed in a platform.

Each module is accompanied by a metadata file, which contains all information to satisfy goals.

A module description can evolve to different stages:

• Module
• Specialization
• ComponentBuilder

Il we try to wrap-up, life of a module in soclib_desc can be summarized in this picture:

We will describe these stages below.

Module

A Module is the module description, in an abstract way.

The sole module description is not enough to compile it. If this is a SystemC (C++) module, it may have some template parameters which change the template instanciation. Therefore, user must provide the template parameters to the build system in order to compile the module’s code. This is the role of the specialization.

Module definition contains the objective description of the module, with a set of attributes:

• name
• source files
• parameters (compile-time and run-time)
• ports (if it is a module). Sometimes, ports depends on parameters.
• needed modules, used as sub-modules. Most of the time, they are parameterized.
• other side-band data.

Complete API implemented by modules is described in ModuleInterface.

Specialization

With addition of template parameters, a module description can evolve into a Specialization. Specialization is a module definition with fixed template parameters. This permits:

• to enumerate the sub-modules with their own parameters (i.e. a list of submodule Specializations.
• to enumerate ports of the module, with fixed widths, il applicable
• to enumerate instance parameters
• to retrieve entity name (C++ class name, or VHDL entity)
• to cast a ComponentBuilder, which is able to build the needed source files and obtain object files.

Complete API implemented by specializations is described in SpecializationInterface.

ComponentBuilder

The builder is the last thing you can obtain with module descriptions. It is able to generate BBlock and associated Action objects of soclib_builder.

Complete API implemented by component builders is described in ComponentBuilderInterface.

Module Index

Upon initialization, soclib_desc scans the directories defined in metadata paths. All found modules declarations are gathered in a global database: the module index.

The module index contains all defined modules, whatever the metadata parser module that provided their definition. The index is keyed by the name of the component. See soclib-cc -l for index listing.

For better performance and lower startup times, the index is cached. See soclib-cc -X for cache cleaning.

Metadata providers

Metadata providers are soclib-cc plugins able to extract metadata from files (or other means). With soclib-cc comes a built-in metadata provider: the .sd file format.

Metadata providers are Python modules implementing the soclib_desc.metadata_file.MetadataFile protocol, and must be registered from Configuration files with config.add_desc_parser().

Metadata paths

Metadata files can be searched anywhere in the filesystem. Sepcified directories are searched recursively.

Default configuration searches for modules in the soclib installation (soclib/module/, soclib/communication/, soclib/iss/, soclib/lib/), and also in the current directory (where soclib-cc is executed).

Users can add new filesystem trees to index through the command line, with soclib-cc -I, or through the Configuration files with config.addDescPath().