Forewords

Inheritance and multiple inheritances are a pivotal part of interfaces and channels building. Channels in SystemC can be viewed as, a sophisticated form of communication mechanism; Akin to signals or wires in found in other HDLs. However what differentiates SystemC from common HDLs is the ability given to the designer to handcraft his own channels. Furthermore, the use of interfaces enables the separation of the modules’ implementation from the communication scheme used in between modules; This is an essential part of system level modeling.
In this section we will examine the existing predefined SystemC channels as well as look at the creation of user defined primitive and hierarchical channels.

Inheritance and SystemC channels/ Interface loose coupling

For the creation of channels, SystemC borrows from C++ a convenient principle called: “the class interface”. This principle is also known as abstract base classes and is used to define a common interface for related derived classes.
Sometimes in C++, designers want to create a class that will define a set of access methods that should be used by all the classes that will be derived from it; however this class in itself will never be used to create objects. This type of classes is an abstract base class. In SystemC, abstract base classes are used to define all the access methods that a channel should have. Consequently, a channel will be a C++ class derived from an abstract base class and will implement the access methods defined inside its abstract base parent class.

An abstract base class is created in C++ through the definition of one or more pure virtual methods as part of that class. A pure virtual method by definition is a method that will only be implemented inside a derived class from the abstract base class. The semantics for the declaration of a C++ pure virtual method is as follows:

virtual <return_type> function_name (args>)=0;

For instance the following line of code declares a method called bustWrite that takes three input arguments and returns an integer type:

virtual void burstWrite( int destAddress, int numBytes, sc_lv<8> *data ) = 0;

The keyword ‘virtual’ and the ‘=0’ are the essential parts of this declaration as they indicate to the compiler that ‘burstWrite’ is a pure virtual method and therefore, that the class containing this declaration can never be made into an object.

Once one or a number of abstract base classes (interfaces) have been designed, channels can be implemented by simply inheriting one or more of the base classes and implementing their virtual methods.

Following the creation of channel, instances of that channel can be made as any other C++ object.

Primitive Channels

The SystemC language extension distinguishes between two kinds of channel’s implementation: Primitive channels and non-primitive ones also referred as ‘hierarchical’ channels. Primitive channel as their name imply, have restrictions in regards to their construction. Firstly, any primitive channel is derived from both, its associated interfaces and the predefined SystemC class: sc_prim_channel. In addition, a primitive channel is not allowed to contain SystemC structures for instance threads, methods, other channels et caetera. However, although primitive channel appear limited, they uniquely support the SystemC defined ‘request_update()’ and ‘update()’ access methods.

The SystemC library defines a number of versatile primitive channels namely: sc_buffer<T>, sc_fifo<T>, sc_mutex, sc_semaphore, sc_signal<T>, sc_signal_resolved, sc_signal_rv<W>. Those channels can be used individually or can be combined as part of a ‘non-primitive’ channel to create more complex communication mechanisms. These channels can be declared as follows:

// A 32×16 bits elements fifo
sc_fifo<sc_lv<16> > inputFifo(32);
// A 16 bits bus
sc_signal<sc_lv<16> > dataBus;
// A 4 tokens semaphore
sc_semaphore gateKeeper(4); 

The predefined SystemC primitive channels rely on a number of access methods to allow users to examine or alter their internal state. As previously highlighted, those methods are defined inside the channel’s interface. For channels used to hold values, the read() and write() methods are provided. Most predefined channels also support the common methods: print(), dump(), trace()and kind(). The print(), dump() and trace() methods are used to display the internal values of a given primitive channel either using the output stream or a trace file in the case of the trace() method. The purpose of the kind() method is used to identify the current primitive channel by providing it’s kind as a string information.

Along with access and display methods, most primitive channels support queries of events. These methods may be used for two purposes: examining if a specific channel has currently had an event as part of an expression; such as an ‘if’ statement or supply information related to the activity/events of a channel as part of a sensitivity list of a SystemC process. The following examples illustrate the different method available for specific channels.

// A non blocking write on an sc_signal
dataBus.write(”1010111101010101″);
// A blocking write on a variable of type sc_lv
sc_lv<16> busVar = dataBus.read();
while ( inputFifo.num_free() != 0 )
// A blocking write on an sc_fifo
inputFifo.write(dataBus.read());
// A blocking access to an sc_semaphore
gateKeeper.wait();
// A non blocking access to an sc_semaphore
if ( gateKeeper.trywait() != 0 )
cout << “Got a lock !” << endl;

Although SystemC provides us with numerous pre-defined channels, it is also possible to create user defined channels. As mentioned previously, the creation of a channel is achieved through multiple-inheritance. As a rule, a channel inherits from one or more interfaces as well as from either the sc_prim_channel or the sc_channel SystemC class. Sophisticated relationship between channels can be created by multiple inheritances from various interfaces. The following example describes the creation of a simplified version of the SystemC’s semaphore primitive channel.

class simple_semaphore_if : virtual public sc_interface {  // Line 1
public:
   // the classical operations: wait(), trywait(),
   // and post(), lock (take) the semaphore,
   // block if not available
   virtual int wait() = 0; // Line 7

   // lock (take) the semaphore, return -1
   // if not available
   virtual int trywait() = 0; // Line 10

   // unlock (give) the semaphore
   virtual int post() = 0; // Line 13

   // get the value of the semphore
   virtual int get_value() const = 0; // Line 16

   protected:
   // constructor
   simple_semaphore_if() { } // Line 21
};

// Creation of the semaphore Channel
class simple_semaphore: public simple_semaphore_if, public sc_prim_channel
{
   public:
   // constructors
   explicit simple_semaphore( int init_value_ );

