SystemC Tutorial for Beginners

Start here if you want SystemC to feel like understandable C++ instead of magic macros. The lessons build from the first model into the LRM rules and source internals that explain why the simulator behaves the way it does.

What This Page Helps You Do

Recommended Path

Your first milestone: observe simulation time

Start with a model small enough to explain line by line. The goal is to distinguish constructing an object from running a simulation process. You need basic C++ classes and functions, a compiler, and a SystemC installation built for that compiler. Follow the installation guide before trying this exercise.

Save this as main.cpp:

#include <systemc>
#include <iostream>

SC_MODULE(Pulse) {
  void run() {
    std::cout << "start: " << sc_core::sc_time_stamp() << '\n';
    wait(5, sc_core::SC_NS);
    std::cout << "resumed: " << sc_core::sc_time_stamp() << '\n';
  }

  SC_CTOR(Pulse) { SC_THREAD(run); }
};

int sc_main(int, char**) {
  Pulse pulse("pulse");
  sc_core::sc_start();
  return 0;
}

Build it using the CMake project in Build SystemC and Write a First Model. That guide explains how to locate and link your installed SystemC library. Run the resulting executable; the model prints these two lines in addition to any library startup banner:

start: 0 s
resumed: 5 ns

Why those two lines appear

1. Pulse pulse("pulse") constructs the module. Its constructor registers run as a thread process; it does not call the function directly.
2. sc_start() starts the scheduler. During initialization, the thread begins and prints the current simulation time.
3. wait(5, sc_core::SC_NS) suspends this thread. It specifies simulated time, so it is not a five-nanosecond sleep on your computer.
4. The scheduler resumes the thread at 5 ns. The function prints again and returns. With no remaining activity, this simulation finishes.

Try a change, then predict the result

Change the wait to 12 ns. Before running, write down which output line should change. Only the second timestamp changes. Next, put another 5 ns wait and print after the first wait: the timestamps become 0, 5, and 10 ns because each wait is relative to when the thread calls it.

Keep SC_THREAD for this experiment. A method process has different suspension rules; replacing it with SC_METHODwhile retaining wait() is an error. Continue with processes, events, and time to learn when each process type fits.

If the first model does not run

• Header not found: check the include directory or the SystemC CMake package location. Installing a compiler alone does not install SystemC.
• Unresolved SystemC symbols: check that the executable links the SystemC library and that compiler, architecture, and library build settings agree.
• Shared library missing at startup: compilation succeeded, but the operating system cannot locate the runtime library. Follow the platform-specific runtime-path instructions in the setup lesson.
• No model output: confirm that the process is registered and that sc_main calls sc_start().

Choose the next exercise

Once you can explain both timestamps, move to module hierarchy and then ports and channels. Your next milestone is two modules communicating through a signal. Leave TLM and virtual platforms until you can explain when a process runs and how information moves between modules.

Standard reference: IEEE 1666-2023, clauses 4.2.3 (process registration), 4.3 (simulation), and 5.2.17 (wait). Find the official standard and reference implementation through the official resources guide.

What You Should Be Able to Answer

• Is SystemC a new language? No. It is a C++ library and simulation kernel that gives hardware-modeling semantics to ordinary C++ objects.
• What should I learn first? Learn modules, elaboration, processes, events, and ports before diving into TLM or virtual platforms.