Getting Started with SystemC-2.3

About systemC

SystemC is a set of C++ classes and macros which provide an event-driven simulation interface in C++. These facilities enable a designer to simulate concurrent processes, each described using plain C++ syntax. SystemC processes can communicate in a simulated real-time environment, using signals of all the datatypes offered by C++, some additional ones offered by the SystemC library, as well as user defined. In certain respects, SystemC deliberately mimics the hardware description languages VHDL and Verilog, but is more aptly described as a system-level modeling language.

SystemC is an IEEE(IEEE 1666-2011) standard and more information about it is available on accellera website(link). This post is not about introducing systemC language as we can get that information from systemC language reference Manual(LRM). There is a reference implementation of systemC available for free download on accellera website(Accellera Home)

In this post I have tried to explain the steps for getting started with systemC 2.3 quickly. It took a while for me to get it working right and I feel this documentation will enable a new user to start quickly.

What new in systemC2.3

SystemC 2.3 is an update over existing systemC2.2. It is backward compatible with systemC2.2 hence model developed with systemC2.2 should compile and work functionally same with systemC2.3. However systemC2.3 has added some important features on top of systemC2.2. Following is some of the most important updates

• Process Control Support
• Stepping and Pausing the Scheduler
• sc_vector
• Merger of TLM to base systemC
• Enabling dynamic linking on linux

There is a document named “SystemC2011NewFeatures.pdf” available in the systemC documentation area(\systemc-2.3.0\docs\sysc) that talks about all the new features added in systemC2.3.

Getting SystsemC2.3 Source Code

Reference implementation of SystemC is available on accellera website which is the governing body for systemC as well as several other advance system-level design, modeling, and verification standards. The source code for download is available on system Initiative Standards page(link). Users need to sign up to download the source code. 

Compiling and Installing systemC2.3 on linux

SystemC 2.3 can be used a static library(.a) or a dynamic library(.so) on linux platform. SystemC needs to be linked statically or dynamically with the final executable that performs the simulation and in a process only one instance of systemC should be present.  Follow the steps mentioned below to compile and install systemC library for further usage.

Tools Required:

•  gcc compiler
• make utility
• Unzip utility

Steps:

1. Download SystemC source from Accellera
2. Uncompress the package using command ‘tar -xvzf systemc-2.3.0.tgz’. If you wish, you can also use winrar or winzip to decompress the package. Place the decompressed package in one of your local directories lets say /usr/home/systemc-2.3.0
3. Now let’s say you wish to install systemC in /usr/local path. Then make a directory systemc-2.3.0 in your /usr/local/ path using command. ‘mkdir /usr/local/systemc-2.3.0’ Installing is an optional step as after compilation systemC can be directly used from the /usr/home location itself. The install package is mostly useful for redistribution
4. Open the console and go to directory where you decompressed the package i e  /usr/home/systemc-2.3.0. Create a temporary directory for compilation let say objdir using command. ‘mkdir objdir’. Change to objdir using ‘cd objdir’
5. Now make sure you have access to gcc compiler. Confirm by running ‘which g++’. If not then add gcc install location to your path variable
6. From objdir folder location run the following command. '../configure --prefix=/usr/local/systemc2.3.0' . 
7. The command above will setup all the build tools and makefiles for building systemC with the default option that is suitable for the current host(EG 32 bit/64 bit option, Target m/c architecture etc). –prefix option sets up the path where systemC has to be finally located. If we need to cross compile systemC for some other platform then refer next section.
8. Run 'make'
9. The make command will start building the sources one by one. At end of it should create libsystemc.a, libsystemc.so and libsystemc-2.3.0.so files in ‘objdir/src/sysc/.libs’ folder that could be used for linking to final executable
10. Run ‘make install’ to install the package in ‘/usr/local/systemc2.3.0’ area. If you examine the contents of install are you will see the header file, library files, documentation and example(.cpp files are not part of installed package as they are already compiled and archived in .a and .so binaries). You are ready to start using systemC. Refer the section on running Hello world to write you first systemC program.
11. Run ‘make check’ to compile and run all the provided examples. While running you may see pass message being printed on the console ‘All 1 tests passed’

Note: If something goes wrong or you want to re run configure and make. Run ‘make distclean’ command to clean all the temporary files that may have been created before re running configure or make.

Cross Compiling and Installing systemC2.3 on linux

It may happen that you want to compile systemC for a different target type with some of your own compilation option. The place to influence that is the configure command. One such example is that lets say you are running the compilation on a 64 bit linux but you want to create a 32 bit binary for systemC. How will you do that? The steps below try to accomplish that.

1. Downlaod and unzip the package. Create install and objdir folders. Detail on command mentioned above.
2. Set the following environment variables
• setenv  CC          "<gccInstallPath>/bin/gcc"
• setenv  CXX         "<gccInstallPath>/bin/g++"
• setenv  CPPFLAGS    "-m32" //Give other option if you like
• setenv  CFLAGS      "-m32"   //Give other option if you like
3. Set the following environment variables
4. You can run the command ‘../configure -help’ to know about all the options supported by configure script.
5. In this case I want to compile a 32 bit binary on 64 bit linux. For that the option to be given are ../configure --prefix=/usr/local/systemc230 --target=i686-pc-linux-gnu --build=i686-pc-linux-gnu
6. Run 'make'. Check and confirm that the -m32 and your option provided are used during compilation. After build succeeds run ‘ldd src/sysc/.lib/libsystemc.so’ to look for the dependencies. Confirm that the system libraries are mapped to 32 bit binaries.
7. Run 'make install' to install.