   // interface methods
   // lock (take) the semaphore, block if
   // not available
   virtual int wait(); // Line 37

   // lock (take) the semaphore, return -1 if
   // not available
   virtual int trywait(); // Line 40

   // unlock (give) the semaphore
   virtual int post(); // Line 43

   // get the value of the semaphore
   virtual int get_value() const // Line 46
   { return m_value; }

   protected:
   // support methods
   bool in_use() const // Line 53
   { return ( m_value <= 0 ); }

   protected:
   int m_value; // Line 58
   sc_event m_free; // Line 58
};

// constructors
simple_semaphore::simple_semaphore( int init_value_ ) :
   sc_prim_channel( sc_gen_unique_name( “semaphore” ) ),
   m_value( init_value_ ) { }

// interface methods
// lock (take) the semaphore, block if
// not available
int simple_semaphore::wait() {
   while( in_use() )  sc_prim_channel::wait( m_free );
   -- m_value;
   return 0;
}

// lock (take) the semaphore, return -1 if
//not available
int simple_semaphore::trywait() {
   if( in_use() ) {
      return -1;
   }
   -- m_value;
   return 0;
}

// unlock (give) the semaphore
int simple_semaphore::post() {
   ++ m_value;
   m_free.notify();
   return 0;
}

The first part of this example defines the interface for the semaphore’s channel. line 1 declares the interface class named ‘simple_semaphore_if’ and inherits virtually, the sc_interface SystemC predefined class. The virtual inheritance is used here to prevent any problems related to repeated inheritance later-on during the creation of the simple_semaphore channel. The lines 7 to 16 declare pure virtual methods that will be used to access the semaphore channel. Finally the line 21 defines a default constructor for the interface. Following the interface declaration, we find the declaration of the semaphore channel called ‘simple_semaphore’. The class is created through the inheritance of both the simple_semaphore_if interface class and the SystemC sc_prim_channel pre-defined class. The lines 37 to 46 make the previously pure virtual methods defined inside the interface into effective methods inside the channel. A local method is created in line 53 to used to keep track of the current value of the semaphore. Lastly in lines 58 and 59 we find the definitions of internal member variables used by the semaphore channel. The ultimate part of this example implements each individual methods defined inside the semaphore channel.

Hierarchical Channel

Up until now we have considered the simplest form of channels: the primary channels. Although primary channels are of great use, one of the main advantages that SystemC has over conventional HDLs, is its ability to create complex communication mechanisms in the form of hierarchical channels.
Hierarchical channels are used as a convenient way to abstract exchanges between communicating objects such as sc_modules. Commonly hierarchical channels are used as transactors, converting high level commands to RTL style signals and vice versa.

Herarchical channel can be considered in a lot of ways as, more sohisticated forms of sc_modules. As such, a hierarchical channel can contain ports, as well as, a hierarchy of sc_modules or other channels. Furthermore, hierarchical channels may contain SystemC processes such as: SC_METHODS or SC_THREAD. However, unlike their sc_modules counterparts, hierarchical channels will also provide methods for implementing the functions defined inside their associated interfaces.

As we mention earlier, a channel is always created from one or multiple existing interfaces. An interface in SystemC is an abstract class derived from the existing SystemC class: sc_interface.

By definition interfaces will only define pure virtual access methods. These methods will eventually have to be implemented in any deriving channels. The following illustrates the creation of a user defined interface called dma_interface with a methods called: burstWrite() and bustRead().

class dma_interface: virtual public sc_interface {
public:
   virtual void burstWrite(int destAddress, int numBytes, sc_lv<8> *data ) = 0;
   virtual void burstRead(int sourceAddress, int numBytes, sc_lv<8>* data) = 0;
};

Commonly the inheritance of the pre-defined SystemC class: sc_interface, is done as, public and virtual. The virtual mechanism is used as a safety net, preventing the rise of issues related to repeated inheritance when a channel inherits more that one interface.

After the creation of an interface, numerous channels can be created to provide the required implementation of the interfaces’ methods. The creation of a hierarchical channel differs from a primitive one, only by the type of the inherited pre-defined SystemC class: sc_channel. Along with the sc_channel class, one to any number of interface classes can be inherited. The following code illustrates the creation of a channel called: dma_channel, publicly inheriting form the interface class: dma_interface.

class dma_channel: public dma_interface, public sc_channel {
public:
   sc_out_rv<16> address_p;
   sc_inout_rv<8> data_p;
   sc_out_resolved rw_p;
   dma_channel(sc_module_name nm): sc_channel(nm)
      ,address_p(”address_p”)
      ,data_p(”data_p”)
      ,rw_p(”rw_p”)
   { }
   virtual void burstWrite( int destAddress, int numBytes, sc_lv<8> *data );
   virtual void burstRead(int sourceAddress, int numBytes, sc_lv<8>* data);
};

void dma_channel::burstWrite( int destAddress, int numBytes, sc_lv<8> *data ) {
   sc_lv<8> *ite = data;
   for (int i=0; i<numBytes; i++) {
      address_p->write(destAddress++);
      data_p->write( *(ite++) );
      wait(10, SC_NS);
      cout << “Write out ” << data_p->read() << endl;
      rw_p->write(SC_LOGIC_0); // Write pulse
      wait(50, SC_NS);
      rw_p->write(SC_LOGIC_Z);
      address_p->write(”ZZZZZZZZZZZZZZZZ”);
      data_p->write(”ZZZZZZZZ”);
      wait(10, SC_NS);
   }
}

