Getting started

This page explains building and installation of ICSC on any Linux OS. In the following description Ubuntu 22.04 is used, all operations are done in bash terminal.

ICSC is based on Clang/LLVM tool chain. It uses Google Protobuf library and patched SystemC library. Patched SystemC sources are uploaded into ICSC repository.

There are two ways to first install ICSC:

Installation with install.sh script -- checked for SLES12, Ubuntu 22.04 and Ubuntu 20.04
Installation with install2.sh script to install into specified folder separate from the sources
Manual installation

To rebuild and install ICSC after update (git pull):

Rebuild script install_icsc.sh

Prepare to installation

ICSC can be installed at any Linux OS with:

Any C++ compiler supports C++17
CMake version 3.13 or later
git to clone ICSC repository

Default Ubuntu 20.04/22.04 C++ compiler is g++ 9.3.0/11.3.0 that works fine. Default Ubuntu 20.04/22.04 CMake version is 3.16/3.22 that works fine.

Initial step before installation is to setup some folder as $ICSC_HOME and clone ISCS source repository to $ICSC_HOME/icsc:

$ export ICSC_HOME=/home/username/sc_tools     ## where /home/username is your home folder
$ git clone https://github.com/intel/systemc-compiler $ICSC_HOME/icsc

If you are using WSL, use a native Linux disk, NOT a Windows disk (e.g., use /home/username/projects/ instead of /mnt/C/somefolder/).

After clone before installation there is the following folder structure:

 $ICSC_HOME
   * icsc      
        * cmake           -- CMake files
        * components      -- assertions, fifo and other library components
        * designs         -- folder for user designs with an design template
        * doc             -- user guide latex and pdf files
        * examples        -- a few illustrative examples 
        * sc_elab         -- elaborator sources 
        * sc_tool         -- ISCS sources  
        * systemc         -- patched SystemC 2.3.3 sources
        * tests           -- unit tests 
        * .gitmodules     -- not intended to be used here, can be removed
        * CMakeLists.txt  -- Cmake file for ICSC tool
        * LICENSE.txt     -- Apache 2.0 WITH LLVM exceptions license
        * README.md       -- Tool description
        * install.sh      -- Installation script
        * install_icsc.sh -- Rebuild script after update from the repository

First installation with install.sh

The install.sh script contains all the stages of manual installation, that includes generating SystemVerilog code for examples. install_icsc.sh does download, build and installation Protobuf, Clang/LLVM, gdb (optional), after that it does build and installation of ICSC in release and debug modes. All the includes and libraries are installed into folder specified with $ICSC_HOME environment variable, which should be set up before.

Open bash terminal and run icsc/install.sh from $ICSC_HOME folder:

$ cd $ICSC_HOME           
$ icsc/install.sh                   ## download and install all required components
$ cd $ICSC_HOME
$ source setenv.sh                  ## setup PATH and LD_LIBRARY_PATH

Tool is ready to use.

The install.sh has an option gdb to download and build gdb 11.2 with Python3 which required for SystemC pretty printers. If system default gdb does not work with pretty printers well, this option could be used:

$ icsc/install.sh gdb               ## run install with gdb build

Before using the installed tool in a new terminal it needs to run setenv.sh:

$ cd $ICSC_HOME
$ source setenv.sh                  ## setup PATH and LD_LIBRARY_PATH

Release and debug mode for user design is supported with two version of SystemC library installed:

systemc.so for release mode,
systemcd.so for debug mode.

Using debug mode allows to see SystemC channels and data type variables in debug session with gdb with the pretty-printers provided.

Rebuild and installation after update

To rebuild and install ICSC after update in the folder where it already installed:

install_icsc.sh could be used instead of instal.sh.

Attention: in Version 1.6.9 Clang/LLVM version updated to 18.1.8 that requires full installation as described above.

Open bash terminal and run icsc/install_icsc.sh from $ICSC_HOME folder:

$ cd $ICSC_HOME           
$ source setenv.sh                  ## setup PATH and LD_LIBRARY_PATH
$ icsc/install_icsc.sh              ## rebuild and install ICSC libraries

install_icsc.sh does build ICSC libraries and installation in $ICSC_HOME folder. It works faster than install.sh which additionally does build and installation of all the dependencies.

First installation with install2.sh

Reason

