How to Read This Lesson

Start here slowly. The goal is not to memorize APIs yet; it is to build the mental model you will reuse in every later SystemC design review.

Downloading and Installing SystemC

Since SystemC is a C++ library, you do not install an "executable" or an "IDE". You must download the source code, compile it into a static library (.a or .lib), and then link your own C++ code against it.

The official reference implementation is maintained by the Accellera Systems Initiative.

Source and LRM Trail

For this foundation lesson, keep three references close: Docs/LRMs/SystemC_LRM_1666-2023.pdf for portable semantics, .codex-src/systemc/src/sysc/kernel for kernel behavior, and .codex-src/systemc/src/sysc/datatypes for bit-accurate C++ types. When this lesson mentions a macro or type, the useful habit is to ask which C++ class the macro eventually creates.

Step 1: Download the Source Code

1. Go to the Accellera Systems Initiative Download Page.
2. Download the latest SystemC Core source code (e.g., SystemC 2.3.3 or 2.3.4).
3. Extract the .tar.gz or .zip file to a permanent directory on your machine (e.g., /opt/systemc on Linux or C:\systemc on Windows).

Step 2: Compiling the Library

On Linux / macOS (Using CMake & GCC/Clang)

Modern SystemC provides a CMakeLists.txt making installation vastly easier than the old autotools method.

1. Open your terminal and navigate to the extracted SystemC directory:

   cd /path/to/systemc-2.3.3

2. Create a build directory and run CMake:

   mkdir build && cd build
   cmake .. -DCMAKE_CXX_STANDARD=14

3. Compile and install (this usually installs to /usr/local/systemc by default, or the path specified via CMAKE_INSTALL_PREFIX):

   make -j4
   sudo make install

On Windows (Using Visual Studio)

1. Open the extracted folder and navigate to the msvc10 or msvc14 directory (depending on your Visual Studio version).
2. Open the SystemC.sln solution file in Visual Studio.
3. Select your desired configuration at the top: Debug or Release, and x64.
4. Right-click the SystemC project in the Solution Explorer and click Build.
5. Once finished, the compiled .lib files will be located in the Debug or Release folder within the MSVC directory.

Step 3: Compiling Your First Program

Once the library is built, you can write a main.cpp file:

#include <systemc.h>
 
int sc_main(int argc, char* argv[]) {
    std::cout << "Hello, SystemC World!" << std::endl;
    return 0;
}

Compiling on Linux (g++)

You must tell the compiler where the SystemC headers (-I) and library files (-L) are located, and explicitly link the systemc library (-lsystemc).

g++ main.cpp -o hello_systemc \
    -I/usr/local/systemc/include \
    -L/usr/local/systemc/lib-linux64 \
    -lsystemc -lm

Compiling on Windows (Visual Studio)

In your own project properties:

1. C/C++ -> General -> Additional Include Directories: Add C:\systemc\src.
2. C/C++ -> Preprocessor -> Preprocessor Definitions: Add _CRT_SECURE_NO_WARNINGS.
3. Linker -> General -> Additional Library Directories: Add C:\systemc\msvc14\SystemC\x64\Release.
4. Linker -> Input -> Additional Dependencies: Add SystemC.lib.

Using CMake (Recommended)

Instead of typing out GCC flags or clicking through Visual Studio menus, the industry standard is to use CMake to build your projects. You can write a CMakeLists.txt based on the example in the previous step and use it for any future tutorials.

Let's Connect This to the Standard and the Source

When you compile and link the Accellera SystemC library, you are pulling together the mechanisms defined in the IEEE 1666-2023 Language Reference Manual (LRM). The library contains the simulation kernel, data types, and synchronization primitives. Understanding what happens at the linker level and what sc_main truly is will save you countless hours of debugging.

The True Entry Point: main() vs sc_main() (IEEE 1666 Section 4.3)

According to the LRM, the entry point for a SystemC application is a function named sc_main. However, standard C++ applications must start at main().

If you inspect the Accellera source code, specifically src/sysc/kernel/sc_main_main.cpp, you will find the definition of the actual C++ main() function:

int main( int argc, char* argv[] )
{
    // ... setup error handlers ...
    return sc_core::sc_elab_and_sim( argc, argv );
}

The library itself provides the main() function. When you compile your project, your sc_main function is linked as a callback. The flow is as follows:

1. The OS executes main().
2. main() calls sc_elab_and_sim() (src/sysc/kernel/sc_main.cpp).
3. sc_elab_and_sim() initializes the global sc_simcontext.
4. sc_elab_and_sim() calls the user's sc_main(argc, argv).

Because the SystemC library provides main(), it is an error to define your own main() function in a SystemC project unless you explicitly circumvent the standard linkage (which is highly discouraged and violates the LRM). If you see a linker error like multiple definition of 'main', it means you mistakenly defined int main() instead of int sc_main().

Static Initialization and sc_simcontext Bootstrapping

SystemC relies heavily on the C++ Static Initialization Order Fiasco. Many core SystemC objects, such as sc_module_name strings, dynamically register themselves with the global simulation context before main() even executes.

In src/sysc/kernel/sc_simcontext.cpp, the sc_get_curr_simcontext() singleton is instantiated globally. If you allocate an sc_module globally (outside of sc_main), the constructor of that module will execute during the static initialization phase before main() is called. While IEEE 1666 Section 4.3 allows for module instantiation during static initialization, it is highly recommended to instantiate all modules inside sc_main to ensure a predictable elaboration sequence.

Library Targets: sc_core and sc_dt (IEEE 1666 Sections 5 & 7)

When you link -lsystemc, you are linking an archive containing several distinct namespaces defined by the IEEE 1666 standard:

• sc_core: The core kernel (src/sysc/kernel), event scheduler, module hierarchy, and communication interfaces (src/sysc/communication). This handles the temporal decoupling, quantum-keeping, and the Delta Cycle.
• sc_dt: The bit-accurate datatypes (src/sysc/datatypes), such as sc_int, sc_uint, sc_logic, sc_bv, and sc_lv. These types are highly optimized templates designed to mimic hardware vector arithmetic.

Environment Variables and Tooling Integration

The Accellera implementation honors several environment variables that affect execution behavior:

• SYSTEMC_HOME: While not required by the kernel at runtime, it is the standard environment variable used by Makefiles and CMake scripts to locate the installed library and headers.
• SC_COPYRIGHT_MESSAGE: Set to DISABLE to prevent the Accellera copyright banner from printing when the simulation starts. The LRM does not mandate this banner, but it is a signature of the PoC implementation.

C++ Standards Compatibility

SystemC is deeply intertwined with the C++ standard it is compiled against. IEEE 1666-2023 officially targets C++17 as a baseline. When building the Accellera source code, it is critical that both the library itself and your application code are compiled using the exact same C++ standard flag (e.g., -std=c++17). Mismatched standards can lead to binary incompatibility, varying sizeof() values for structs, and silent segmentation faults due to mismatched vtables.