void dma_channel::burstRead(int sourceAddress, int numBytes, sc_lv<8>* data) {
   for (int i=0; i<numBytes; i++) {
      address_p->write(sourceAddress++);
      wait(10, SC_NS);
      rw_p->write(SC_LOGIC_1); // Read pulse
      wait(10, SC_NS);
      *(data++) = data_p->read();
      cout << “Data read ” << data_p->read() << endl;
      wait(40, SC_NS);
      rw_p->write(SC_LOGIC_Z);
      address_p->write(”ZZZZZZZZZZZZZZZZ”);
      data_p->write(”ZZZZZZZZ”);
      wait(10, SC_NS);
   }
}

The first part of this code illustrates the creation of the hierarchical channel called dma_channel. This is done through the multiple inheritance of the sc_channel class and the dma_interface class.
Ports are created to illustrate the flexibility of channels. Those port are initialised inside the constructor of that class.
The last part of the dma_channel class declaration restates the existance of the burstWrite() and burstRead() methods found in the parent class: dma_interface.

Lastly the code illustrates the implementation of the two methods burstWrite() and burstRead(). The code itself is of little importance but it demonstrates how high level transactions can be refined into low-level RTL signal activities.

For the pupose of completeness of this example the following code illustrates how can this channel could be used in a verification environment.
This code shows the creation of a simple testbench sending a burstWrite() and a burstRead() request to a slave RTL memory via the dma_channel.

class test_bench: public sc_module {
   public:
   sc_port<dma_interface> master_port;

   void stimuli()
   {
      sc_lv<8> data_sent[10] = {20, 21, 22, 23, 24, 25,26,27,28,29};
      sc_lv<8> data_rcv[10] = {0,0,0,0,0,0,0,0,0,0};
      master_port->burstWrite(100, 10, data_sent);
      wait(100, SC_NS);
      master_port->burstRead(100, 10, data_rcv);
      for (int i=0; i<10; i++) {
         if (data_sent[i] != data_rcv[i]) {
            cout << data_sent[i] << ” ” << data_rcv[i] << endl;
            cout << “data missmatch” << endl;
         }
      }

   SC_HAS_PROCESS(test_bench);

   test_bench(sc_module_name nm): sc_module(nm) {
      SC_THREAD(stimuli);
   }
};

class rtl_memory: public sc_module {
public:
   sc_in_rv<16> address_p;
   sc_inout_rv<8> data_p;
   sc_in_resolved rw_p;
   sc_lv<8> *mem_arr;
   void run() // sensitive rw_p
   {
      while(true) {
         // read cycle
         if (rw_p->read() == SC_LOGIC_1) {
            data_p->write( *( mem_arr+(sc_uint<16>(address_p->read())) ) );
            // write cycle
         } else if (rw_p->read() == SC_LOGIC_0) {
            *(mem_arr + (sc_uint<16>(address_p->read()))) = data_p->read();
         }
         wait();
      }
   }

   SC_HAS_PROCESS(rtl_memory);
   rtl_memory(sc_module_name nm, int mem_size = 100): sc_module(nm) {
      mem_arr = new sc_lv<8>[mem_size];
      for (int i=0; i< mem_size; i++) {
         mem_arr[i] = sc_lv<8>(0);
      }
   SC_THREAD(run);
      sensitive << rw_p;
   }

