Core API and Source Symbol Field Guide

How to Read This Lesson

This is a field guide for the names that show up when you move from normal tutorials into the LRM and the Accellera source tree. Do not try to memorize every private helper. Use each symbol as a breadcrumb: public modeling concept first, C++ implementation mechanism second.

Standard and source context

Use Docs/LRMs/SystemC_LRM_1666-2023.pdf for the normative API and behavior. Use .codex-src/systemc/src/sysc for implementation reading, especially kernel, communication, datatypes, tracing, and utils.

Object Model and Attributes

sc_object is the root of the visible hierarchy story. Most things a user can name, find, or inspect inherit from it or cooperate with it. sc_attr_base, sc_attribute, and sc_attr_cltn are the lightweight attribute mechanism around that object model. They are not the same as CCI parameters. Think of them as attached metadata for SystemC objects, while CCI is a configuration and inspection standard with brokers, originators, callbacks, and mutability rules.

sc_find_object and sc_find_event are lookup helpers. They are convenient in debug tools, but production model connectivity should usually be explicit through constructors, ports, exports, and configuration objects.

sc_hierarchy_scope, sc_object_host, sc_module_name, and sc_gen_unique_name belong to the naming and construction machinery. When a module constructor runs, the implementation needs to know which parent is currently being elaborated. That is why names can become hierarchical without you manually passing every parent path.

Process and Simulation Context

sc_simcontext is the simulation kernel owner. It tracks elaboration, process registries, event queues, time, runnable processes, update requests, and simulation status. When you call sc_start, you are not just entering a loop; you are asking this context to run the scheduled world that elaboration built.

sc_curr_proc_kind tells implementation code what kind of process is active: method, thread, cthread, or no process. This matters for APIs such as wait, dynamic sensitivity, and originator-like behavior where the library needs to know who is calling.

sc_elab_and_sim, sc_end_of_simulation_invoked, sc_delta_count_at_current_time, and related status helpers are guardrails. They let the implementation reject operations at the wrong time and let tooling ask whether the kernel is elaborating, simulating, ending, or already stopped.

sc_get_stop_mode, sc_pending_activity, sc_pending_activity_at_current_time, sc_pending_activity_at_future_time, sc_get_time_resolution, sc_max_time, sc_get_top_level_events, and sc_objects are introspection and simulation-state helpers. They are most useful in tools, diagnostics, and tests that need to ask the kernel what remains scheduled.

sc_interrupt_here, sc_is_unwinding, sc_join, sc_cthread_handle, sc_cor_std_thread, sc_cor_pthread, and sc_cor_pkg_std_thread live near process control and coroutine/thread implementation. Model authors normally do not use these names directly, but they explain why wait can suspend a SystemC thread without returning to your own C++ loop.

The stop/suspend vocabulary includes sc_set_stop_mode, sc_stop_mode, sc_stop_here, sc_status, sc_starvation_policy, sc_time_to_pending_activity, sc_suspend_all, sc_unsuspend_all, sc_suspendable, and sc_unsuspendable. Read these as kernel-control and scheduler-state concepts. They are useful in simulation control and diagnostics, but most models should still express behavior through events, waits, and clear termination policy.

Events and Sensitivity Helpers

sc_event_finder, sc_event_finder_t, sc_event_and_expr, and sc_event_or_expr are the C++ machinery behind nice sensitivity syntax. When you write sensitive << clk.pos(), the implementation cannot store a magic expression; it stores objects that can later locate the event associated with the interface.

sc_sensitive, sc_sensitive_pos, and sc_sensitive_neg are builder-style helpers for static sensitivity. They exist because the SC_METHOD and SC_THREAD registration APIs need a readable way to attach events after the process object exists.

sc_event_queue is different from a plain event. It queues notifications for future times, which makes it useful for delayed callbacks and timeout-like behavior. If your model only needs immediate or delta notification, a plain sc_event is simpler.

Ports, Exports, and Binding Internals

sc_port, sc_in, sc_inout, sc_out, sc_export, sc_export_base, and sc_bind_proxy form the binding surface. The user-level story is simple: ports call interfaces, exports publish interfaces, and channels implement interfaces. The source-level story is that elaboration builds and checks those links before simulation starts.

sc_port_registry, sc_export_registry, sc_module_registry, sc_reset_finder, sc_port_policy, sc_hierarchical_name_exists, sc_register_hierarchical_name, sc_unregister_hierarchical_name, sc_context_begin, sc_context, sc_name_gen, and sc_descendant_inclusion_info are part of the registration and hierarchy infrastructure. When you see them in the source, read them as bookkeeping for "what has been built, where does it live, and which rules apply to this connection?"

sc_signal_write_if, sc_signal_channel, sc_semaphore_if, sc_unbound, sc_unnamed, sc_stub, sc_tie, sc_switch, sc_bind_ef, sc_bind_elem, and sc_event_expr describe communication edges, fallback binding states, event expressions, and interface contracts. They are the kind of names you inspect when a binding or sensitivity problem happens before time zero.

sc_fifo_blocking_in_if, sc_fifo_blocking_out_if, and sc_fifo_out_if are examples of narrow interface contracts. They let a channel expose exactly the operations a client should see, instead of exposing a concrete FIFO object.

sc_in_resolved, sc_in_rv, sc_inout_resolved, sc_inout_rv, sc_out_resolved, and sc_out_rv are resolved-signal port variants. Reach for them only when the model really has multi-driver semantics. For most platform models, a single-writer signal or an explicit channel is easier to review.

Bit and Logic Vector Proxies

The datatype implementation uses proxy objects heavily. Names such as sc_proxy, sc_bitref, sc_bitref_r, sc_concref, sc_concref_r, sc_concatref, sc_value_base, sc_int_bitref, sc_int_bitref_r, sc_uint_bitref_r, sc_signed_bitref_r, sc_signed_subref, sc_signed_subref_r, sc_unsigned_subref, and sc_unsigned_subref_r are how the library makes expressions like bit selects, ranges, and concatenations feel natural in C++.

Additional source names such as sc_int_base, sc_int_subref, sc_int_subref_r, sc_uint_subref_r, sc_unsigned_proxy, sc_signed_proxy, sc_unsigned_bitref, sc_cref, sc_generic_base, sc_abs, sc_min, sc_max, sc_enc, and sc_behavior show up around numeric expression support and generic helper layers. Treat them as datatype implementation vocabulary unless the LRM exposes the behavior directly.

The practical lesson is this: bit-accurate datatypes are powerful, but expressions may create temporary proxy objects. In hot platform paths, prefer plain C++ integers unless bit width, four-state logic, signedness, or synthesis intent really matters.

Fixed-Point and Numeric Policy Symbols

sc_fixed, sc_ufixed, sc_fix, sc_ufix, sc_fix_fast, sc_ufix_fast, sc_fxnum, sc_fxnum_fast_observer, sc_fxnum_bitref, sc_fxnum_fast_bitref, sc_fxcast_switch, sc_fmt, sc_numrep, sc_length_param, and sc_big_op_info sit in the fixed-point and numeric policy area.

sc_fxcast_context, sc_fxtype_context, sc_length_context, sc_fxnum_bitref_r, sc_fxnum_fast_bitref_r, sc_fxnum_subref_r, sc_fxnum_fast_subref, sc_fxnum_fast_subref_r, sc_fxval_observer, and sc_fxval_fast_observer are context/proxy/observer names behind fixed-point expression evaluation. They are useful when diagnosing why a fixed-point expression quantized, rounded, or overflowed differently than expected.

The LRM gives the portable behavior. The source shows the cost: quantization, overflow, casting, and range operations are library work, not free machine instructions. Use them when the numeric contract is part of the hardware model. Avoid them when a fast architectural model only needs approximate integer or floating-point behavior.

Reports and Assertions

sc_assertion_failed, sc_report, and the report-handler family are the difference between a model that fails clearly and one that fails as a C++ mystery. Prefer SC_REPORT_ERROR, SC_REPORT_WARNING, and SC_REPORT_INFO over scattered std::cout once the message is part of model behavior.

Implementation names such as sc_msg_def, sc_stage_callback_registry, sc_stage_callback_if, sc_register_stage_callback, sc_unregister_stage_callback, sc_phash_base, sc_phash_elem, sc_phash_base_iter, sc_plist_base, sc_plist_base_iter, sc_plist_elem, sc_pvector, sc_vpool, sc_mempool, and sc_cmnhdr are utility infrastructure. They are not modeling APIs, but they show how the reference implementation organizes messages, callbacks, pools, lists, and hash tables.

sc_argc, sc_argv, and sc_exception are the bridge back to ordinary C++ process startup and exception flow. They matter for integration code and test harnesses more than for day-to-day model structure.

Other low-level source names that help you navigate the implementation are sc_entry_func, sc_global, sc_carry, sc_utils_ids, sc_kernel_ids, sc_communication_ids, sc_int_ids, sc_nbdefs, sc_time_tuple, sc_digits, sc_proxy_traits, sc_simcontext_int, sc_curr_proc_handle, sc_cor_fn, sc_cor_fiber, sc_cor_pkg_fiber, sc_cor_pkg_pthread, sc_cor_pkg_qt, sc_scoped_lock, sc_ref, sc_vector_assembly, sc_vector_init_policy, and sc_write_comment. They are implementation and support vocabulary, not the public modeling surface.

Review Pattern

When reviewing unfamiliar SystemC source, ask four questions:

• Is this symbol public API, LRM-defined behavior, or implementation support?
• Does it participate in elaboration, simulation scheduling, communication, datatype expression building, tracing, or reporting?
• Does the model rely on a portable contract or an implementation detail?
• Would a simpler C++ type or explicit channel make the behavior easier to maintain?