Compiling SystemC on Windows

SystemC2.3 package comes with a visual c++(aka visual studio) project file. It is located in systemc-2.3.0\msvc80\SystemC folder. Steps to compile systemC on windows are as mentioned below.

Tools Required

Microsoft  Visual Studio Express Edition Version 2005 or Above

Note: VC 2005 is also known as VC8, similarly VC 2008 is know as VC9 and VC 2010 is known as VC10.  The Solution file provided by systemC2.3.0 package is for VC8. But it gets easily exported by the IDE when you try to open it with higher versions of the Tool. Simply follow the steps guided by the Wizard.If you have the professional Edition of the Tool that’s even better

Steps:

1. Download SystemC source from Accellera and unzip it. Same package works for both windows and linux. Lets say the unzipped package is placed at 'E:\systemc-2.3.0'
2. Open windows explorer and go to ‘E:\systemc-2.3.0\msvc80\SystemC’ folder. You will file two files SystemC.sln and SystemC.vcproj.
3. Double click on SystemC.sln. It should open VC++ IDE and loads the project into it. You can also open the solution file by opening the VC++ IDE first and Selecting File->Open->Project/Solution option. Note: If you are using a later version of visual studio then the IDE will open a Wizard for converting the project and seek your permission. Allow it to do the conversion by selecting the appropriate option. 
   
4. SystemC Project opened in VC++ IDE. 
   
5. You can build the project by selecting Build->Build Solution option. Or simply press F7. This will build the debug configuration. If you want to build the release configuration. Select Build->Batch Build Option
   
6. That will open a new dialog as shown above. Select checkbox for both Debug and Release and click Build. It should build both debug and release versions of the library. One complete SystemC.lib file gets created in .\msvc80\SystemC\Debug and .\msvc80\SystemC\Release folders
7. Changing the compilation option: By default all the options required for building systemC library are set up in the project file but in case you need to modify any one of them then select ‘Project->SystemC Properties’ option to do so.

Note: Unlike Linux we do not need to install the package any where. On windows the SystemC is compiled as a .lib and it needs to be statically link with the final executable or dll. And since Systemc.lib is a static library we need the location of systemC header files for compiling any source code using systemC. The header files are relatively reference from the directory ‘E:\systemc-2.3.0\src’. Hence simply add an include directory dependency to ‘E:\systemc-2.3.0\src’ folder to compile any source code using systemC.

Running a ‘Hello World’ Program with systemC

The Source File

1. Create an empty text file ‘helloworld.cpp’ and open it with your favorite text editor.
2. Add the following code to it and save it. You can download it from here helloworld.cpp.
   

Compiling and Running Example on Linux

Since systemC is installed in usr/local/systemc2.3.0 area we need to compile helloworld.cpp by including ‘/usr/local/systemc2.3.0/include’ as include path and ‘/usr/local/systemc2.3.0/lib-linux’ as library include path. Also libsystemc.so libraries need to be linked in with the executable.
Hence the command to compile helloworld.cpp will be:
g++ -I. -I/usr/local/systemc2.3.0/include -L. -L/usr/local/systemc2.3.0/lib-linux -Wl,-rpath=/usr/local/systemc2.3.0/lib-linux -o helloworld helloworld.cpp -lsystemc

Running above command will create an executable helloworld in the current working directory
After running the executable helloworld you should get the following output:

You first program with systemC is up and running.

Compiling and Running Example on Windows

Steps

1. Create a new empty ‘win32 console application’ project in VC++ by selecting File->New->Project option. 
   
2. Browse and add helloworld.cpp file to the project. 
   
3. Open Project property window by selecting project->helloworld properties. The following Dialog will appear. Open C/C++ tree view.  
   
4. Update the following options for compilation.
• General->Additional Include Directories: <The place where systemc.h is available> ‘E:\systemc-2.3.0\src’ in my case.
• General->Preprocessor: Add the following macros SC_INCLUDE_FX;_CRT_SECURE_NO_DEPRECATE
• Code Generation->RuntimeLibrary: Change to MultiThreadedDebug(/MTd) since systemc lib was built with this option. If you had changed that to any thing else then make sure that it is set the same here as well other wise you will get linking error.
• Command Line->AdditionalOption: Add /vmg in the textbox
5. Update the following options for Linker by selecting Linker option in the Tree View display.
   
    


• General->AdditionalLibraryDirectories: <Path where systemc.lib has present> in my case it is ‘E:\systemc-2.3.0\msvc80\SystemC\Debug’
• General->Input: Add SystemC.lib





Select F7 or Build->BuildSolution to build the project. 

Once build done run the project by selecting ctrl + F5 or debug the project using F5 key
The o/p should be as shown below. 

With this we are done with setting up SystemC and running a helloworld program with it.

Concluding Remarks:

With this post I tried to explain the first steps towards using systemC library. I know this post is a bit lengthy and wordy but can’t help it as there are lot of subtle details to be mentioned for building and using the library. Ideally this information should have been part of systemC package but surprisingly they are missing. Hope this will be useful in getting a new systemC user start quickly.
Take care.