   ~rtl_memory() { delete []mem_arr; } };

// Main program
int sc_main(int argc, char* argv[])
{
   sc_set_time_resolution(1, SC_NS);

   sc_signal_rv<16> address_s;
   sc_signal_rv<8> data_s;
   sc_signal_resolved rw_s;

   test_bench tb(”tb”);
   dma_channel transactor(”transactor”);
   rtl_memory uut(”uut”, 1000);

   tb.master_port(transactor);
   transactor.data_p(data_s);
   transactor.rw_p(rw_s);
   transactor.address_p(address_s);
   uut.address_p(address_s);
   uut.data_p(data_s);
   uut.rw_p(rw_s);

   sc_start();
   return 0;
}

Summary

In this section we covered the existance of two kind of channels in SystemC: primitive, hierarchical. The main differences between those two kinds being: primitive channels cannot contain SystemC structural objects (ports, channels, processes) but can use the update() method to implement non blocking update mechanisims; The hierachical channels however can have structural objects but cannot use the update() method.
I addition we illustrated the creation of both a primitive and hierarchical channel as well as their use in the context of a verification environment.

The code for this tutorial can be found HERE.

Et voila !

David Cabanis

Forewords

This tutorial is intended to be a basic introduction to the notions of concurrent processes in SystemC. We will touch on the SystemC ability to dynamically spawn processes.

Processes in SystemC

One of the essential element of the SystemC language is concurrency. This is achieved through what we will call processes. Processes are similar to processes in VHDL or always/initial in Verilog. In principle processes are block of sequential code similar to functions. However, unlike functions, processes are not explicitly called by the user. Processes can in effect be seen as always active; For that reason they are considered to be concurrent.
In the SystemC language there are two distinct kinds of processes namely: SC_METHOD and SC_THREAD. These two kind of processes are typically created statically; In other words they are created prior to the execution of the simulation. Alternatively SystemC allows processes to be created dynamically via a dedicated function called: sc_spawn() .

The SC_THREAD process

As a first step we will look at the SystemC SC_THREAD. A thread by definition is a process that will automatically execute itself at the very start of a simulation run and then will suspend itself for the rest of the simulation.
Threads are versatile processes in the sense that they can be halted at any moment and any number of times during their execution. Interestingly, although the thread is mean to be executed only once throughout the simulation, most of times we want to be able to use threads for the whole duration of the simulation. In order to achieve this, we use a simple ‘trick’ that consist in creating an infinite loop within a thread. Consequently we prevent the thread from ever reaching its sequential end. The following example illustrates how to create a simple thread used to generate a clock generator.

void run() {
   while(true) {
      clock_signal.write(SC_LOGIC_0);
      wait(10, SC_NS);
      clock_signal.write(SC_LOGIC_1);
      wait(10, SC_NS);
   }
}

Three main observations can be made:

• The funtion ‘run’ does not have any input or return parameters. This typical of a SystemC static process such as SC_THREAD or SC_METHOD.
• An infinite while loop is used to prevent the function ‘run’ from ever reaching its end. This does not have to be used for all SC_THREAD implementations; however it is a common occurrence.
• We are using ‘wait’ function calls to force a temporary suspension of the function ‘run’ and the update of the ‘clock_signal’ value. This can only be used by SC_THREAD processes.

Up until now we have only created a C++ member function that will be used as a thread. At this time we will need to indicate to the SystemC simulation kernel that this specific member function (in our case ‘run’) should be treated as a concurrent thread and not as a basic C++ member function. This will be done through an operation called processes registration. To put it simply this consists in enumerating how individual functions should be treated. This simple operation is done inside the constructor of a module. The following code will illustrate how this is achieved.

sample_module(sc_module_name nm):sc_module(nm) {
   SC_THREAD(run);
}

In this example we assume the existence of a SystemC called ’sample_module’. The process registration of the member function ‘run’ as an SC_THREAD is done by passing the name of the selected function (run) as an argument of the macro SC_THREAD.

The SC_METHOD process

The SC_METHOD is in many ways similar to the SC_THREAD. However there are two main differences: SC_METHOD will run more than once by design and methods cannot be suspended by a wait statement during their execution. The following code illustrates this.

void log() {
   count_signal.write(count_signal.read()+1);
   if (count_signal.read() >= 10) {
      cout << "Reached max count" << endl;
      count_signal.write(0);
   }
}

From this sample we can observe that no wait statements are being used. Additionally there is no need for an infinite ‘while’ loop since this is the nature of an SC_METHOD to go back to it’s beginning when it finishes executing.
However not visible inside the code lies a hidden wait statement. That implicit statement is always located on the very last line of the member function and causes the kernel to suspend the SC_METHOD so that its sensitivity list can be evaluated.

Processes Sensitivity

SystemC support two kind of sensitivity: Dynamic and static. For the purpose of this tutorial we will concern ourselves only with that later. Both SC_THREAD and SC_METHOD may have a sensitivity list although they are not obliged to. In the example of the SC_THREAD covered previously we did not use a static sensitivity list; For the SC_METHOD example we will have to.
As seen before the SystemC requires a kernel registration to identify which member function it needs to treat as a SC_METHOD (no explicit suspension allowed) or an SC_THREAD (suspensions allowed). In the case of the method processes we will use the macro SC_METHOD. The following code illustrates the registration of the ‘log’ function as a SC_METHOD.

sample_module(sc_module_name nm):sc_module(nm) {
   SC_METHOD(log);
      sensitive << clock_signal.posedge_event();
}

As can be observed we now have an additional statement indicating that the macro directly above it is sensitive to positive edges of the signal ‘clock_signal’. That sensitivity list will typically contain event objects as well as ports or channels (signals).
Consequently as soon as a positive edge is detected on the signal ‘clock_signal’, the function ‘log’ will be re-executed.

The last point of detail remaining is to indicate to the kernel that this module that we have created will contain concurrent processes. This is done using the macro SC_HAS_PROCESS(moduleName).

The full code for this section on threads, methods and sensitivity list is shown here:

class sample_module: public sc_module
{
	public:
	sc_signal clock_signal;
	sc_signal count_signal;
	SC_HAS_PROCESS(sample_module);
	sample_module(sc_module_name nm):sc_module(nm) {
		SC_THREAD(run);
		SC_METHOD(log);
			sensitive << clock_signal.posedge_event();
	}

	void log() {
		count_signal.write(count_signal.read()+1);
		if (count_signal.read() >= 10) {
			cout << "Reached max count" << endl;
			count_signal.write(0);
		}
	}

	void run() {
		while(true) {
			clock_signal.write(SC_LOGIC_0);
			wait(10, SC_NS);
			clock_signal.write(SC_LOGIC_1);
			wait(10, SC_NS);
		}
	}
};

Dynamic processes

In the first part of this tutorial we have looked at the most common usage of processes in SystemC. Nevertheless there is yet a more sophisticated way of creating processes by spawning functions at will. This method is by far the most flexible and most complete.
The sc_spawn function can be seen as a super-set of the existing SC_THREAD, SC_METHOD macros. It can be used as a straight replacement although the semantics is a bit more involving.
A very basic example of the function sc_spawn is as follows. Assuming that we have an existing member function as such:

void spawned_th(bool value) {
   cout << "spawned_th successfuly spawned with value: "
          << value << endl;
}

A call to spawn that function from within an SC_THREAD would be as such:

sc_spawn( sc_bind(&sample_module::spawned_th, this, true) );

Without going in too much details, this call relies on an additional function sc_bind that is required to attach an existing function. This is done by passing the address (&) of the required member function as an argument. In addition, we need to indicate that this specific function is not a global function (this is also allowed) but a member function of our module hence the use of ‘this’. Finally the function ’spawned_th’ has one input paramenter ‘value’ of type bool therefore we set an actual value (true) inside the ’sc_bind’ call.

A more complete example is as follows:

class sample_module: public sc_module
{
   public:
   sc_signal clock_signal;
   SC_HAS_PROCESS(sample_module);
   sample_module(sc_module_name nm):sc_module(nm) {
      SC_THREAD(run);
   }

