Building a Simics SystemC module using GNU Make is different than building a Simics module written in other languages. When you try to build a SystemC module, it might fail because the required libraries are missing.

project> bin/project-setup --sc-device=my_sc_device
project> make my_sc_device
=== Building module my_sc_device ===
<path to Simics SystemC Library Installation>/src/extensions/systemc-cci/systemc-config.mk:55: *** Unable to locate: CCI libs.  Stop.

This document provides information on the required libraries, how to build them, and the different build options.

Please see 8 for details on using CMake. With CMake the problems described in this chapter does not apply.

9.1 The SystemC Libraries

The SystemC libraries refer to a set of required static libraries (.a) to build a Simics SystemC device module. The exact set of libraries depends on the different build options. However, the minimal set of required libraries is libsystemc.a and libsystemc-library.a.

The libsystemc.a library contains the compiled object code for the SystemC kernel. It provides the implementation of the SystemC classes and functions.
The libsystemc-library.a library contains the compiled object code for the SystemC Library. It provides the implementation of the SystemC Library classes and functions.

These two libraries are required for all Simics SystemC modules. By default, USE_SIMICS_CCI is set to yes, thus the libcciapi.a library which provides the implementation of the SystemC CCI classes and functions is required as well.

When SystemC checkpointing is enabled by setting USE_SIMICS_CHECKPOINTING to yes, two additional libraries libcci_serialization.a and libsystemc-checkpoint.a are required.

The lack of a stable C++ ABI prevents these libraries from being shipped (as binaries) in the Simics package. Therefore, it is necessary to rebuild the libraries from source every time the Simics SystemC Library package is upgraded.

The following chapter describes how to build these SystemC libraries.

9.2 Build Requirement and Boost Dependency

The build requirement is covered in 2. The compiler needs to support the C++14 language standard. For maximum interoperability it is recommended to use either GCC 6.4.0 or 12.1.0 on Linux ; and MSVC 2022 on Windows. Other GCC and MSVC versions may work, but have not been fully tested.

9.2.1 Boost Dependency

There is no external dependency when building libraries libsystemc.a and libsystemc-library.a using the 9.4.

If Simics checkpointing is enabled by USE_SIMICS_CHECKPOINTING=yes, there is an external dependency on Boost C++ (www.boost.org). The Simics Serialization Library is a fork of Boost version 1.65.1, so only this version will work. The Boost C++ used in Simics SystemC Serialization is header-only, so there is no need to build and link with any Boost libraries.

If you are an Intel internal user, you may have different Boost dependencies. Please check the Intel SystemC Library Programming Guide for more details.

To let Simics know where Boost is installed, you need to define and export the BOOST_INC_PATH variable. This can be done by multiple ways as mentioned in 9.5. Here is an example shows how to set it in the config-user.mk file in your Simics project directory.

Variables set in config-user.mk must also be explicitly exported:
BOOST_INC_PATH ?= /home/packages/boost/1.65.1/include/
export BOOST_INC_PATH

It is not an error to provide both BOOST_INC_PATH and BOOST_PREFIX variables. If both are provided, BOOST_INC_PATH takes precedence.

9.3 Library Order

SystemC libraries have dependencies on each other and must be compiled in the right order before any SystemC devices can be built. Here is the recommended order for building the SystemC libraries:

SystemC Kernel
SystemC CCI (If not disabled by USE_SIMICS_CCI=no)
SystemC Serialization (If enabled by USE_SIMICS_CHECKPOINTING=yes)
SystemC Checkpoint (If enabled by USE_SIMICS_CHECKPOINTING=yes)
SystemC Library

To build all the libraries in the correct order and with the same compiler flags, it is recommended to invoke the build script from a Simics project. Please refer to 9.4 for more details.

9.4 Build Script

Simics provides a build script that simplifies the compilation of all the SystemC libraries within a Simics project. The script is located in the bin subdirectory of the Simics installation, and is invoked like this:

Usage

Windows

project> bin\build-systemc-libraries.bat [options]

Linux

project$ bin/build-systemc-libraries [options]

Options

-h, --help Show help message and exit.
-f, --force Force rebuild of all the libraries.
-j, --jobs Run up to N build jobs in parallel.
-v, --version Specify which version of SystemC kernel to use. Defaults to ‘2.3.3’
--verbose Run build with --verbose flag.
... The rest are parsed as make options for the modules. Please note that any option passed after the make options are interpreted as make options.

The script copies the necessary SystemC modules to the current Simics project and builds them in the correct dependency order. The required SystemC modules depend on the chosen build options, which are explained in detail in 9.5 section. These build options can be specified when invoking the script.

The build script expects:

CXX to be defined and exported to the shell that runs the build script. The build script can be embedded in a GNU Make target in which case CXX is resolved through the GNU Make build system.
If not embedded in GNU Make, the script must be invoked from the root of the Simics project
If run from MSVC, the script must run from an MSVC shell with CXX=cl

For improved support:

export SYSTEMC_KERNEL_VERSION to the kernel version needed
export VALGRIND_INCLUDE_DIR for valgrind support, if Valgrind wasn’t found automatically
set USE_SIMICS_CHECKPOINTING=yes to opt-in on the checkpointing support
set USE_SIMICS_CCI=no to opt-out of the CCI support
export BOOST_INC_PATH for Boost, which must be version 1.65.1 if checkpointing is enabled

project> ./bin/build-systemc-libraries CXX=/usr/itm/gcc/6.4.0/bin/g++
...
All SystemC libraries successfully built

Once the script has finished running, you can proceed to build other SystemC modules within the project.

project> make my_sc_device
=== Building module my_sc_device ===
...
CCLD    my_sc_device.so

Users can choose which SystemC kernel version to use for building the libraries by specifying the -v or --version option when executing the build script, or via the SYSTEMC_KERNEL_VERSION variable. The supported values are ‘2.3.3’, ‘2.3.4’ and ‘3.0.0’, with ‘2.3.3’ set as the default version. When using ‘3.0.0’, the SystemC checkpoint feature is not supported.

Users can optionally choose which C++ language standard to use for building the libraries by exporting the SYSTEMC_CXX_STANDARD variable. Supported values are ‘14’ and ‘17’. If not set, the standard setup by the Simics CMake top-level will be used. The SystemC kernel 3.0.0 must be built with C++17.

Whenever the Simics SystemC Library package is upgraded, the script must be run again with the --force option.

9.5 Build options

This section provides a list of GNU Make variables related to SystemC modules that are configured by the build script. These variables are generally identical for all SystemC modules. For information on common Simics Make variables, including CC and CXX, refer to Simics Makefile Variables.

Please note that this is only for GNU Make. See 8 for details on options when using CMake.

The following table displays the variable names, their default values, and their usage:

Variable name	Default value	Usage
BOOST_INC_PATH		Specifies the location of the Boost headers
INTC_EXT	1	enables or disable the Intel SystemC kernel extension
USE_SIMICS_CCI	‘yes’	enables or disables the Simics CCI feature
USE_SIMICS_CHECKPOINTING	‘no’	enables or disables the Simics checkpointing feature
SYSTEMC_KERNEL_VERSION		Selects the SystemC kernel version used in the project
SYSTEMC_CXX_STANDARD		Selects the C++ language standard used in the project

There are 3 ways to set these Make variables:

The user can set and export the variables in the config-user.mk file.
The variables can be provided as script parameters.
The variables can be set as shell environment variables.

The SYSTEMC_KERNEL_VERSION variable must be explicitly set to either ‘2.3.3’, ‘2.3.4’, or ‘3.0.0’ for the SystemC module, as it does not have a default value. If all modules within a project share the same version requirement, it can be specified in config-user.mk. However, it is preferable to define the version requirement for each module individually by setting SYSTEMC_KERNEL_VERSION=<version> in the respective Makefile.

9.6 Building on Windows

On Windows, SystemC modules can only be built using Visual C++ (provided with Visual Studio). In order to build SystemC modules using Visual C++, launch the Visual Studio Command Prompt (x64 version), configure the CC environment variable to use Visual C++ (‘cl’), and build your modules using bin\make.bat.

project> "<path to Visual Studio's vcvars64.bat"
project> set CC=cl
project> bin\make.bat

The module’s makefile will try to detect which Visual C++ version to use by inspecting the environment variables, set up by the corresponding Visual Studio Command Prompt. The version can be forced by setting MSVC_VERSION:

project> set MSVC_VERSION=msvc140
-- or --
project> set MSVC_VERSION=msvc170

Use of Visual Studio 2010 or 2013 is no longer supported, due to their lack of C++14 support.

Use of Visual Studio 2017 and 2019 is currently not supported, but it should be possible to manually convert the solution files and make it work; as it does work for Visual Studio 2022.

DML and C modules must use GCC/MinGW, so if there is a mix of DML/C and C++/SystemC models in the project, then it is necessary to build the targets separately.

Currently the host requires the “8.3 short filename”-support to be enabled in order for the GNU Make logic to work. See ‘fsutil 8dot3name’ on https://docs.microsoft.com for more details on how to query and enable this.

9.7 Errors When Building the SystemC Libraries

Many errors when building the SystemC libraries are caused by unresolved dependencies like Boost (see 9.2.1), or not following the particular order (see 9.3) to build the SystemC libraries. The best way to build all binaries in the correct order, is to invoke the build script from a Simics project. See 9.4 for more details.

The script must be run once again with –force option every time the Simics SystemC Library package is upgraded. If you failed to do this, you will probably see an undefined symbol error like this when loading your SystemC device module:

Undefined symbol: _ZN6simics7systemc16SCL_VERSION_5108C1Ev

The number 5108 shown in the error message depends on the SystemC Library version which may differ in real cases.

There are also compile-time checks that will take effect when compiling the Simics modules using the SystemC libraries. These checks verify that the libraries have been build with the same compiler as is used to build the Simics module.

9.8 Cached libraries

In order to save time when working in multiple Simics projects, building the libraries in each project can be avoided by using a cache. The build system supports this through the following scheme:

Build the libraries by running the build script in a project
Copy the libraries and the generated headers for the compile-time checks, i.e. everything under <host>/lib/systemc, to a shared location
Add the following to config-user.mk:
export SYSTEMC_DEPS_CACHE=<path to cache> Please note that the SYSTEMC_KERNEL_VERSION should not be part of the SYSTEMC_DEPS_CACHE
Build SystemC Simics modules using GNU Make as normal

8 Building with CMake 10 Migration Guide SystemC Kernel