CCI API, Callback, Value, and Handle Field Guide

How to Read This Lesson

CCI is not just a prettier way to store variables. It is a standard way to make configuration inspectable, typed, tool-visible, and lifecycle-aware. Read each API name by asking what it protects: value ownership, mutation timing, tool access, callback ordering, or error reporting.

Standard and source context

Use Docs/LRMs/SystemC_CCI_1_0_LRM.pdf. Use .codex-src/cci/cci, .codex-src/cci/configuration/src, and .codex-src/cci/inspection/src for implementation reading.

Broker and Naming APIs

cci_broker_if, cci_broker_handle, cci_broker_handles, cci_register_broker, cci_get_broker, cci_gen_unique_name, cci_get_name, cci_unregister_name, and cci_name_gen sit around broker discovery and unique naming.

Some source and generated documentation may contain the misspelled cci_orginator; read it as the originator concept, not as a separate modeling idea.

The broker is the configuration authority. It owns the map from hierarchical names to parameters and preset values. A cci_broker_handle gives client code a safer front door than directly poking the broker implementation.

cci_originator records who is asking. That matters because tools, modules, and processes may not all deserve the same permissions.

Parameter Shape and Mutability

cci_param, cci_param_if, cci_untyped_param, cci_untyped_tag, cci_typed_tag, cci_typed_handle, cci_param_mutable_type, cci_param_data_category, and cci_mutable_param describe parameter typing and mutation policy.

Typed parameters are what model authors normally instantiate. Untyped access is what generic tools need when they enumerate a platform without knowing every C++ template parameter.

cci_param_range, cci_filtered_range, cci_param_predicate, cci_preset_value_range, and cci_preset_value_predicate are iteration and filtering concepts. Use them when tools need to ask, "show me every parameter matching this category or hierarchy."

Presets and Unconsumed Values

Preset APIs let configuration arrive before the owning parameter exists. That is useful for top-level platform configuration, but it creates one classic failure mode: a typo becomes an unconsumed preset.

cci_preset_value_predicate, cci_preset_value_range, get_unconsumed_preset_values, and broker preset maps should be part of every VP bring-up checklist. A configuration file that silently falls back to defaults can waste days.

Callback APIs

cci_callback, cci_callback_typed_handle, cci_callback_traits, cci_callback_untyped_handle, cci_param_callback_if, cci_param_create_callback, cci_param_create_callback_handle, cci_param_destroy_callback, cci_param_destroy_callback_handle, cci_param_pre_read_callback, cci_param_pre_read_callback_typed, cci_param_pre_read_callback_untyped, cci_param_read_event, and value-change callbacks let tools and model owners observe parameter lifecycle and access.

Write-path and post-read variants include cci_param_pre_write_callback, cci_param_pre_write_callback_typed, cci_param_pre_write_callback_untyped, cci_param_post_write_callback, cci_param_post_write_callback_typed, cci_param_post_write_callback_untyped, cci_param_post_read_callback, cci_param_post_read_callback_typed, cci_param_post_read_callback_untyped, cci_param_pre_write_callback_handle, cci_param_post_write_callback_handle, cci_param_pre_read_callback_handle, and cci_param_post_read_callback_handle.

Callbacks are powerful because they turn configuration into an observable protocol. They are dangerous when they hide side effects. Keep callbacks small, documented, and explicit about whether they run during elaboration or simulation.

Value Tree APIs

cci_value, cci_value_ref, cci_value_cref, cci_value_list_ref, cci_value_list_cref, cci_value_map, cci_value_map_ref, cci_value_map_cref, cci_value_map_elem_ref, cci_value_map_elem_cref, cci_value_string_ref, cci_value_string_cref, cci_value_iterator, and cci_name_value_pair form the JSON-like value tree.

This is what lets CCI represent structured configuration instead of only scalar C++ values. In a real platform, that can mean a table of memory regions, a map of feature switches, or a list of debug endpoints.

Error and Report APIs

cci_param_failure, cci_report_handler, cci_abort, and cci_handle_exception belong to the error path. Good CCI code does not just return false and hope somebody reads a log. It reports configuration mistakes early, preferably before simulation results become misleading.

Implementation Names Worth Recognizing

cci_impl, cci_cmnhdr, cci_broker_callback_if, and internal handle classes are implementation scaffolding. You do not model with them directly, but recognizing them makes the source tree easier to navigate.

Other source names worth recognizing are cci_get_cci_unique_names, cci_name_state, cci_value_has_converter, cci_value_unpack_fx, cci_config_macros, cci_msg_type, cci_msg_types, cci_msg_type_prefix, cci_msg_type_prefix_len, cci_meta, cci_core_types, cci_mutable_types, cci_tag, cci_callback_impl, cci_broker_callbacks, cci_broker_types, cci_param_callbacks, cci_value_converter_disabled, cci_inspection, cci_param_cast, cci_true_type, and cci_false_type. Most are implementation support for type traits, message IDs, conversion, inspection, and callback dispatch.

The remaining utility names cci_name_free, cci_name_used, cci_value_delegate_converter, cci_version, cci_macros_undef, cci_param_predicate_handle, cci_preset_value_predicate_handle, cci_iterable, cci_param_write_event_untyped, and cci_param_read_event_untyped fit the same pattern: naming state, converter delegation, version metadata, macro cleanup, iterable ranges, predicate handles, and untyped read/write events.

Senior Review Checklist

• Is every structural parameter locked before simulation?
• Are unconsumed presets checked?
• Can generic tooling inspect values without knowing C++ template types?
• Are callbacks simple enough to reason about?
• Do errors explain the parameter path, originator, and attempted value?