   void spawned_th(bool value) {
      cout << "spawned_th successfuly spawned with value: "
             << value << endl;
   }

   void run() {
      sc_spawn( sc_bind(&sample_module::spawned_th, this, true) );

      while(true) {
         clock_signal.write(SC_LOGIC_0);
         wait(10, SC_NS);
         clock_signal.write(SC_LOGIC_1);
         wait(10, SC_NS);
      }
   }
};

As stated earlier this example has been kept very simple for the purpose of clarity. Additional features would be the ability to:

• Specify a return argument for the spawned function
• Specify if the argument passed to the function are reference (as opposed to copies) or constant references
• Spawn a global function instead of a member function
• Being able to specify if the spawned function should be treated as a method or thread(default)
• Being able synchronise thread activities by checking their status (idle or running)

Most of those options can fairly easily be achieved however they fall outside of the scope of this tutorial. Nevertheless to give you a more complete picture of the ’sc_spawn’ function, we will illustrate the spawning of a global function with return arguments and reference input arguments.

#define SC_INCLUDE_DYNAMIC_PROCESSES

int global_th(const bool& in_value, int& out_value) {
   cout << "global_th successfuly spawned with value: "
          << in_value << ", " << out_value << endl;

   if (in_value) {
      out_value++;
      wait(2, SC_NS);
      return 0;
   }
   wait(5, SC_NS);
   return 1;
}

class sample_module: public sc_module
{
   public:
   sc_signal clock_signal;
   SC_HAS_PROCESS(sample_module);
   sample_module(sc_module_name nm):sc_module(nm) {
      SC_THREAD(run);
   }

   void run() {
      int actual_return_value, actual_int_arg = 9;
      bool actual_bool_arg = true;

      sc_spawn( &actual_return_value, sc_bind(&global_th,
                       sc_cref(actual_bool_arg),
                       sc_ref(actual_int_arg) ) );

      while(true) {
         clock_signal.write(SC_LOGIC_0);
         wait(10, SC_NS);
         clock_signal.write(SC_LOGIC_1);
         wait(10, SC_NS);
      }
   }
};

This time the ’sc_spawn’ function has an additional argument for the returned value (passed by pointer) in addition the ‘this’ argument was removed since we are now dealing with a global function. The ’sc_cref’ and ’sc_ref’ functions were used to indicate that we were dealing with constant reference and reference formal arguments.

Conclusions

This tutorial covered the basic uses of SystemC processes. we announced the rules regarding the suspension of processes and looked at the sensitivity list and kernel registrations. Lastly we covered the use of the sc_spawn function and saw how can generic functions can be parallelised at will.

Et voila!

David Cabanis.

The SystemC Live CD version 2.0 has been released today. It can be downloaded directly from HERE and HERE

This new version features:

1. SystemC 2.2 beta
2. SCV 1.0
3. TLM 1.0
4. SystemC / C++ tutorial (Esperan)
5. gcc g++ 3.4.6
6. gdb 6.3
7. ddd 3.3.9
8. gtkwave 1.3.79
9. vim 7.0
10. geany 0.7.1
11. opera 9.02
12. Beep Media Player 0.9.7
13. xpdf
14. xfce4 4.2.3.2
15. slapt-get 0.9.11b
16. gslapt 0.3.1.2

The file size is 137MB and can be burnt onto various media such as: Memory stick (USB), Mini CD, CD-R, CD-RW.

You will find SCLive 2.0 to be a more integrated, complete and slicker distribution with tools that will facilitate SystemC development (gdb, ddd, vim) and user customisations (gslapt, slap-get).

The zip file also contains pre-prepared configuration files to run SCLive 2.0 painlessly inside the VMWare player software.

Have a lot of fun with SCLive and don’t hesitate to send me your comments (Francais/ English) at: systemclive@googlemail.com

David Cabanis

Forewords

C++ implements Object-Orientation on the C language. For most Hardware Engineers, the principles of Object-Orientation seem fairly remote from the creation of Hardware components. However ironically, Object-Orientation was created from design techniques used in Hardware designs. Data abstraction is the central aspect of Object-Orientation which incidentally, is found in everyday hardware designs through the use of publicly visible “ports” and private “internal signals”. Furthermore, the principle of “composition” used in C++ for creating hierarchical design is almost identical to component instantiation found in hardware designs. The coming sections will introduce the basics of C++ by looking at the creation of an hardware component.

The Class

The class in C++ is called an Abstract Data Type (ADT); it defines both data members and access functions (also called methods). Both data members and access functions are said to be private by default. In other words, data members and access functions are not visible from the outside world. This ADT mechanism is analogous to a package and package body in VHDL. The designer is responsible for making publicly available the essential set of access functions for manipulating an ADT. The semantics for a C++ class declaration is as follows:

class counter

{

int value;

public:

void do_reset() { value = 0 ; }

void do_count_up() { value++ ; }

int do_read() { return value; }

};

 

In this example we see the declaration of an ADT called: “counter” with a data member “value” and publicly available access functions: “do_reset”, “do_count_up” and “do_read”. Although this class declaration is complete; commonly, a class declaration will also contain specialised functions such as constructors and a destructor. When constructors are used, they provide initial values for the ADT’s data members. This mechanism is the only allowed mean for setting a default value to any data member.
A destructor is used to perform clean-up operations before an instance of the ADT become out of scope. Pragmatically, the destructor is used for closing previously opened files or de-allocating dynamically allocated memory.
An example of an ADT with constructors and a destructor is as follows:

class counter

{

int value;

public:

void do_reset() { value = 0 ; }

void do_count_up() { value++ ; }

int do_read() { return value; }

counter() {

cout << “This a simple constructor” << endl;

value = 10;

}

counter(int arg): value(arg) {

cout << “This a more interesting constructor” << endl;

}

~counter() {

cout << “Destroying a counter object” << endl;}

};

 

In our example all access functions are made visible to the outside world through the use of the “public” keyword. However, not all functions have to be made public; they can be held hidden from the rest of the world through the use of the “private” keyword.

The Object

An object is an instance of an ADT. Any number of instances can be made of a given ADT; each of these instances are initialised individually.
An example of objects instantiation and messages passing is as follows:

void main() {

 

counter first_counter;

counter second_counter(55);

 

// Message passing

first_counter.do_reset();

for (int i=0; i < 10; i++) { first_counter.do_count_up(); }

second_counter.do_count_up();

 

first_counter.do_reset();

second_counter.do_reset();

}

In this example two instances of the counter ADT are created. The “first_counter” instance uses the default constructor not requiring any arguments. The “second_counter” instance uses a more sophisticated constructor form that passes an argument.

Messages are send to individual objects via the ‘dot’ notation which is similar to what is used for “struct” data structures.

The building of more complex objects can be achieved through the composition mechanism. This mechanism is akin to component instantiation in Hardware design.

The following example illustrates the principle of hierarchical design through composition.

class modulo_counter

{

counter internal_counter;

int terminal_count;

public:

void do_reset() { internal_counter.do_reset(); }

void do_count_up() {

if ( internal_counter.do_read() < terminal_count ) {

internal_counter.do_count_up();

} else { internal_counter.do_reset(); }

}

int do_read() { return internal_counter.do_read(); }

modulo_counter(int tc):

terminal_count(tc),

internal_counter(0) {

cout << “A new modulo_counter instance” << endl; }

};

 

In this example a new ADT “modulo_counter” is created form an instance of a counter ADT called “internal_counter”. An additional data member “terminal_count” was added to provide the modulo value for this new ADT. The access function “do_count_up” is customised to take in considerations of the modulo counter specifications. As it can be observed, most actions are delegated to the “internal_counter” instance via message passing. It is interesting to notice how the constructor function is used to initialise both the “terminal_count” value and the instantiated object “internal_counter”. The argument “tc” is used to set the value of “terminal_count” and the value “0” is passed to the constructor of the “internal_counter” object.

Inheritance

Along with composition, C++ provides a sophisticated mechanism for reusing code called: inheritance. With inheritance designers are able to create new ADTs from existing ones by accessing all public elements of a parent class into a child class. This principle can be more appropriate than composition since it usually requires less effort to achieve the same goal. However inheritance does not replace composition but complements it. The following example illustrates the creation of a modulo counter ADT from an existing counter ADT whilst using inheritance.

class modulo_counter : public counter {

int terminal_count;

public:

void do_count_up() {

if ( do_read() < terminal_count ) {

counter::do_count_up(); }

else { do_reset(); }

}

modulo_counter(int tc): terminal_count(tc), counter(0) {

cout << “A new modulo_counter instance” << endl; }

};

 

In this example a new access function called “do_count_up” is created. This overrides the inherited function from the parent class “counter”. The remaining public access functions (do_reset, do_read) found in the parent class are now available to the child class: “modulo_counter”. As it can be observed the creation of the “modulo_counter” class is greatly simplified through the use of inheritance. Nevertheless, the “do_read” and “counter::do_count_up” functions had to be used in the newly created “do_count_up” function to access the private data members inside the parent class. Although this is a valid solution, C++ offers a more pragmatic alternative, consisting in using a protected encapsulation in place of a private one. Unlike private members, protected members are inherited along with public ones when a parent class is derived, however, protected data members remain hidden from the outside world in the same way as private members do. A new implementation of the counter and modulo_counter class using protected data members is as follows:

class counter

{

protected:

int value;

public:

void do_reset() { value = 0 ; }

void do_count_up() { value++ ; }

int do_read() { return value; }

counter() {

cout << “This a simple constructor” << endl;

value = 10;

}

counter(int arg): value(arg) {

cout << “This a more interesting constructor” << endl;

}

~counter() { cout << “Destroying a counter object”

<< endl;}

};

 

class modulo_counter : public counter {

protected:

int terminal_count;

public:

void do_count_up() {

if ( value < terminal_count ) { value++; }

else { value = 0; }

}

modulo_counter(int tc): terminal_count(tc), counter(0) {

cout << “A new modulo_counter instance” << endl; }

};

 

In this last example the data member “value” is directly accessed from within the “modulo_counter” class. The use of the protected encapsulation has simplified the creation of the derived class by making data members from the parent class accessible.
The principle of single inheritance can be extended to allow a child class to be built from multiple parents. This principle is referred as multiple inheritance. Multiple inheritance enables designers to rapidly create new sophisticated classes from a multitude of existing ADTs. The use of multiple inheritance commonly requires careful planning since it can create numerous undesirable side effects. An example of multiple inheritance is as follows:

class reg {

protected:

int value;

public:

void do_reset() { value = 0; }

int do_read() { return value; }

void do_write(int arg) { value = arg; }

reg(): value(0) {}

};

 

class up_counter: virtual public reg {

public:

void do_count_up() { value++; }

};

 

class down_counter: virtual public reg {

public:

void do_count_down() { value–; }

};

 

class up_down_counter: public up_counter, public down_counter { };

 

In this example the “up_down_counter” ADT is created from two parent classes: “up_counter” and “down_counter”. The “up_down_counter” does not require any code since it inherits all of its implementation from its parent classes. It is important to point out that both the “up_counter” and “down_conter” are inheriting virtually the register class. The virtual inheritance is used here to prevent multiple declarations of the “value”, “do_reset”, “do_read”, “do_write” inside the “up_down_counter” since this ADT inherits those attributes twice, though both the “up_counter” and “down_counter” inheritance.

Template Class

The template mechanism is used for creating more versatile ADTs. Templates can be used for variable types or values. An example of a simple template class is as follows:

template<int min, int max> class barrel_counter {

private:

int value;

public:

void do_reset() { value = min; }

void do_count_up() {

if (value< max ) { value++; }

else {value = min; }

}

int do_read() { return value; }

barrel_counter(): value(min) { }

};

 

 

int main(int argc, char *argv[])

{

barrel_counter<10, 50> first_counter;

barrel_counter<0, 10> second_counter;

 

for (int i=0; i < 60; i++) {

first_counter.do_count_up();

second_counter.do_count_up();

cout << first_counter.do_read() << endl;

cout << second_counter.do_read() << endl;

}

return 0;

}

 

This counter implementation defines two templates “min” and “max”; these variables are then used inside the class to define the boundaries of the barrel counter. This example uses templates to set variable values; alternatively templates can be used to set a variable type. An example of templates used for variable types is as follows:

template<class T> class adder {

private:

T result;

public:

T add( T a, T b ) {

result = a + b ;

return result ;

}

};

 

int main(int argc, char *argv[]) {

adder<int> integer_adder;

adder<float> float_adder;

 

int int_result = integer_adder.add(3, 5);

float float_result = float_adder.add(6.7, 10.2);

cout << int_result << endl;

cout <<float_result << endl;

return 0;

}

 

This example uses a variable type “T” used throughout the class to provide a versatile ADT implementation. At a later stage two objects of type adder are declared however, both adders use different types for its operations.

Summary

As we illustrated in this section, Hardware components can be modeled in C++ and to some extent the mechanisms used are similar to those used in HDLs. Additionally C++ provides inheritance as a way to complement the composition mechanism and promotes design reuse.
Nevertheless, C++ does not provide for concurrency which is an essential aspect of systems modeling. Furthermore, timing and propagation delays cannot easily expressed in C++. The SystemC library provides additional mechanisms such as processes and dedicated data types to tackle C++ modeling deficiencies.

The pdf file and the source files for this tutorial can be found HERE.

Et Voila !

David Cabanis

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.

Ports

A Port is an essential element of any SystemC model. Ports are used by modules as a gateway to and from the outside world. In a simplistic way, one can consider a port like the pin of a hardware component.
In HDLs such as VHDL or Verilog, ports are very much like the pins metaphor; In the case of SystemC ports have a substantially more generalized purpose and as a result they are far more sophisticated and useful than their HDLs counterparts.

A simple SystemC port declaration would look like the following code:

sc_in<bool> my_input;

As can be observed the semantic is kept to a minimum level of complexity; The port has a name my_input and in this particular instance, it is of input mode since we used the sc_in<> port type (or port mode if you prefer). The last observation that we can make from this simple line of code is the use of the bool data type inside the <> of the sc_in port type. This data type refers to the kind of data that will be exchanged on that port. In other words we are expecting to receive boolean values on the my_input port.

As you would expect, numerous predefined port types exist in SystemC; Such as: sc_in<Type>, sc_out<Type>, sc_inout<Type>, etc. All of those ports are almost identical to their HDL equivalents in VHDL or Verilog; they have a name, a type and a mode (in, out, etc). As a mater of fact, these kinds of ports are commonly used in RTL SystemC. However, as we indicated earlier, SystemC ports are much more than just RTL like ports; This is because SystemC ports not only have a name and a type but most importantly they define the access mechanisms that should be used on them. Pragmatically the access mechanisms are just a list of allowed messages that can be used on them. If we consider the sc_in<bool> port of the previous example, SystemC defines that one can use the read() message on it. Not surprisingly, an sc_out<> port would allow the use of the write() message. The following code illustrates the use of an sc_in<bool> and an sc_out<bool> ports.

// More code not shown here

sc_in<bool> my_input;
sc_out<bool> my_output;

// More code not shown here

void do_run() {
if (my_input.read() == true) {
my_output.write(false);
} else {
my_output.write(true);
}
}
};

// More code not shown here

For the sake of simplicity the creators of the SystemC language have provided operators that can be used instead of the read() and write() messages. Consequently the following code is also acceptable:

// More code not shown…

void do_run() {
if (my_input == true) {
my_output = false;
} else {
my_output = true;
}
}

// More code not shown…

The list of access messages allowed on specific ports has already been defined for the existing SystemC ports. However SystemC allows the user to define his/her very own set of messages for his/her very own ports. For instance one could imagine the existence of a high-level port used on a CPU model that could receive messages such as: dma_request() or interrupt_request() form the outside world.
The creation of user defined ports goes beyond the scope of this tutorial and can only be covered when you will have gained an understanding of the notion of SystemC interfaces.

Ports and Modules

Up until now we only considered ports in isolation. Prosaically ports are parts of modules and are used to pass data of some form in and out of the modules. SystemC ports are by definition object instances of predefined classes (sc_in<>, sc_out<>, etc.) . As a result they can be accessed from within any member function defined inside the module. For instance the following code would be a valid way of using ports:

class portsTutorial: public sc_module {
public:
sc_in<bool> my_input;
sc_out<bool> my_output;

SC_HAS_PROCESS(portsTutorial);

portsTutorial(sc_module_name nm): sc_module(nm) {
SC_METHOD(do_run);
sensitive << my_input;
}

protected:
void do_run() {
if (my_input.read() == true) {
my_output.write(false);
} else {
my_output.write(true);
}
}
};

