Modeling and Simulation with SystemC

1 Introduction
This document is a basic tutorial in SystemC [3]. It is supposed to be studied as a preparation for the lab assignments in the courses TDTS07 and TDDI08. The assignments are found in Section 3. Parts of this document are based on the books by Black and Donovan [1] and Grtker et al. [2]. o The SystemC language has in the recent years become an important alternative to the traditional hardware and system description languages VHDL and Verilog. In an industrial context, SystemC has been used extensively, and nowadays synthesis tools and other design automation tools support SystemC models. In this lab, we shall use SystemC to model and describe timed systems on a high level of abstraction (transactions-level modeling). We shall further use simulations to validate our models.

SystemC

SystemC is a language that allows designers to develop both the hardware and software components of their system together. This is all possible to do at a high level of abstraction. Strictly speaking, SystemC is not a language, but rather a library for C++, containing structures for modeling hardware components and their interactions. SystemC can thus be compared to the hardware description languages VHDL and Verilog. An important aspect that these languages have in common is that they all come with a simulation kernel, which allows the designer to evaluate the system behavior through simulations. Nowadays, there exist tools for high-level synthesis of SystemC models; this has pushed the industry to adopt this unied hardwaresoftware design language in large scale. The rest of this section shall introduce the basic data types and structures in the SystemC library together with a set of illustrating examples. Note that we cover only the part of the SystemC language that is needed to nish the assignments in this lab successfully. The interested reader is encouraged to search for additional literature in the library, as well as on Internet. It can also be useful to look into the SystemC language reference manual (LRM), which can be downloaded from the SystemC Web page [3]. We use SystemC version 2.1, which is installed at /home/TDTS07/sw/systemc-2.1.v1. The SystemC library has been compiled with gcc version 3.4.6. You should use the same version when compiling your programs. Type gcc --version at the command line to check your version. Depending on the output, you might have to add a module that gives you access to the correct version by issuing the following commands: module add prog/gcc/3.4.6 module initadd prog/gcc/3.4.6

2.1

Model of time

One of the most important components in the SystemC library is the model of time. The underlying model is based on 64 bits unsigned integer values. However, this is hidden to the programmer through the data type (class) sc_time. Due to the limits of the underlying implementation of time, we cannot represent continuous time, but only discrete time. Therefore, in SystemC there is a minimum representable time quantum, called the time resolution. This can be set by the user, as we shall demonstrate in later parts of this document. Note that this time resolution limits the maximum representable time, because the underlying data type representing the time is a 64-bit integer value. Thus, any time value smaller than the time resolution will be rounded to zero. The default time resolution is set to one picosecondthat is, 1012 seconds. The class sc_time has a constructor of the form sc_time(double, sc_time_unit); where sc_time_unit is an enumerated type (enum in C/C++) with the following attributes: SC_FS (femtosecond) SC_PS (picosecond) SC_NS (nanosecond) SC_US (microsecond) SC_MS (millisecond) SC_SEC (second) The following C++ statement (using the constructor of sc_time) creates an instance t1 of the type sc_time, representing the time 45 microseconds: sc_time t1(45,SC_US); or alternatively (using the copy constructor of sc_time) sc_time t1 = sc_time(45,SC_US); When dealing with sc_time objects, it is sometimes useful to convert them to a oating-point number. This can be achieved by the following statement: double t1_magnitude = t1.to_default_time_units(); In this way we obtain the time in the default time unit. The default time unit can be set by the user; for example, sc_set_default_time_unit(2,SC_MS); sets the default time-unit to 2 milli-seconds. This function may be called only once, and it has to be done in the sc_main function before starting the simulation with sc_start. This shall be explained in Section 2.4. There is also a function for setting the time resolution, which also should be called before simulation start; for example, sc_set_time_resolution(1,SC_US); sets the time resolution to 106 seconds. One special constant is worth mentioning, namely SC_ZERO_TIME which is simply sc_time(0,SC_SEC). Finally, we mention that a lot of arithmetic and boolean operations are dened in the class sc_time, such as, +,-,>,<, etc. For more detailed information, refer to the SystemC language reference manual (LRM), which you can download from the SystemC Web page [3]. 2

2.2

Modules