In some environments, the system admin may require the installed files to be separate from the source code. The install2.sh script allows one to set the install prefix, as well as specifying per-package CMAKE_BUILD_TYPE.

Quick start

$ ./install2.sh /tmp/icsc llvm proto icsc

Usage

$ ./install2.sh <install prefix> [--debug|--release|--rel-debug] [--download] [proto] [llvm] [gdb] [icsc] [examples]

The --debug/--release switches can be placed before any of the packages (proto, llvm, gdb, icsc), and they can be mixed on one command line:

$ ./install2.sh /tmp/icsc --release llvm --debug proto icsc

This example will install to /tmp/icsc. It will download, compile and install release versions of LLVM. It will download, compile and install debug versions of Protobuf. It will compile and install both debug and release versions of ICSC.

The ICSC package is always compiled as both Release and Debug, with d library postfix for the debug libraries.

The script will not download a package a second time, unless --download is also specified. Not that all of the switches (--debug, --release, --rel-debug, --download) take effect on all packages following it. The script will mind the correct build order (llvm + protobuf + gdb first, then icsc). You can omit packages already compiled.

Manual installation

Preparing dependencies

It needs to have:

Protobuf version 3.19.4 or later, can be downloaded from https://github.com/protocolbuffers/protobuf/releases
LLVM 18.1.8 and Clang 18.1.8, can be downloaded from https://releases.llvm.org/download.html#18.1.8

Download Protobuf, LLVM and Clang into $ICSC_HOME folder.

Building and installing Protobuf

Download Protobuf version 3.19.4 or later from https://github.com/protocolbuffers/protobuf/releases into $ICSC_HOME folder.

$ cd $ICSC_HOME/protobuf-3.19.4
$ mkdir build && cd build
$ cmake ../cmake/ -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$ICSC_HOME -DBUILD_SHARED_LIBS=ON 
                  -Dprotobuf_BUILD_TESTS=OFF -DCMAKE_CXX_STANDARD=17
$ make -j8
$ make install

Building and installing LLVM/Clang

Download LLVM 18.1.8, Clang 18.1.8 and Cmake 18.1.8 from https://releases.llvm.org/download.html#18.1.8 into $ICSC_HOME/build_deps folder.

$ cd $ICSC_HOME/build_deps
$ mv clang-18.1.8.src clang
$ mv cmake-18.1.8.src cmake
$ cd llvm-18.1.8.src
$ mkdir build -p && cd build
$ cmake ../ -DLLVM_ENABLE_ASSERTIONS=ON -DLLVM_TARGETS_TO_BUILD=X86 
            -DLLVM_ENABLE_PROJECTS=clang -DCMAKE_BUILD_TYPE=Release -G "Unix Makefiles" 
            -DCMAKE_INSTALL_PREFIX=$ICSC_HOME -DGCC_INSTALL_PREFIX=$GCC_INSTALL_PREFIX 
            -DCMAKE_CXX_STANDARD=17 -DLLVM_INCLUDE_BENCHMARKS=OFF -DLLVM_INCLUDE_TESTS=OFF
$ make -j8
$ make install

Building and installing ICSC

For release build use -fno-tree-vectorize to avoid bug in g++ 10.x and g++ 11.x. This is specified in the project CMakeLists.txt.

$ cd $ICSC_HOME/icsc
$ mkdir build && cd build
$ cmake ../ -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$ICSC_HOME -DCMAKE_CXX_STANDARD=17
$ make -j8
$ make install

Folders and files after installation

After installation there is the following folder structure:

 $ICSC_HOME
   * bin                 -- binary utilities, can be removed
   * build               -- build folder where examples, tests and user designs are built
   * designs             -- folder for examples, tests and user designs with an design template
   * icsc                -- ICSC sources
        * build          -- build folder, can be removed        
        * cmake          -- CMake files
        * components     -- assertions, fifo and other library components
        * doc            -- user guide latex and pdf files
        * sc_elab        -- elaborator sources 
        * sc_tool        -- ISCS sources  
        * systemc        -- patched SystemC 2.3.3 sources
        * .gitmodules    -- not intended to be used here, can be removed
        * CMakeLists.txt -- Cmake file for ICSC tool
        * LICENSE.txt    -- Apache 2.0 WITH LLVM exceptions license
        * README.md      -- Tool description
        * install.sh     -- Installation script
   * include             -- LLVM/Clang, SystemC and other headers
   * lib                 -- tool compiled libraries
   * libexec             -- can be removed
   * lib64               -- tool compiled libraries
   * share               -- gdb and pretty-printers to show SystemC types 
   * CMakeLists.txt      -- CMake file for examples, tests and user designs
   * gdbinit-example.txt -- GDB configuration to be copied into ~/.gdbinit
   * README              -- build and run examples, tests and used designs instruction
   * setenv.sh           -- set environment script for bash terminal