Ports and Signals

Ports and signals have a special relationship since ports will connect to other ports via signals (also known as channels). More importantly, ports and signals share a common language. All the messages that can be used on a port should also be available on the signals (channels) connected to that port. As a result specific ports can only be connected to compatible signals; for instance an sc_in<> or an sc_out<> port can be connected to an sc_signal<> however and sc_fifo_in<> or an sc_fifo_out<> port can only be connected to an sc_fifo<> kind of channel. The following code illustrates the use of ports with signals:

// Top level
class top: public sc_module {
public:
sc_signal<bool> sig_1, sig_2;

portsTutorial uut;

top(sc_module_name nm): sc_module(nm), uut(”uut“) {
uut.my_input(sig_1);
uut.my_output(sig_2);
}
};

As can be observed the connection of a port and a signal is a simple operation. Nevertheless this semantics may look surprising since a usual object-oriented message is of the form: object_name.message(parameters) . In this case, uut.my_input(sig_1) is composed of two objects: uut which is the component’s name and my_input which is the port’s name and finally sig_1 is a parameter. In other words we have: object_name.object_name(parameter) but no message call on the object. The reason is a simple one; the creators of SystemC used an overloading trick to make ports/signals connections appear simpler. In fact if you wanted to be a object-orientation purist you could write the following code to the same effect:

top(sc_module_name nm): sc_module(nm), uut(”uut“) {
uut.my_input.bind(sig_1);
uut.my_output.bind(sig_2);
}

The bind() message is effectively what is being used to connect a port to a signal (channel) although in the previous example it was hidden through an overloading trick.
Lastly, there is yet anther way to connect your ports to your signals this is done using positional mapping where the signals are mapped to the ports by position. An example of positional mapping is as follows:

top(sc_module_name nm): sc_module(nm), uut(”uut“) {
uut(sig_1, sig_2);
}

This style is certainly the most succinct way of connecting a component to a set of signals however it is usually seen as a more error prone way since the signals can easily be miss-ordered.

Summary

This tutorial covered the basic uses of ports in a SystemC model. Ports are part of modules and are used to connect modules together via signals (channels). In this tutorial wefocused on the predefined SystemC ports however, most commonly the user creates it’s own port kind defining it’s own set of messages that can be exchanged on those ports. The subject of user defined port we be covered in an other tutorial.

The pdf file and the source files for this tutorial can be found HERE.

David Cabanis.

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

Introduction

This module will allow you to use the much loved editor SciTE inside of SCLive. It’s a 1 Mb module.

Details

The module once installed will copy its content inside the directory: /usr/local/bin To use it, simply type on a console: SciTE

Note: You may get some warning messages when the program is loading, this is expected and you should not worry about them.
Downloading

The module can be downloaded HERE.

Installing

The easiest way to install the module is to download it from within SCLive then type:

uselivemod ~/Desktop/<modulename.mo>

Note: As I am sure you realize ~/Desktop is the default location for the downloaded files from firefox.

Alternatively you can add the module inside the /modules directory of your SCLive ISO file and burn a new ISO file.

Introduction

This module will allow you to use ghdl a free VHDL simulator with SCLive. It’s a 4 Mb module.

Details

The module once installed will copy its content inside the directory: /usr/local/bin To use it, you can follow the ghdl tutorial located HERE.
Downloading

The module can be downloaded HERE.

Installing

The easiest way to install the module is to download it from within SCLive then type:

uselivemod ~/Desktop/<modulename.mo>

Note: As I am sure you realize ~/Desktop is the default location for the downloaded files from firefox.

Alternatively you can add the module inside the /modules directory of your SCLive ISO file and burn a new ISO file.

Screenshot:

Et voila!

David Cabanis.

Introduction

This module will allow you to use the SystemC Verification Library with SCLive. It’s a 4 Mb module.

Details

The module once installed will copy its content inside the directory: /usr/local/systemc/systemc-2.1.v1
To use it, navigate to the examples directory inside the systemc-2.1.v1 directory and try the exemples inside the scv directory ( use make ).

Downloading 

The module can be downloaded HERE.

Installing

The easiest way to install the module is to download it from within SCLive then type:

uselivemod ~/Desktop/<modulename.mo>

Note: As I am sure you realize ~/Desktop is the default location for the downloaded files from firefox.

Alternatively you can add the module inside the /modules directory of your SCLive ISO file and burn a new ISO file.

Et voila!

David Cabanis.

Introduction

This module will allow you to edit files via the ubiquitous and adored vim program. It’s a 4.5 Mb module and worth every bits of it.

Details

The module once installed will copy its executable inside the /usr/local/bin directory.

To invoke vim, simply type: vim <filename> as a command inside a terminal window.

Downloading

The module can be downloaded HERE.

Installing

The easiest way to install the module is to download it from within SCLive then type:

uselivemod ~/Desktop/<modulename.mo>

Note: As I am sure you realize ~/Desktop is the default location for the downloaded files from firefox.

Alternatively you can add the module inside the /modules directory of your SCLive ISO file and burn a new ISO file.

Et voila!

David Cabanis.