8 Building Required Libraries

Building a Simics SystemC module 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 Base 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.

8.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 Base package is upgraded.

The following chapter describes how to build these SystemC libraries.

8.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 GCC 6.3.0. On Linux, other GCC versions may work, but only GCC 6.3.0 is used in the Simics regression tests.

8.2.1 Boost Dependency

There is no external dependency when building libraries libsystemc.a and libsystemc-library.a using the (build script)[#build-script].

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.

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 8.5. Here is an example shows how to set it in the config-user.mk file in your Simics project directory.

BOOST_INC_PATH ?= /home/packages/boost/1.65.1/include/
export BOOST_INC_PATH

8.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:

1. SystemC Kernel
2. SystemC CCI (If not disabled by USE_SIMICS_CCI=no)
3. SystemC Serialization (If enabled by USE_SIMICS_CHECKPOINTING=yes)
4. SystemC Checkpoint (If enabled by USE_SIMICS_CHECKPOINTING=yes)
5. 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 8.4 for more details.

Alternatively, you can build all the modules manually following the above order. Keep in mind that due to library dependencies, if one library is rebuilt with different compile flags, all the libraries that depend on it should also be rebuilt using the same compiler flags. Please refer to 8.6 for more details.

8.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:

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 8.5 section. These build options can be specified when invoking the script.

It is recommended to configure the Make variable CC and CXX instead of relying on the default system compiler. By default, on Linux, the build script builds the following libraries if no additional Make variables are provided:

project> ./bin/build-systemc-libraries CC=/usr/itm/gcc/6.3.0/bin/gcc CXX=/usr/itm/gcc/6.3.0/bin/g++
Building:
systemc-kernel            |################################| 100%
systemc-cci               |################################| 100%
systemc-library           |################################| 100%

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

8.5 Build options

This section provides a list of 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 x.

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_NO_UNITTESTS | 1 | enables or disables the Simics libraries unittest |

There are 3 ways to set these Make variables:

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

8.6 Build libraries manually

This section contains build instructions for the individual SystemC libraries. The best way to build them is to run the build script. See 8.4 for details.

Reduce the compilation times of SystemC libraries by setting the SYSTEMC_NO_UNITTESTS variable. When set, no unit tests are compiled and run for those libraries that contain them.

8.6.1 Building SystemC Kernel

In order to run SystemC models in Simics, the Simics SystemC Kernel must be used.

8.6.1.1 How To Build SystemC Kernel

SystemC Kernel is built from a Simics Project. When building on Microsoft* Windows*, Microsoft Visual Studio 2015 is also required. These are the steps to build SystemC Kernel from a Simics Project:

8.6.1.1.1 Building On Linux

project> bin/project-setup --copy-module=systemc-kernel

project> make systemc-kernel

8.6.1.1.2 Building On Microsoft Windows

Start a Visual Studio command prompt and change directory to the project.

project> bin\project-setup --copy-module=systemc-kernel

project> bin\make systemc-kernel

You will need to set the CC to point to the Visual C++ compiler. See 8.7 for more details.

8.6.2 Building the Simics Serialization Library

Simics Serialization Library is a fork of Boost Serialization, which provides extended serialization support to be used with SystemC Checkpoint Library.

To build Simics Serialization Library from source:

project> bin/project-setup --copy-module=systemc-serialization

project> make systemc-serialization

Simics Serialization Library requires Boost; see 8.2.1 for more details.

8.6.3 Building SystemC Checkpoint Library

SystemC Checkpoint Library depends on Simics Serialization Library and SystemC Kernel. Please see 8.6.2 and 8.6.1 for more details. SystemC Checkpoint Library is used by SystemC Library to provide checkpointing support, but it can also be used on its own. See the SystemC Checkpoint Library Programming Guide for more details.

To build Checkpoint Library from source:

project> bin/project-setup --copy-module=systemc-checkpoint

project> make systemc-checkpoint

See 8.6.4 for using a different compiler, and 8.7 for building on Windows.

SystemC Checkpoint Library requires Boost, see 8.2.1 for more details.

8.6.4 Building SystemC Library

SystemC Library is distributed as source code, and must be compiled together with the other SystemC components including the device modules using the same toolchain.

To build Simics SystemC Library from source:

project> bin/project-setup --copy-module=systemc-library

project> make systemc-library

This will use the default compiler of the system. To use a different compiler, set the CC and CXX flags:

project> CC=/usr/itm/gcc/6.3.0/bin/gcc CXX=/usr/itm/gcc/6.3.0/bin/g++ make systemc-library

It is also possible to set the CC and CXX flags in the config-user.mk file, like this:

CC = /usr/itm/gcc/6.3.0/bin/gcc
CXX = /usr/itm/gcc/6.3.0/bin/g++

The SystemC Library unit tests require Boost. See 8.2.1 for more details.

8.7 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  

8.8 Errors When Building the SystemC Libraries

Many errors when building the SystemC libraries are caused by unresolved dependencies like Boost (see 8.2.1), or not following the particular order (see 8.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 8.4 for more details.

The script must be run once again with --force option every time the Simics Base 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

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.

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

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