This blog is about the MINRES SystemC-Components library, or how it is usually referred to, the SCC. The SCC is a CPP productivity library for SystemC and TLM 2.0 based modeling. What this means is that the SCC combines ready-to-use modules for many of the most common problems people are facing in SystemC projects. This includes basics such as configurable logging and simulation tracing but also more advanced features such as pin-level adapters for many bus protocols.
In this post I’ll showcase two parts that I especially like, and which I believe are particularly useful in virtually every SystemC project.
We start with a very minimal plain SystemC model of a simple memory target. You can find everything you need to follow along in this article, however, we will be publishing a ready-to-run repository in due course and will update this blog when it’s live.
The target has 256 bytes of addressable memory that can be accessed via SystemC’s b_transport function and plain old tlm_generic_payloads. We will extend this model with two SCC features: SCC logging and the SCC configurer.
#include <cstring>
#include <cstdint>
#include <tlm_utils/simple_target_socket.h>
#include <tlm_utils/simple_initiator_socket.h>
#include <iostream>
using namespace sc_core;
class Initiator : public sc_module {
public:
tlm_utils::simple_initiator_socket<Initiator> socket;
Initiator(sc_module_name name): sc_module(name), socket("socket") {
SC_THREAD(run);
}
private:
void send_trans(tlm::tlm_command cmd, uint64_t addr, unsigned char* data) {
tlm::tlm_generic_payload trans;
sc_time delay = sc_time(0, SC_NS);
trans.set_command(cmd);
trans.set_address(addr);
trans.set_data_ptr(data);
trans.set_data_length(1);
socket->b_transport(trans, delay);
sc_assert(trans.is_response_ok());
wait(delay);
}
void run() {
wait(sc_time(100, SC_NS));
for (int i = 0; i < 4; i++) {
uint64_t addr = static_cast<uint64_t>(i) * 4;
uint8_t data = static_cast<uint8_t>(i);
send_trans(tlm::TLM_WRITE_COMMAND,
addr,
reinterpret_cast<unsigned char*>(&data));
}
for (int i = 0; i < 4; i++) {
uint64_t addr = static_cast<uint64_t>(i) * 4;
uint8_t data = 0;
send_trans(tlm::TLM_READ_COMMAND,
addr,
reinterpret_cast<unsigned char*>(&data));
}
}
};
class Target : public sc_module {
public:
tlm_utils::simple_target_socket<Target> socket;
Target(sc_module_name name)
: sc_module(name), socket("socket") {
socket.register_b_transport(this, &Target::b_transport);
}
private:
unsigned char mem[256]{};
void b_transport(tlm::tlm_generic_payload &trans, sc_time &delay) {
uint64_t addr = trans.get_address() & 0xff;
unsigned char *ptr = trans.get_data_ptr();
unsigned int len = trans.get_data_length();
if (trans.is_write()) {
std::memcpy(&mem[addr], ptr, len);
std::cout << sc_time_stamp() << ": WRITE mem[0x" << std::hex << addr << "]=0x" << static_cast<uint8_t>(*ptr) << std::endl;
} else if (trans.is_read()) {
std::memcpy(ptr, &mem[addr], len);
std::cout << sc_time_stamp() << ": READ mem[0x" << std::hex << addr << "]=0x" << static_cast<uint8_t>(*ptr) << std::endl;
}
delay += sc_time(100, SC_NS);
trans.set_response_status(tlm::TLM_OK_RESPONSE);
}
};
int sc_main(int, char *[]) {
Initiator init("init");
Target tgt("mem");
init.socket.bind(tgt.socket);
sc_start(2000, SC_NS);
return 0;
}
Running this minimal model prints the plain std::cout output:
100 ns: WRITE mem[0x0]=0x00
200 ns: WRITE mem[0x4]=0x01
300 ns: WRITE mem[0x8]=0x02
400 ns: WRITE mem[0xc]=0x03
500 ns: READ mem[0x0]=0x00
600 ns: READ mem[0x4]=0x01
700 ns: READ mem[0x8]=0x02
800 ns: READ mem[0xc]=0x03
In the initial model, logging is done manually via C++’s std::cout streams. While this works, the SCC provides logging functionality that is as easy to use and which provides more features that come in handy during debugging later.
Switching to SCC logging takes three small changes. First, swap the <iostream> include for <scc.h>, the umbrella header that pulls in the logging macros:
-#include <iostream>
+#include <scc.h>
Second, replace the std::cout statements with the corresponding SCC macro, here SCCINFO:
- std::cout << sc_time_stamp() << ": WRITE mem[0x" << std::hex << addr << "]=0x" << static_cast<uint8_t>(*ptr) << std::endl;
+ SCCINFO(name()) << "WRITE mem[0x" << std::hex << addr << "]=0x" << static_cast<uint8_t>(*ptr);
- std::cout << sc_time_stamp() << ": READ mem[0x" << std::hex << addr << "]=0x" << static_cast<uint8_t>(*ptr) << std::endl;
+ SCCINFO(name()) << "READ mem[0x" << std::hex << addr << "]=0x" << static_cast<uint8_t>(*ptr);
The macro streams just like std::cout, and the << chain stays almost the same: only the manual sc_time_stamp() << ": " prefix and the trailing std::endl are dropped, because the logger adds the timestamp and the line break itself.
What does change is the first argument: instead of std::cout you pass the module name (name()), which the logger uses to prefix every line with the hierarchical path of the module that produced it.
In a large design you therefore always know where a message comes from.
The macros route every message through a central logging framework with 8 severity levels, 0 (none) to 7 (trace).
Anything below the configured level is dropped, so verbose debug output can stay in the code without flooding the console, and it can be re-enabled at runtime without recompiling (we’ll see how with the configurer below).
Initializing with logAsync(false) keeps the output synchronous and deterministically ordered, which is much easier to read than interleaved std::cout calls from multiple threads.
For very verbose logs that you only want to see occasionally (e.g. marking the phases in the initiator), use SCCTRACE, the highest level:
SCCTRACE(name()) << "start write transactions";
Finally, the logger has to be initialized once at the top of sc_main, before any module is constructed, so that every module can register with it:
int sc_main(int, char *[]) {
+ scc::init_logging(scc::LogConfig().logLevel(scc::log::DEBUG).logAsync(false));
Initiator init("init");
Target tgt("mem");
Running the model again, now with SCC logging enabled, produces:
[I] [ 100.0 ns] mem : WRITE mem[0x0]=0x
[I] [ 200.0 ns] mem : WRITE mem[0x4]=0x01
[I] [ 300.0 ns] mem : WRITE mem[0x8]=0x02
[I] [ 400.0 ns] mem : WRITE mem[0xc]=0x03
[I] [ 500.0 ns] mem : READ mem[0x0]=0x
[I] [ 600.0 ns] mem : READ mem[0x4]=0x01
[I] [ 700.0 ns] mem : READ mem[0x8]=0x02
[I] [ 800.0 ns] mem : READ mem[0xc]=0x03
Each line now carries a level tag ([I] for INFO), the simulation time, and the hierarchical name of the module that emitted it. The initiator’s SCCTRACE lines are not shown here: the global level is DEBUG, which is below TRACE, so they are filtered out.
The SCC configurer is a wrapper around CCI parameters. It applies cci::cci_param values from a JSON file at runtime, even when the parameter sits deep inside a nested module hierarchy, so we can experiment with the model without recompiling it. In this step we make the response delay of the target memory configurable. First, we declare a CCI parameter in the target, right next to the socket:
class Target : public sc_module {
public:
+ cci::cci_param<unsigned int> txn_delay{"txn_delay", 100};
tlm_utils::simple_target_socket<Target> socket;
The two constructor arguments are the parameter name and its default value. The default is used whenever the JSON config does not override the parameter.
Then we use the parameter in b_transport instead of the hardcoded constant:
- delay += sc_time(100, SC_NS);
+ delay += sc_time(txn_delay, SC_NS);
That is all we need to change inside the target. The remaining step is wiring up the configurer in sc_main:
int sc_main(int, char *[]) {
scc::init_logging(scc::LogConfig().logLevel(scc::log::DEBUG).logAsync(false));
+ scc::configurer cfg("config.json");
Initiator init("init");
Target tgt("mem");
init.socket.bind(tgt.socket);
+ cfg.configure();
+ cfg.dump_configuration("config-dump.json");
One thing to be aware of is the ordering of the new function calls. The configurer must be instantiated before the modules, but cfg.configure()must be called after they are constructed, because only then do all cci_param objects exist and can be found by name. configure() reads config.json and applies each value to the parameter at the matching hierarchical path, so a config like this sets both the delay and the log level of the memory target:
{
"mem": {
"txn_delay": 50,
"log_level": 5
}
}
Calling cfg.dump_configuration("config-dump.json") writes all CCI parameters available in the model to a file. That is the easiest way to discover what can be configured: run the model once, inspect the dump, then put the values you want to change into config.json:
{
"init": {
"log_level": 7
},
"mem": {
"txn_delay": 50,
"log_level": 5
}
}
A nice side effect we get by using SCC logging is that every module automatically got a per-module log_level CCI parameter, as the dump shows. We can use the same config file to fine-tune what we see in the logs, for example keeping init at the verbose level 7 while turning mem down to 5.
We can now run the model again with config.json without having to recompile it.
[T] [ 100.0 ns] init : start write transactions
[I] [ 100.0 ns] mem : WRITE mem[0x0]=0x
[I] [ 150.0 ns] mem : WRITE mem[0x4]=0x01
[I] [ 200.0 ns] mem : WRITE mem[0x8]=0x02
[I] [ 250.0 ns] mem : WRITE mem[0xc]=0x03
[T] [ 300.0 ns] init : start read transactions
[I] [ 300.0 ns] mem : READ mem[0x0]=0x
[I] [ 350.0 ns] mem : READ mem[0x4]=0x01
[I] [ 400.0 ns] mem : READ mem[0x8]=0x02
[I] [ 450.0 ns] mem : READ mem[0xc]=0x03
We can see two changes in the output. First, the transactions now complete 50 ns apart instead of 100 ns, because txn_delay was set to 50, and, secondly, the [T] trace lines from init are visible because its log_level was raised to 7 (trace).
Logging and runtime configuration are for sure two things that every SystemC model needs. By using the SCC you can make use of many battle-tested modules that handle much of the common boilerplate but also many advanced features that are hard to implement and hard to get right.
In addition to the features in this post, there is more in the SCC including waveform and transaction tracing, pin-level adapters for many protocols, and many quality of life modules that make writing SystemC quicker and more pleasant.
Best of all, the SCC is open-source, so go and try it today (and maybe contribute some of your SystemC library back)!
Do you want to use the SCC and need some guidance? Feel free to drop us a message and we can get you started.
We use Matomo to analyze website usage statistics and improve our services. You can decide for yourself whether to consent to this statistical analysis.
For more information, see our Privacy Policy