CCI Presets, Configuration Files, and Unconsumed Values

How to Read This Lesson

CCI becomes valuable when configuration comes from outside the model: command lines, JSON files, scripts, GUIs, or regression systems. This lesson is about making that flow reliable enough for real virtual platforms.

Source and LRM Trail

Use Docs/LRMs/SystemC_CCI_1_0_LRM.pdf for parameter initialization, brokers, handles, values, and originators. In source, inspect .codex-src/cci/configuration/src/cci, especially broker interfaces and the consuming broker implementation.

The Preset Value Idea

A preset value is configuration that arrives before the target parameter exists.

That matters because C++ elaboration order is hierarchical. A top-level script may know:

top.cpu.frequency_hz = 500000000

before the cpu module has constructed its cci_param<unsigned long long> frequency_hz.

The broker stores the preset. When the parameter is created, it asks the broker whether a preset exists for its name. If yes, the parameter starts with that value instead of its constructor default.

The Typo Problem

What if the file says:

top.cup.frequency_hz = 500000000

The broker can store that preset, but no parameter ever consumes it. Without validation, your simulation may run with the default CPU frequency and nobody notices until performance numbers look wrong.

That is why unconsumed preset checks are not optional in serious platforms.

Configuration Validation Pattern

At the end of elaboration or start of simulation, ask the broker for unconsumed presets and report them:

void end_of_elaboration() override {
  auto broker = cci::cci_get_global_broker(
      cci::cci_originator{name()});
 
  auto unused = broker.get_unconsumed_preset_values();
  for (const auto& item : unused) {
    std::ostringstream os;
    os << "unused CCI preset: " << item.first;
    SC_REPORT_WARNING("CCI_CONFIG", os.str().c_str());
  }
}

Your project may choose to make this fatal. For production regressions, fatal is usually better: a typo in configuration is not a harmless warning.

How the Source Makes This Work

Broker implementations keep two categories of information:

• live parameter interfaces registered by constructed parameters
• preset values waiting to be consumed

When a parameter appears, the broker can move a matching preset from the unused category into the parameter's initial value path. The source implementation makes the lifecycle concrete: configuration is not a global variable lookup; it is a broker-mediated registration and consumption protocol.

Review Checklist

• Are all external knobs represented as CCI parameters?
• Are preset files validated for unconsumed values?
• Are bad presets warnings or fatal errors by project policy?
• Are originators used so tools and logs show who changed a value?
• Do parameter descriptions include units, legal ranges, and default intent?