SystemC Tutorial: threads, methods and sc_spawn

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.