Home > SytemC Tutorials > SystemC Tutorial: modules

SystemC Tutorial: modules


These tutorials do not try to teach you everything about SystemC in large chapters taken from the language reference manual (LRM). Instead they focus on the most important aspects of the language, basic and advanced covering them in tutorials designed to take around ten minutes each.


A module is a C++ class – it encapsulates a hardware or software description. SystemC defines that any module has to be derived from the existing class sc_module. SystemC modules are analogous to Verilog modules or VHDL entity/architecture pairs, as they represent the basic building block of a hierarchical system. By definition, modules communicate with other modules through channels and via ports. Typically a module will contain numerous concurrent processes used to implement their required behaviour.

The following code illustrates the creation of the simplest of modules:

1 // module tutorial
2 SC_MODULE(module_test) {
3 SC_CTOR(module_test) {
4 cout << “This is my first module” << endl;
5 }
6 };

As can be observed two predefined macros have been used namely: SC_MODULE and SC_CTOR. As a result, the SystemC code resembles other hardware description languages such as Verilog.
Although using predefined macros is seen as convenient by someone coming to SystemC from an HDL background, this would look totally alien to someone comming from a software programming background. Additionally, using this simplistic coding style hides the true nature of SystemC, that is C++.
As a result a we will rewrite the previous code using a more C++ oriented style:

1 class module_test: public sc_module {
2 public:
3 module_test(sc_module_name nm): sc_module(nm)
4 {
5 cout << “This is my first module” << endl;
6 }
7 };

This latest version requires a few clarifications to understand some of the subtleties of SystemC.
First, the creation of a SystemC module requires the inheritance of a specialized class called sc_module. This class defines common features found in any module such as their names. As you would expect the sc_module class feature some more complex elements that are beyond the scope of this tutorial.
The second observation that we can make is the existance of the function: module_test. This function is known in C++ as a constructor and is typically used to perform variables initialization. The other important role of the C++ constructor is to make sure that all the parents used by the current class have been initialized too. In the case of a SystemC module it’s parent class is always the sc_module class. As a result the constructor module_test has to initialise the class sc_module. Thankfully, the only part of the sc_module class that needs to be initialized is it’s name of type: sc_module_name. Therefore the following code:
module_test(sc_module_name nm) defines a parameter for the constructor function called nm of type sc_module_name and then uses that parameter to initialize the parent class by passing it to the constructor of the sc_module class with this semantic: sc_module(nm).

Module Instances

A module by itself isn’t of much use until we start creating instances of it. To create an instance of a module we use a semantics very similar to existing HDLs like Verilog:

module_test module_test_1(“module_test_1”);

Where, module_test is the type of the instance, module_test_1 is the logical name of the instance and “module_test_1” is the name (string) passed to the constructor of the module_test class. This name according to the previous discussion is of type sc_module_name. As can be observed, the sc_module_name data type is very similar to a string data type.
To put this module instance in context, the following code will illustrate how a module can be instantiated inside the main function of a SystemC program (sc_main):

1 // Main program
2 int sc_main(int argc, char* argv[])
3 {
4 module_test module_test_1(“module_test_1”);
5 sc_start();
6 return (0);
7 }

The result from the following code would be:

SystemC 2.2.05jun06_beta — Sep 9 2006 10:21:39
Copyright (c) 1996-2006 by all Contributors

This is my first module

A variation on the way that we create a module instance is by declaring a pointer to a module instead of a module. This method is commonly used to allocate the memory resources on the mass storage instead of the precious RAM. The following code illustrate this:

1 // Main program
2 int sc_main(int argc, char* argv[])
3 {
4 module_test *module_test_1 =
5 new module_test(“module_test_1”);

6 sc_start();
7 delete module_test_1;
8 return (0);
9 }

In this example we used the new instruction to allocate memory for a module_test instance and we assign the address of the memory location onto the pointer module_test.


This tutorial covered the use of SystemC’s modules. A module is a C++ class derived from an existing class: sc_module; consequenlty all SystemC modules require initialization to provide their parent class (sc_module) an expected name of type (sc_module_name).
This tutorial also covered module instantiations, as demonstrated, instantiating a module is a simple afair all that is required is a logical name and a string.

The pdf file for this document and c++ code can be find HERE.

et Voila !

David Cabanis

Categories: SytemC Tutorials
  1. June 25, 2007 at 12:43 am
  2. Aamir Mehmood
    July 18, 2007 at 12:19 pm

    Good Effort buddy!

    But try to expand it a bit more and elaborate more on the software side of systemC coding. I am weak at that side.

    A question, see the code:

    class pv2rtl: public sc_module, trans_if {


    pv2rtl(sc_module_name nm) : sc_module(nm),


    so, How shall we write it in the VHDL type notation…I am more easy with that representation….. see U

  3. GGSoSo
    May 7, 2008 at 8:05 am

    Very useful tutorial for beginners. And thank you for the shared SCLive CD.

  4. mjeong
    August 29, 2013 at 6:50 pm

    Thanks a lot for the good intro. Coming from a pure C++ system simulation background, this tutorial helps me understand SystemC simulation kernel a lot better than, say the standard.

  5. November 7, 2017 at 8:09 pm

    hi there,
    i need your help in systemC. i’m new to this and writing my codes on EDA playground online simulator but i’m getting lots of errors. it would be a great help if you could send a simple basic executable code (say code of half adder) or any other link. or if you also use EDA playground then please send me the link of your program.

    jatin (eajen7@gmail.com)

  1. No trackbacks yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: