systemc-tools

SystemC Tools

Use this skill for synthesizable SystemC code development and review in projects using ICSC and the SingleSource library. Apply it when implementing modules, records, channels, process code, assertions, or when reviewing existing code for synthesis, simulation, and SystemVerilog generation risks.

Workflow

1. Identify the task type: implementation, refactor, debug, or review.
2. Read the nearby code first: module ports, constructor bindings, process declarations, sensitivity lists, reset logic, channel usage, and tests.
3. Check synthesis constraints before changing behavior: process kind, supported data types, control flow, function calls, dynamic allocation, and pointer usage.
4. Prefer existing project patterns over introducing new abstractions.
5. For edits, keep changes local to the relevant module, record, or helper.
6. Validate with the narrowest relevant test or build target. For CMake projects, use the CMake Tools build/test tools.
7. In reviews, lead with correctness, synthesis mismatch, reset/sensitivity, handshake, and missing-test risks.

Project Structure

• Expect a main source file such as sc_main.cpp containing the SystemC entry point and testbench/top instantiation.
• A design normally has one translated top module, selected by ELAB_TOP when required.
• Keep design modules in headers/source files organized by protocol or block ownership.
• Keep testbench-only logic separate from synthesizable module logic.
• Avoid global or namespace variables for design state. Global and namespace constants are acceptable when they are compile-time constants.

Module Hierarchy

• A module is a C++ class or structure inheriting sc_module.
• A modular interface inherits both sc_interface and sc_module; ICSC flattens it into the parent module in generated SystemVerilog.
• A pure interface inherits sc_interface only and is not part of the module hierarchy.
• Instantiate modules and modular interfaces inside parent modules, except top-level instances in sc_main or testbench hierarchy.
• Do not pass modules, modular interfaces, or pointers to them as function parameters or return values.
• Do not use module or modular interface types as signal or port payload types.

Modules And Modular Interfaces

• Use explicit ports, signals, and SingleSource channels for interconnect.
• Avoid direct field access across normal module boundaries.
• Access child modular interface fields and methods only when they are flattened into the same generated module.
• Access modular interface methods through sc_port<IF> or a parent-owned pointer only when the connected interface is valid for flattening.
• Keep module ownership clear: one parent owns each child module/interface instance.
• Avoid multiple pointers to the same heap-allocated SystemC object.

Module Constructors

• Every module and modular interface needs a constructor with sc_module_name, or SC_CTOR when suitable.
• Constructor bodies may create processes, bind ports/channels, allocate elaboration-time objects, and call elaboration-time helper functions.
• Prefer static/member object construction over dynamic allocation.
• If dynamic allocation is needed, use it only during elaboration. Use new for SystemC objects where supported, and sc_new or sc_new_array for non-sc_object data.
• Bind all child ports and channels in constructors. Unconnected child ports may be promoted to top-level ports.
• Initialize constants in-place, in constructor initializer lists, or in supported elaboration callbacks.
• Initialize non-constant runtime state in reset code, not as a substitute for reset behavior.

Process Code

• Use SCT_METHOD to create combinational method process. Use SCT_THREAD macro to create sequential thread process. Use SC_CTHREAD macro only in testbench and only if it required, for example for process without sensitivity. Never use SCT_CTHREAD macro.
• Use method processes for combinational logic and simple sequential methods where project conventions allow.
• Use thread processes when multiple states or explicit wait() calls simplify the design.
• A combinational method must be sensitive to every signal, port, or channel it reads.
• A method must not read a signal or port that it writes in the same process.
• A thread reset section is the code before the first wait(); reset modified channels and register variables there.
• Avoid to have any code between reset section wait() and the main loop. One exception is if multi-cycle initialization is required for an object like memory or complex data structure used in the process.
• Keep the main thread loop simple. Prefer one wait() at the end of the loop unless a real multi-state protocol is needed.
• Assertions in thread processes should be before the main loop, not inside it, unless using a supported loop assertion form.
• Do not put unsupported function calls or side effects in process sensitivity, loop conditions, or complex conditions.

Data Types And Literals

• Prefer SystemC/SCT integer types over C++ integer types for hardware-width values.
• Use bool for one-bit Boolean intent and loop variables such as int or unsigned for simple static loops.
• Prefer sct_uint<N> and sct_int<N> for bit-accurate widths, including optional zero-width fields.
• Use sc_biguint<N> and sc_bigint<N> when exact wide arithmetic behavior is more important than simulation speed.
• Avoid unsupported types: sc_lv, sc_logic, sc_signed, sc_unsigned, fixed-point types, and floating-point types in synthesizable code.
• Do not mix signed and unsigned values in one expression unless explicitly cast and reviewed.
• Use string literals for numeric literals wider than 64 bits.
• Use sct_zeros<N> and sct_ones<N> for all-zero and all-one SCT literals.
• Remember that uninitialized local SystemC integer variables are zero-initialized by their constructors.

Channels And Ports

• Use sct_signal, sct_in, and sct_out for SingleSource signal and port interconnect when that is the project convention.
• Use sc_signal, sc_in, and sc_out where the surrounding code already uses standard SystemC ports/signals.
• Connect sibling modules through parent-owned signals or through supported SingleSource channels.
• Bind ports through hierarchy only when ownership and direction remain clear.
• Ensure all ports are connected in design or testbench; otherwise expect top-port promotion.
• For target/initiator channels, bind endpoints in the common parent and connect clock/reset with clk_nrst() where required.
• Add every accessed SingleSource channel or signal/port to process sensitivity according to the process kind.
• Avoid combinational loops in FIFO/channel ready-valid paths.

Collections

• Built-in arrays and std::array are supported for data and many SystemC objects, but follow local code style.
• Prefer sc_vector for arrays of signals, ports, modules, and modular interfaces when supported.
• Keep pointer arrays homogeneous. Elements should be all nullptr or all allocated objects of the same concrete class.
• Avoid non-rectangular pointer data structures except for supported module-array cases.
• Do not index a signal/port array or record array using the same array element when that pattern is unsupported.
• Do not pass sc_vector to or return it from functions.

Structures

• Use records for plain data payloads, not for modules, channels, signals, ports, or ownership.
• Records used in channels or ports should have a default constructor, operator==, operator<<, and sc_trace when required by the channel/port type.
• Keep records trivially copyable where they are passed by value or returned from functions.
• Records cannot contain pointers, references, modules, modular interfaces, signals, or ports in synthesizable payload code.
• Avoid nested records when ICSC restrictions apply.
• Record constructors may contain function calls, but field in-place initialization and initializer lists must not call functions.

Control Flow

• Conditions for if, ?:, for, while, and do while must be side-effect free.
• if and ternary conditions may call side-effect-free functions without wait().
• for, while, and do while conditions must not call functions.
• Method range() arguments for sct_uint, sct_int and other bit-accurate types in loop if loop counter is used as index should use of the following form: range(i+N, i) or range(i, i-N)or range(M*i + N, M*i) where i is the loop counter, M and N are constants. The same is applicable for operator () for sct_uint, sct_int and other bit-accurate types which has the same semanthic as range().
• Static loops without wait() must have statically determinable iteration counts.
• Loops with wait() may have dynamic iteration counts, but every path must respect process wait/reset rules.
• switch cases need one final break, or return-only cases in supported function patterns. Do not mix break and return styles in one switch.
• Avoid break and continue in main loops and loops containing wait().
• Do not use goto.

Arithmetical Operations

• Operator comma (operator ,) for sct_uint, sct_int and other bit-accurate types concatenates arguments therefore it requires correct order of arguments and their bit widths.
• Preserve bit widths intentionally. Cast intermediate expressions when overflow or promotion could change generated SV behavior.
• Never mix signed and unsigned operands casually; this is a common SystemC versus SV mismatch source.
• Avoid bitwise ~ on C++ bool; use logical !.
• Review >>, /, and % carefully with sc_bigint or sc_biguint; use a single big variable operand where required.
• Avoid left-shift overflow on C++ integer types.
• For protocol bit packing, keep struct member order, documented bit ranges, toBits(), and fromBits() in exact agreement.
• Prefer explicit width constants and typedefs for

Content truncated.