Run tool for examples and tests

There are number of examples in examples sub-folder:

asserts -- immediate and temporal SystemC assertions with SVA generation
counter -- simple counter with SC_METHOD and SC_CTHREAD processes
decoder -- configurable FIFO example
dvcon20 -- assertion performance evaluation examples
fsm -- finite state machine coding
intrinsic -- Verilog code intrinsic example
latch_ff -- simple latch and flip flop with asynchronous reset

There are number of unit tests in tests sub-folder:

const_prop -- constant propagation analysis tests
cthread -- general tests in SC_CTHREAD
elab_only -- dynamic elaborator tests
method -- general tests in SC_METHOD
mif -- modular interface tests
misc -- extra tests
record -- local and members of struct and class type
state -- state tests
uniquify -- module uniquification tests

Generate SV code for one specific example or design

$ cd $ICSC_HOME
$ source setenv.sh                   # setup PATH and LD_LIBRARY_PATH
$ cd build   
$ cmake ../                          # prepare Makefiles in Release mode
$ ctest -R DesignTargetName          # compile and run SV generation for DesignTargetName

where DesignTargetName is a target name in CMakeLists.txt.

For Debug mode use cmake ../ -DCMAKE_BUILD_TYPE=Debug.

Generate SV code for examples, tests and designs

$ cd $ICSC_HOME
$ source setenv.sh                   # setup PATH and LD_LIBRARY_PATH
$ cd build   
$ cmake ../                          # prepare Makefiles in Release mode
$ ctest -j8                          # compile and run SV generation for all designs

Generated SystemVerilog files are put into sv_out folders. For counter example:

$ cd examples/counter                # go to counter example folder 
$ cat sv_out/counter.sv              # see generated SystemVerilog file

Run SystemC simulation

SystemC simulation for examples and tests can be run with:

$ cd $ICSC_HOME
$ mkdir build && cd build
$ cmake ../                          # prepare Makefiles in Release mode
$ make counter                       # compile SystemC simulation for counter example
$ cd examples/counter                # go to counter example folder
$ ./counter                          # run SystemC simulation

How to add your design

To run ICSC for custom design it needs to create a CMakeList.txt file for the project. SystemVeriog generation is performed with svc_target function call. svc_target is CMake function defined in $ICSC_HOME/lib64/cmake/SVC/svc_target.cmake.

The custom design can be placed into $ICSC_HOME/designs folder. There is an empty design template $ICSC_HOME/designs/template. This design template contains example.cpp and dut.h files. In the design template top module is specified as variable name dut_inst which is instantiated in module tb, so full SystemC name is tb.dut_inst.

# Design template CMakeList.txt file
project(mydesign)

# All synthesizable source files must be listed here (not in libraries)
add_executable(mydesign example.cpp)

# Test source directory
target_include_directories(mydesign PUBLIC $ENV{ICSC_HOME}/examples/template)

# Add compilation options
# target_compile_definitions(mydesign PUBLIC -DMYOPTION)
# target_compile_options(mydesign PUBLIC -Wall)

# Add optional library, do not add SystemC library (it added by svc_target)
#target_link_libraries(mydesign sometestbenchlibrary)

# svc_target will create @mydesign_sctool executable that runs code generation 
# and @mydesign that runs general SystemC simulation
# ELAB_TOP parameter accepts hierarchical name of DUT  
# (that is SystemC name, returned by sc_object::name() method)
svc_target(mydesign ELAB_TOP tb.dut_inst)

Pretty printers for SystemC types

The pretty printers for gdb support SystemC integer types, sc_signal, sc_in, sc_out, sc_inout and sc_vector. The printers can be used in gdb command line as well as in C++ IDE. These printers require gdb built with Python 3 which can be provided by install.sh script.

To setup the pretty printers it needs to copy GDB configuration from icsc/gdbinit-example.txt into ~/.gdbinit.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly