Kernel Source Map

Reading the Accellera SystemC Proof-of-Concept (PoC) source code is easier when you know which files map to which IEEE 1666 LRM concepts. This page is a map. It is not a replacement for the LRM, but it bridges the gap between theoretical standards and actual C++ implementation.

When a simulator behaves unexpectedly, stepping through these specific files in GDB or Visual Studio is the fastest way to understand the kernel's rules.

Core Simulation Context

LRM Reference: Section 4 (Elaboration and Simulation Semantics) Source Files:

• sysc/kernel/sc_simcontext.h
• sysc/kernel/sc_simcontext.cpp

The simulation context (sc_simcontext) is the beating heart of SystemC. It owns the scheduler state, registries for all objects, the delta cycle counter, the timed event queues, the currently executing process, the current simulation time (sc_time_stamp), and the phase transition logic (elaboration -> initialization -> evaluation -> update). When you ask "who knows what simulation time it is?", this is the area to read.

Modules and Object Hierarchy

LRM Reference: Section 5 (Module and Hierarchy) Source Files:

• sysc/kernel/sc_object.*
• sysc/kernel/sc_module.*
• sysc/kernel/sc_module_name.*

This area explains names, hierarchy, construction context, child objects, and the relationship between C++ construction and SystemC elaboration. sc_object handles the tree structure, while sc_module_name manages the stack-based scoping that assigns child objects to their parents during C++ constructors.

Processes and Scheduling

LRM Reference: Section 5.2 (Processes) Source Files:

• sysc/kernel/sc_process.*
• sysc/kernel/sc_method_process.*
• sysc/kernel/sc_thread_process.*
• sysc/kernel/sc_spawn.*

This area explains how SC_METHOD, SC_THREAD, dynamic processes (sc_spawn), resets, sensitivity lists, and process state (Runnable, Suspended, Terminated) are represented internally. SystemC threads are typically implemented using user-level cooperative threads (coroutines), often utilizing QuickThreads (qt) or POSIX threads under the hood.

Events and Time

LRM Reference: Section 5.10 (sc_event) and Section 5.11 (sc_time) Source Files:

• sysc/kernel/sc_event.*
• sysc/kernel/sc_time.*

This area explains immediate, delta, and timed notifications. It also shows why sc_time is not just a standard integer: it represents time accurately scaled against the selected global time resolution (sc_set_time_resolution), preventing rounding errors across the simulation.

Ports, Exports, and Interfaces

LRM Reference: Section 5.12 (sc_interface), 5.13 (sc_port), 5.14 (sc_export) Source Files:

• sysc/communication/sc_port.*
• sysc/communication/sc_export.*
• sysc/communication/sc_interface.h

This area explains hierarchical binding, interface method dispatch, bind-count checking, and the reason ports can call methods on channels without knowing the concrete channel type (pure virtual interfaces).

Signals and Primitive Channels

LRM Reference: Section 6 (Predefined Channels) Source Files:

• sysc/communication/sc_prim_channel.*
• sysc/communication/sc_signal.*
• sysc/communication/sc_writer_policy.*

This area explains the request-update semantics (request_update()), single/many writer checks, value-changed events, and why sc_signal writes take effect securely in the kernel's update phase, preventing combinational races.

TLM-2.0 Standard

LRM Reference: Section 10 to 16 (TLM-2.0) Source Files:

• tlm_core/tlm_2/tlm_generic_payload/tlm_gp.h
• tlm_core/tlm_2/tlm_sockets/*
• tlm_utils/simple_initiator_socket.h
• tlm_utils/simple_target_socket.h
• tlm_utils/peq_with_cb_and_phase.h
• tlm_utils/tlm_quantumkeeper.h

This area implements the generic payload extensions, initiator/target socket composition, blocking/non-blocking protocol phases, payload event queues (PEQ), and temporal decoupling (quantum keeper) helpers.

Complete Example: Accessing Kernel Internals

While you shouldn't rely on implementation-specific APIs, the LRM does guarantee certain kernel introspection APIs. This complete sc_main demonstrates querying the simulation context and object hierarchy.

#include <systemc>
#include <iostream>
#include <vector>
 
SC_MODULE(KernelMapDemo) {
    SC_CTOR(KernelMapDemo) {
        SC_THREAD(run);
    }
    
    void run() {
        wait(10, sc_core::SC_NS);
        
        // LRM API to check simulation status
        std::cout << "[Kernel] Current Time: " << sc_core::sc_time_stamp() << "\n";
        std::cout << "[Kernel] Delta Count: " << sc_core::sc_delta_count() << "\n";
        
        // LRM API to query the object hierarchy
        std::cout << "[Kernel] Module Name: " << this->name() << "\n";
        std::cout << "[Kernel] Object Kind: " << this->kind() << "\n";
        
        sc_core::sc_stop();
    }
};
 
int sc_main(int argc, char* argv[]) {
    KernelMapDemo demo("kernel_demo");
    
    // LRM API to check engine status
    std::cout << "Engine status before start: ";
    if (sc_core::sc_get_status() == sc_core::SC_ELABORATION) {
        std::cout << "ELABORATION\n";
    }
 
    sc_core::sc_start();
    
    std::cout << "Engine status after stop: ";
    if (sc_core::sc_get_status() == sc_core::SC_STOPPED) {
        std::cout << "STOPPED\n";
    }
 
    return 0;
}

Explanation of Execution

Engine status before start: ELABORATION
[Kernel] Current Time: 10 ns
[Kernel] Delta Count: 1
[Kernel] Module Name: kernel_demo
[Kernel] Object Kind: sc_module
Engine status after stop: STOPPED

By tracing through sc_simcontext.cpp, you can see exactly how sc_get_status() updates its internal state machine from SC_ELABORATION -> SC_RUNNING -> SC_STOPPED. Understanding this source map allows you to debug complex deadlock or ordering issues rapidly.