SystemC Tutorial: modules

Forewords

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.

Modules

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
ALL RIGHTS RESERVED

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.

Summary

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