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 do 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.91.0, 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 showing 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.91.0/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.4’
--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 configures a CMake build tree in the current Simics project and builds the required SystemC libraries in 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:

CMake and Ninja to be available in PATH.
On Linux, 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
On Windows, Visual Studio with MSVC to be installed. The script auto-detects MSVC unless the compiler is already configured, for example by running from a Visual Studio developer shell.

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 1.91.0 headers, if checkpointing is enabled and Boost cannot be found automatically

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, GNU Make based module builds can re-use the generated libraries.

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 disables 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
D		enables the debug build of SystemC libs

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 libraries and SystemC modules are built with Visual C++ (provided with Visual Studio). The build script uses CMake and Ninja for the libraries, and auto-detects Visual Studio and the Windows SDK. It can be run from a regular PowerShell as long as cmake.exe and ninja.exe are in PATH.

project> bin\build-systemc-libraries.bat

If Visual Studio is installed in a non-standard location, set the CMake cache variables SIMICS_VS_INSTALL_DIR, SIMICS_MSVC_TOOLSET_DIR, SIMICS_WINSDK_DIR, or SIMICS_WINSDK_VERSION before configuring with CMake, or pass them as NAME=value arguments to the build script. If checkpointing or ISCTLM is enabled and Boost is not found automatically, provide the Boost header path with BOOST_INC_PATH.

Users building SystemC modules directly with CMake should configure a project with the Visual Studio auto-detect toolchain file and build the desired module target:

project> cmake -S . -B bt-systemc -G Ninja -D CMAKE_TOOLCHAIN_FILE=<simics-base>/cmake/simics/msvc-autodetect-toolchain.cmake
project> cmake --build bt-systemc --target my_sc_device

Running from a Visual Studio developer shell is also supported; in that case the toolchain file leaves the existing compiler environment alone.

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

9.6.1 Building the modules with GNU Make on Windows

Unlike the build script, GNU Make does not auto-detect Visual Studio. Select the Visual C++ compiler with CC=cl CXX=cl, and make sure the MSVC environment is set up, either by running Make from a Visual Studio developer shell:

project> bin\make.bat my_sc_device CC=cl CXX=cl

or, from any other shell, by pointing __VCVARS at the vcvars64.bat of the Visual Studio installation. Make then prefixes every compile command with it:

project> bin\make.bat my_sc_device CC=cl CXX=cl __VCVARS="C:\Program Files\Microsoft Visual Studio\2022\Professional\VC\Auxiliary\Build\vcvars64.bat"

The modules must be built with the same Visual Studio version as the SystemC libraries were, or the compile-time compiler version check fails. Since the build script picks the latest installed Visual Studio, __VCVARS must point at that same installation.

9.6.2 Length of the project path

Visual C++ cannot create an object file whose full path exceeds the Windows MAX_PATH limit of 260 characters, and reports it as:

fatal error C1083: Cannot open compiler generated file: '': Invalid argument

The deepest object path of the SystemC libraries needs about 150 characters below the project directory, so keep the path to the Simics project short; below 100 characters is recommended. Enabling long paths in Windows does not help, as the Visual C++ compiler is not long-path aware.

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, or by building the CMake systemc-deps-cache target directly
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