Modules are the basic building blocks in SystemC. A module comprises ports, concurrent processes, and some internal data structures and channels that represent the model state and the communication between processes. A module can also use another module in a hierarchy. A module is described with the macro SC_MODULE. Actually, the macro SC_MODULE(Module) expands to class Module : public sc_module

where sc_module is the base class for all SystemC modules. Its constructor has a mandatory argument name, which is the name of the created instance; therefore, all modules have a name that is needed mainly for debugging and information purposes. A module must have a constructor. The constructor serves the same purpose as it does for a normal C++ class. Moreover, the constructor, declared functions to be concurrent processes (Section 2.3). The declaration of the constructor is done with the macro SC_CTOR, with the module name as the argument. Thus, a rst template for a simple module could look like the following piece of code: SC_MODULE(TemplateModule) { // ports, processes, internal data, etc... SC_CTOR(TemplateModule) { // Body of constructor // Process declaration, sensitivities, etc... } }; // VERY IMPORTANT! Dont forget that a class/module declaration // should be ended with a semi-colon ; An instance of the module can then be created as follows: TemplateModule instance1("Instance_1"); In this example the constructor only has one argument, namely the module name. Note that it is possible to obtain the name of any instance of the module by writing name() anywhere in the module. This is a function in the base class sc_module. In some cases, you may need more arguments in the constructor. Then the constructor must be declared together with the macro SC_HAS_PROCESS. The following piece of code illustrates the use of the SC_HAS_PROCESS macro: SC_MODULE(TemplateModule) { // ports, processes, internal data, etc... SC_HAS_PROCESS(TemplateModule); TemplateModule(sc_module_name name, int other_parameter) : sc_module(name) { // Body of constructor // Process declaration, sensitivities, etc... } };

2.3

Processes and events

The functionality in SystemC is achieved with processes. As opposed to C++ functions, which are used to model sequential system behavior, processes provide the mechanism for simulating concurrency. A process is a C++ member function of the SystemC module. The function is declared to be a process in the constructor. There are two macros (SC_METHOD and SC_THREAD) which can be used in the constructor for such process registration with the simulation kernel. The two types of processes dier in a number of ways. SC_THREADs are run at the start of simulation, and are run only once. They can suspend themselves with the wait statement, and thus let the simulation resume with another process. Typically, a process of type SC_THREAD contains an innite loop (for(;;)) and at least one wait statement. For example, if you want to suspend a thread for 2 seconds you may write wait(2,SC_SEC); A process of the type SC_METHOD cannot contain any wait statements. Thus, when such a process is started by the simulation kernel, it is run from beginning to end, without any interrupts and in zero simulated time. An SC_METHOD can be sensitive to a set of events. This sensitivity must be declared in the constructor. This declaration makes an event a trigger for a set of processes. Whenever a certain event occurs, it makes the corresponding sensitive processes to become ready for execution. In Section 2.5, we shall illustrate how to declare processes and sensitivities to events. An event e is declared as sc_event e; without any name or other arguments. The only possible action on an event is to trigger it. This is done with the notify function. A SystemC event is the result of such a notication, and has no value and no duration, but only happens at a single point in time and possibly triggers one or several processes. An sc_event can be notied using immediate or timed notication. Immediate notication of e is achieved with e.notify(); The statement e.notify(10,SC_MS); triggers the event e after 10 milliseconds of simulated time (it overrides any previous timed notication that did not yet occur). Sometimes it is useful to cancel a scheduled notication of an event. For example, the most recent scheduled notication of e can be canceled with the statement e.cancel(); Instead of suspending a thread for a given amount of time, it is also possible to use the wait statement with an sc event as an argument. The statement wait(e); suspends the thread until event e is triggered. It is important to note that only wait statements and event notications can advance simulated time.

2.4

Writing a test bench

Having a set of SystemC modules, it is possible to test them by writing a test bench. A test bench is an implementation of the function int sc_main(int argc, char **argv); which is the starting point of the execution. The two parameters argc and argv are the same as for a C++ main function. These contain information about command-line arguments to the program. The sc_main function contains instantiations of a set of modules, as well as an optional part consisting of function calls for setting up the simulation. Thereafter, the function sc_start is called with the simulation time as argument. This starts the simulation phase, and the function returns when the simulation is nished. Note that the function sc_start can be called at most one time. The simulation phase consists of executions of the concurrent processes (SC_METHODs and SC_THREADs) in the instantiated modules. The following piece of code shows a simple template: #include <systemc.h> int sc_main(int argc, char **argv) { // Create instances of the modules // contained in the simulation model // ... // Setup the simulation sc_set_time_resolution(1,MS); // Invoke the simulation kernel sc_start(20,SC_SEC); // or sc_start( sc_time(20,SC_SEC) ); // or sc_start(); for infinite simulation // Clean-up (possibly nothing to do) return 0; } Note that it is possible to set the time resolution. However, this has to be done before the invocation of the SystemC simulation kernel.

2.5

Example 1

We shall now study an example with a SystemC module that represents a counter. The counter is incremented periodically every second. Further, we illustrate how to write a test bench. In the directory /home/TDTS07/tutorial/systemc/counter you may nd the les counter.h and counter.cc that denes a counter module, as well as the test bench counter_testbench.cc. Copy the whole directory to your account. You also nd a make le which together with the gmake tool compiles and links the two .cc-les into an executable called counter.x. Type gmake on the command line to build 5

#ifndef COUNTER_H #define COUNTER_H #include <systemc.h> SC_MODULE(Counter) { int value; sc_event count_event; SC_HAS_PROCESS(Counter); Counter(sc_module_name name, int start = 0); void count_method(); void event_trigger_thread(); }; #endif // COUNTER_H

Figure 1: counter.h the example. This creates an executable called counter.x by compiling and linking the .cc-les together with the SystemC library. Study the sc_main function to nd out how to run the program from the command line. Figures 1 and 2 list the les counter.h and counter.cc respectively, whereas Figure 3 lists counter_testbench.cc. The module Counter has two variablesan integer variable holding the value of the counter and an sc_event that is the event supposed to trigger the part of the module responsible for incrementing the counter. The constructor takes two arguments, the name of the instance and the initial value of the counter. Note that the second argument has the default value 0. The constructor registers two SystemC processes, namely count_method as an SC_METHOD sensitive to count_event, and event_trigger_thread as an SC_THREAD that generates periodic notications of count_event. This makes the simulation kernel call count_method every second. This function increments the counter value, whereafter it prints the current value of the counter to standard output. Note how events are registered to the sensitivity list of SC_METHODs by using the sensitive statement. For example, to register a process called print_method to the events e1 and e2 you should write the following in the constructor of the respective module: SC_METHOD(print_method); sensitive << e1 << e2; Note the use of the function sc_time_stamp() to obtain the current time as an sc_time object. This function can be called anytime during simulation. Also note that event_trigger_thread is an innite loop that uses wait to suspend itself and let the other process execute. Finally, when you run the example, note that the runtime of your program is much less than the simulated time. The runtime (or simulation time) depends on the size of the model, the number of processes, and the complexity of each process itself.

#include "counter.h" #include <iostream> using std::cout; using std::endl; Counter::Counter(sc_module_name name, int start) : sc_module(name), value(start) { SC_THREAD(event_trigger_thread); SC_METHOD(count_method); dont_initialize(); sensitive << count_event; } void Counter::count_method() { value++; cout << sc_time_stamp() << ": Counter has value " << value << "." << endl; } void Counter::event_trigger_thread() { for (;;) { // infinite loop wait(1,SC_SEC); // wait 1 second // then immediately trigger "count_method" through "count_event" count_event.notify(); } }

Figure 2: counter.cc

#include <systemc.h> #include "counter.h" #include <cassert> // for assert(bool) int sc_main(int argc, char **argv) { // Two arguments: (1) the initial counter value, and // (2) the simulation time in seconds assert(argc == 3); int init_value = atoi(argv[1]); sc_time sim_time( atof(argv[2]), SC_SEC); // instantiate module(s) Counter c1("Counter_1", init_value); sc_start(sim_time); // start simulation return 0; }

Figure 3: counter_testbench.cc

2.6

SystemC simulator kernel

Having studied a simple example, let us now study the details of the SystemC simulation semantics. The execution of the simulator kernel can be viewed according to the following list of steps: 1. Initialize. In the initialize phase, each process is executed once; (i.e., SC_METHOD or SC_THREAD). Processes of the type SC_THREADs are executed until the rst synchronization point, that is, the rst wait statement, if there is one. As we have discussed before, it is possible to disable a process for being executed in this phase. This is done by calling dont_initialize() after the corresponding process declaration inside the constructor of the module. Observe that this is only done for processes of type SC_METHOD. 2. Evaluate. Select a ready to run process and execute/resume it. This may cause immediate notications to occur (e.notify()), which may cause more processes to be ready to run in the same phase. The order in which the processes are executed is unspecied, but deterministic, which means that two simulation runs will yield identical results. 3. Repeat step 2 until no more processes to run. 4. Update phase. In this phase, the kernel updates the values assigned to channels in the previous evaluate cycle. We shall describe channels and their behavior in the next section. 5. Steps 24 is referred to as a delta-cycle, just as in VHDL and Verilog. If 2 or 3 resulted in delta event notications (wait(0) or e.notify(0)), go back to step 2 without advancing simulation time. 6. If there are no more timed event-notications, the simulation is nished and the program terminates. 7. Advance to the next simulation time that has pending events. 8. Determine which processes are ready to run due to the events that have pending notications at the current simulation time. Go back to step 2. We now make some very important remarks about immediate and delayed notication. With immediate notication, that is, e.notify(), the event is triggered during the current delta-cycle, which means that any process sensitive to the event will be executed immediately without any update phase. With delayed notication, that is e.notify(SC_ZERO_TIME) or wait(SC_ZERO_TIME), the triggered processes execute during a new delta-cycle, after the update phase.

2.7

Channels and ports

We have now studied how concurrency is handled by using processes and events. This section introduces the basics of channels and ports, which is used to communicate between modules. There are several types of channels in SystemC, and it is also possible to dene customized channels. We shall study one of the basic channels, namely the sc_signal. This is called an evaluateupdate channel, meaning that if some process writes a new

value to the channel, the channels value is changed in the update phase of the simulation kernelthat is, at the end of a delta-cycle. This is done in order to achieve concurrency. For example, if several processes read and write to the same channel in the same delta-cycle, the order of execution of the processes should not have an eect on the functionality. Thus, if a process writes to a channel with a new value, a reader in the same delta-cycle (same time) reads the old value. This can be compared to signals in VHDL. The syntax for declaring a SystemC signal is sc_signal<T> signame; where T is the data type for the signal. Thus, it is possible to create signals with integer values, oating point values, boolean values, etc. For example, the following piece of code shows how to create three dierent signals: sc_signal<int> sig_int; sc_signal<double> sig_double; sc_signal<bool> sig_bool; Reading and writing to signals can be done using the read and write functions. For example, consider the following piece of code in an SC_THREAD, assuming that the current value of sig_int is 0: sig_int.write(1); int value = sig_int.read(); cout << value << endl; wait(SC_ZERO_TIME); value = sig_int.read(); cout << value << endl; sig_bool.write(false); The rst print statement prints 0 on the screen, even though there is a preceding write statement. However, after the wait statement, there has been an update phase, and thus the second print statement prints 1 on the screen. An sc_signal also has an event that is triggered when the signal value changes. Thus, it is possible to have the following statement in an SC_THREAD: wait( sig_int.default_event() ); We shall now describe how to communicate between modules on a channel. For this purpose we shall use ports, which can be viewed as the inputs and outputs of a module. We focus on the two most important basic ports, sc_in<T> and sc_out<T>, which are used to model input and output ports of any data type. We also mention that there is another port type sc_inout<T>. Basically, a port can be viewed as a pointer to a channel. Thus, a port is connected to a channel through an interface that enables reading and writing. In this way, modules can communicate changes to other modules. The following piece of code illustrates how to declare a module with two in ports and one out port: SC_MODULE(Divider) { sc_in<int> numerator; sc_in<int> denominator; sc_out<double> quotient;

// constructor, processes, etc. // ... }; The ports will then be connected to channels at module instantiation. This is demonstrated with an example in the next section. Further, it is possible to initialize a value to out ports in the constructor of the corresponding module. Thus, we could write quotient.initialize(1.5); to initialize the channel connected to the out port to the value 1.5. Reading from and writing to the channels is achieved through the ports by using the read and write methods. Remember that we view a port as a pointer to a channel. Thus, reading from the port numerator is done by using the expression numerator->read(). Similarly, writing a value to the out port is done with quotient->write(4.2). We also mention that we can achieve the same thing by viewing ports as normal variables. Thus, the following statements have the same eect: int sum = numerator + denominator; int sum = numerator->read() + denominator->read(); Similarly, for the write operation, the following statements achieve the same result: quotient = 1.1; quotient->write(1.1); Note that both of the latter updates will have eect only after the evaluate-update cycle, that is, the delta-cycle, as we discussed in the beginning of this section. Finally, the port of type sc_inout<T> is used exactly as the in- and out ports. For this type of port it is possible to both read and write to the channel connected to the port.

2.8

Example 2

In this section, we discuss a divider module, which is implemented with channels and ports. We shall also study a test bench and show how to connect channels to ports. Copy the entire contents of the directory /home/TDTS07/tutorial/systemc/divider to your home directory. You will nd the following les: divider.h, divider.cc, describing a divider module that takes two inputs and computes the quotient whenever any of the two inputs changes. input_gen.h,input_gen.cc, describing an input generator for the divider module. The inputs are read from a text le, given by the user. The text le consists of pairs of integers representing the two inputs. Each row in the le represents one pair of inputs. The le input.txt shows what such a le can look like. monitor.h, monitor.cc, describing a monitor module that takes one input and writes the value to a le as soon as the value is updated. This is used to monitor the output value of the divider module, as will be seen in the test bench. divider_testbench.cc, implements a test bench for a divider module connected to three signals. These signals are also connected to an input generator and a monitor. Study the code to see how to run the simulation. 10

#ifndef DIVIDER_H #define DIVIDER_H #include <systemc.h> SC_MODULE(Divider) { sc_in<int> numerator; sc_in<int> denominator; sc_out<double> quotient; SC_HAS_PROCESS(Divider); Divider(sc_module_name name); void divide_method(); }; #endif

Figure 4: divider.h

#include "divider.h" Divider::Divider(sc_module_name name) :sc_module(name) { quotient.initialize(0); SC_METHOD(divide_method); dont_initialize(); sensitive << numerator << denominator; } void Divider::divide_method() { int num = numerator->read(); int denom = denominator->read(); double q = double(num) / denom; quotient->write(q); }

Figure 5: divider.cc

11

#ifndef INPUT_GEN_H #define INPUT_GEN_H #include <systemc.h> #include <fstream> using std::ifstream; SC_MODULE(Generator) { sc_out<int> numerator; sc_out<int> denominator; SC_HAS_PROCESS(Generator); Generator(sc_module_name name, char *datafile); ~Generator(); void generate_thread(); // variables ifstream *in; }; #endif

Figure 6: input_gen.h

#include "input_gen.h" #include <cassert> Generator::Generator(sc_module_name name, char *datafile) : sc_module(name) { assert(datafile != 0); // not null in = new ifstream(datafile); // open file assert(*in); // check that everything is OK SC_THREAD(generate_thread); numerator.initialize(0); denominator.initialize(0); } Generator::~Generator() { delete in; } void Generator::generate_thread() { int num, denom; for (;;) { wait(1,SC_SEC); // generate new inputs every second *in >> num >> denom; // read from file numerator->write(num); denominator->write(denom); } }

Figure 7: input_gen.cc

12

#ifndef MONITOR_H #define MONITOR_H #include <systemc.h> #include <fstream> using std::ofstream; SC_MODULE(Monitor) { sc_in<double> quotient; sc_in<int> denominator; SC_HAS_PROCESS(Monitor); Monitor(sc_module_name name, char *outfile); ~Monitor(); void monitor_method(); void check_constraints_method(); // variables ofstream *out; }; #endif

Figure 8: monitor.h
#include "monitor.h" #include <cassert> Monitor::Monitor(sc_module_name name, char *outfile) : sc_module(name) { assert(outfile != 0); out = new ofstream(outfile); assert(*out); SC_METHOD(monitor_method); dont_initialize(); sensitive << quotient; SC_METHOD(check_constraints_method); dont_initialize(); sensitive << denominator; } Monitor::~Monitor() { delete out; } void Monitor::monitor_method() { double q = quotient->read(); *out << "quotient(" << sc_time_stamp() << ") = " << q << endl; } void Monitor::check_constraints_method() { assert( denominator != 0 ); }

Figure 9: monitor.cc 13

#include #include #include #include

<systemc.h> "divider.h" "input_gen.h" "monitor.h"

int sc_main(int argc, char **argv) { // The command line arguments are as follows: // 1. simulation time (in seconds) // 2. file with input data (see input.txt for example) // 3. file to write output data assert(argc == 4); sc_time sim_time( atof(argv[1]), SC_SEC); char *infile = argv[2]; char *outfile = argv[3]; // create channels sc_signal<int> numerator_sig; sc_signal<int> denominator_sig; sc_signal<double> quotient_sig; // create modules Divider divider("Divider"); Generator gen("Generator", infile); Monitor monitor("Monitor", outfile); // connect channels to ports divider(numerator_sig,denominator_sig,quotient_sig); gen(numerator_sig,denominator_sig); monitor(quotient_sig,denominator_sig); // start simulation sc_start(sim_time); return 0; }

Figure 10: divider_testbench.cc

14

 Makefile. Finally, there is a make le, which helps you build the program using gmake. The created executable is called divider.x. The source code for the whole example is listed in Figures 410. Study the source code carefully and revisit the dicussions in this document to understand the example. You may also make modications to the example to further try things out. Before we end this section we make some remarks regarding parts of the source code listed in the gures. First, in divider.cc, note that divide_method is sensitive to both the two in ports. That is, if any of the in ports is updated with a new value, the divide method will be triggered. In the implementation of the input generator and the output monitor, we use the C++ classes ifstream and ofstream for achieving le I/O. Finally, there are many interesting things in divider_testbench.cc. First, we create three signals that represent the two inputs and the output in the divider module. After the modules are instantiated, we must connect the signals to the ports of the modules. This is done in positional form for all instances. For example, for the instance divider, this is done with the following statement: divider(numerator_sig, denominator_sig, quotient_sig); This connects the signals, in the order they are listed, to the ports in the order they are declared in the module declaration. Thus, the order of the signals in the previous statement is important in order to connect the signals to the ports correctly. It is also possible to use named form to connect the signals to the ports. For example, the following statements have the same eect as the positional form used for the divider module: divider.numerator(numerator_sig); divider.quotient(quotient_sig); divider.denominator(denominator_sig); Here, the order does not matter anymore. The rst form is more compact, whereas the second form is more clear.

Optional exercise
Change the divider example in Section 2.8 such that the inputs are generated by the Counter module (Section 2.5) instead of by the Generator module. Further, instead of waiting a second before each increment step in the counter, you should wait for a random amount of time between 1 second and 10 seconds. You are free to make appropriate changes to the source code for both the examples.

Assignment: Trac light controller

In this assignment, your task is to model a trac light controller and to implement it in SystemC. Further, you shall simulate your system to check some properties. The trac light controller is specied as follows: The system must control the lights in a road crossing. There are four lights, one for vehicles traveling in direction North South (NS), one for vehicles traveling in direction SN, one for the direction WestEast (WE), and one for the direction EW, and respectively four sensors that detect vehicles in a particular direction. The system must satisfy the following properties:

15

1. The lights shall work independently. For example, if the light NS is green, the light SN is red if there are no cars coming in the direction SN. 2. Of course, safety constraints apply. For instance, SN must not be green at the same time as WE is green. 3. If a vehicle arrives at the crossing (as detected by the respective sensor) it will eventually be granted green light. You must describe the controller in SystemC, and further, using print statements, le I/O, or monitors, implement functionality to demonstrate that all the mentioned properties hold during simulation. To check the properties and to study the execution of your system, you have to generate trac at the trac lights. To demonstrate that your implementation satises the required properties, you must run the controller with trac that is generated randomly and with trac generated in a way that specically targets to check some of the properties. The lights must be represented by boolean channels. The arrival of cars must be modeled with events, for example using sc_event or the change of value of a boolean channel. Examination: You must write and hand in a report in which you present and explain your implementation. In the report, you must describe the simulations you have conducted to validate your solution. You must present the simulation results and explain them in sucient detail.

References
[1] D.C. Black and J. Donovan. SystemC: From The Ground Up. Eclectic Ally, 2004. [2] T. Grtker, S. Liao, G. Martin, and S. Swan. System Design with SystemC. Kluwer o Academic Publishers, 2002. [3] SystemC homepage. http://www.systemc.org.

16