systemc

1. Naming Conventions

1.1 Filenames

1.2 Class/Module Naming

1.3 Port Naming (RTL Matching)

SystemC ports use the same names as their RTL counterparts:

sc_in<sc_uint<8>>  i_data{"i_data"};
sc_out<bool>        o_valid{"o_valid"};
sc_in<bool>         sys_clk{"sys_clk"};       // clock: no i_/o_ prefix
sc_in<bool>         sys_rst_n{"sys_rst_n"};   // reset: no i_/o_ prefix

2. Reference Model Rules

2.1 Core Principles

• Bit-accurate: Must guarantee identical bit-level results as the RTL
• Cycle-agnostic: Implements only the algorithm, with no timing concepts
• Deterministic: Same input → same output guaranteed (no random, no float)
• Standalone: Must be compilable as pure C/C++ without SystemC

2.2 Interface Patterns

class cabac_ref_model {
public:
  static uint32_t encode_bin(uint16_t ctx_addr, bool bin_val,
                             const ctx_table_t& ctx_table);
  void process_block(const block_input_t& input, block_output_t& output);
  void reset();
private:
  ctx_table_t m_ctx_table;
};

2.3 Fixed-Point Rules

• Use fixed-width integers such as int16_t, uint32_t (no int, no float)
• Explicitly specify overflow behavior: saturate vs wrap

// CORRECT: bit-exact fixed-point multiply
int32_t fixed_mul(int16_t a, int16_t b) {
  return static_cast<int32_t>(a) * static_cast<int32_t>(b);
}

// WRONG: implicit promotion may differ from RTL
int result = a * b;  // 'int' width is platform-dependent

3. BFM (Bus Functional Model) Rules

3.1 Core Principles

• Cycle-accurate: Produce results in the same number of cycles as RTL
• AT non-blocking by default: Use nb_transport_fw/bw() (LT only when explicitly requested)
• Separate pin-adapter: Separate TLM abstraction from pin-level interface
• AXI as default protocol: AHB/APB/ACE only when explicitly requested

3.2 Coding Styles

3.3 AT 4-Phase Protocol

Initiator                    Target
    |-------- BEGIN_REQ ------->|
    |<------- END_REQ ----------|
    |<------- BEGIN_RESP -------|
    |-------- END_RESP -------->|

3.4 Required Headers

#include <systemc>
#include <tlm>
#include <tlm_utils/simple_initiator_socket.h>
#include <tlm_utils/simple_target_socket.h>
#include <tlm_utils/peq_with_cb_and_phase.h>  // AT phase scheduling
// #include <amba_pv.h>  // AMBA protocol extensions (when needed)

3.5 BFM Architecture

┌────────────┐  AT nb_transport  ┌────────────┐
│ Testbench  │◄──── fw/bw ─────►│    BFM     │
│ (Initiator)│                   │(Cycle-acc.)│
└────────────┘                   └─────┬─────┘
                                       │ Pin Adapter
                                ┌──────▼──────┐
                                │ RTL Wrapper  │   (optional)
                                │ (sc_signal)  │──► DPI-C ──► SV TB
                                └─────────────┘

4. Memory Manager (Payload Pooling)

Required component for payload reuse in AT models:

class MemoryManager : public tlm::tlm_mm_interface {
public:
    tlm::tlm_generic_payload* allocate() {
        if (m_pool.empty()) return new tlm::tlm_generic_payload(this);
        auto* p = m_pool.back(); m_pool.pop_back(); return p;
    }
    void free(tlm::tlm_generic_payload* p) override {
        p->reset(); m_pool.push_back(p);
    }
    ~MemoryManager() override { for (auto* p : m_pool) delete p; }
private:
    std::vector<tlm::tlm_generic_payload*> m_pool;
};

Usage: m_mm.allocate() → trans->acquire() → ... → trans->release()

5. AMBA-PV Protocol Selection

Default AXI extension setup:

#include <amba_pv.h>

auto* ext = new amba_pv::axi_extension();
ext->set_id(0);
ext->set_burst(amba_pv::AXI_BURST_INCR);  // Incrementing (most common)
ext->set_length(burst_len);                // AxLEN (beats - 1)
ext->set_size(log2(beat_size));            // AxSIZE
ext->set_cache(0xF);                       // Write-back, allocate
ext->set_prot(0x0);                        // Unprivileged, secure, data
trans.set_extension(ext);

See the <Advanced> section for AHB/APB/ACE details and AXI attribute tables.

6. Build Rules

# Reference Model (standalone C, no SystemC)
gcc -std=c11 -O2 -Wall -Wextra -Werror -shared -fPIC -o ref_cabac.so ref_cabac.c

# BFM (SystemC required)
g++ -std=c++17 -O2 -Wall -Wextra \
  -I${SYSTEMC_HOME}/include -L${SYSTEMC_HOME}/lib-linux64 -lsystemc \
  -o tb_cabac tb_cabac_top.cpp bfm_cabac.cpp

# cocotb integration (shared library, C ref model)
gcc -std=c11 -shared -fPIC -o ref_cabac.so ref_cabac.c

cocotb integration:

import ctypes
lib = ctypes.CDLL("./ref_cabac.so")
lib.encode_bin.restype = ctypes.c_uint32
lib.encode_bin.argtypes = [ctypes.c_uint16, ctypes.c_bool]
expected = lib.encode_bin(ctx_addr, bin_val)

7. Coding Style

7.1 Mandatory

• C++17 (not C++20), fixed-width integers (<cstdint>), RAII, const, Header guard
• AT models: use MemoryManager + PEQ

7.2 Prohibited

• float/double in bit-exact models
• malloc/free, platform-dependent int
• using namespace std; in headers
• LT b_transport in performance BFMs (use AT)