Identifying SystemC constructs

SystemC Module Declarations

There are two ways in which a SystemC module can be declared: (1) using the SC_MODULE() macro or (2) inheriting from the sc_module class. Both of these approaches are recognized by systemc-clang.

#include <systemc.h>
SC_MODULE(counter) {
// Some other code here.

};

#include <systemc.h>
class counter: public sc_module {
// Some other code here.

};

SystemC Constructor

There are two ways in which the constructor can be used: (1) using the SC_CTOR() macro or (2) using the class constructor. Both of approaches are recognized by systemc-clang.

#include <systemc.h>
SC_MODULE(counter) {
  sc_uint<32> keep_count;
  SC_CTOR(counter): keep_count{0} {
  // Some other code here.
  }
};

#include <systemc.h>
class counter: public sc_module {
  sc_uint<32> keep_count;
  counter(): keep_count{0}  {
  // Some other code here.
  }
};

SystemC Processes and Sensitivity Lists

There are two process types that systemc-clang recognizes: (1) SC_METHOD() and (2) SC_THREAD(). The only synthesizable process type is SC_METHOD(). systemc-clang gives access to the function provided as the argument to the process macro. Plugins can then use tihs to perform other operations on the implementation of the process’ function such as generating Verilog or an intermediate representation.

#include <systemc.h>
SC_MODULE(counter) {
  sc_in_clk clk;
  sc_uint<32> keep_count;

  SC_CTOR(counter): keep_count{0} {
    SC_METHOD(count_up);
    sensitive << clk.pos();
  }

  void count_up() {
  // Some code here.
  }

};

#include <systemc.h>
class counter: public sc_module {
  sc_in_clk clk;
  sc_uint<32> keep_count;

  SC_HAS_PROCESS(counter);
  counter(): keep_count{0}  {
    SC_METHOD(count_up);
    sensitive << clk.pos();
  }

  void count_up() {
  // Some code here.
  }
};

SystemC Ports and Member Variables

SystemC ports and member fields can be a part of the module. In the counter example, there is a clk port of type sc_in_clk and there is a member variable called keep_count of type sc_uint<32>. Note that the latter is a templated type. We extend this example further.

Note that a member variable can also be an sc_signal<>, which we show in the next subsection.

#include <systemc.h>
SC_MODULE(counter) {
  // clock
  sc_in_clk clk;

  // output port
  sc_out<sc_uint<32>> count_out;

  // member variable
  sc_uint<32> keep_count;

  SC_CTOR(counter) {
    SC_METHOD(count_up);
    sensitive << clk.pos();
  }

  void count_up() {
    keep_count = keep_count + 1;
    count_out.write( keep_count );
  }

};

Nested Module Declarations & Port Binding

It is common to use a hierarchy of modules to describe a design. systemc-clang identifies this hierarchy. For the example below, the nested module of type counter will be identified as being nested within the SystemC module of type DUT. Within the constructor of the DUT module, we are instantiating the count member variable with a given name, and then binding the ports to the appropriate signals.

This example also shows the use of a sc_signal<>.

#include <systemc.h>
// Code from before
SC_MODULE(counter) {
};

// Top level module.
SC_MODULE(DUT) {
  counter count;
  sc_clk clock;
  sc_signal< sc_uint<32> > counter_out;

  SC_CTOR(DUT): count{"counter_instance"} {
    // port bindings
    count.clk(clock);
    count.count_out(counter_out);
  };
};

int sc_main() {
  DUT dut{"design_under_test"};
};

Templated Modules

The SystemC module declaration can be templated as well. We can extend our counter module to have it access a template argument.

#include <systemc.h>
template <typename T>
SC_MODULE(counter) {
  // clock
  sc_in_clk clk;

  // output port
  sc_out<T> count_out;

  // member variable
  T keep_count;

  SC_CTOR(counter) {
    SC_METHOD(count_up);
    sensitive << clk.pos();
  }

  void count_up() {
    // Ensure that type T supports +
    keep_count = keep_count + 1;
    count_out.write( keep_count );
  }

};

User-defined Templated Datatypes

Note

Todo

User-defined Channels

Note

Todo

Typedefs and using

Typedefs and the use of type alias via using are parsed by systemc-clang. The parsing drills down to the most basic type, and desugars any sugared type. This means that any intermediate type (via indirection) is not captured, but only the final desugared type.

systemc-clang uses Catch2 to implement tests. There are several examples under tests/ that can be viewed. This part of the documentation will go through creating a simple test, and integrating it into the build system.

In order to run systemc-clang from within a C++ program, and integrate it successfully into the build environment, we describe a few boilerplate items that are essential.

The boilerplate allows one to integrate tests into the build environment for systemc-clang.

We describe the #include files that are necessary. We must include the main header file from where we can invoke the SystemCConsumer called SystemCClang.h. We also include the catch.hpp, which is necessary to use the features of Catch2. Finally, there is an include file that is automatically generated called ClangArgs.h. This is necessary to pass the arguments provided to the build environment to the test.

#include "SystemCClang.h"
#include "catch.hpp"

// This is automatically generated from cmake.
#include "ClangArgs.h"

systemc-clang is wrapped in a namespace called scpar. Hence, we add the namespace.

using namespace scpar;

The next step is in providing the SystemC source that we wish to parse. This can come from a file or embedded within the test program as a string. Note that this uses the R" approach to defining a std::string.

 std::string code = R"(
 #include <systemc.h>
 SC_MODULE(counter) {
   // clock
   sc_in_clk clk;

   // output port
   sc_out<sc_uint<32>> count_out;

   // member variable
   sc_uint<32> keep_count;

   SC_CTOR(counter) {
     SC_METHOD(count_up);
     sensitive << clk.pos();
   }

   void count_up() {
     keep_count = keep_count + 1;
     count_out.write( keep_count );
   }

 };

 // Top level module.
 SC_MODULE(DUT) {
   counter count;
   sc_clock clock;
   sc_signal< sc_uint<32> > counter_out;

   SC_CTOR(DUT): count{"counter_instance"} {
     // port bindings
     count.clk(clock);
     count.count_out(counter_out);
   };
 };

 int sc_main() {
   DUT dut{"design_under_test"};
   return 0;
 };
)";

We can start creating our test using Catch2’s TEST_CASE(). Please refer to the Catch2 documentation the usage of the specific Catch2 macros. They key systemc-clang aspect we point out is that the tests create the AST from within the C++ program using ASTUnit as shown below. The arguments to buildASTFromCodeWithArgs() include the string created earlier, and the arguments to successfully create the AST. For example, the location of the SystemC header files. These are captured in systemc_clang::catch_test_args as a part of the ClangArgs.h.

TEST_CASE("Basic parsing checks", "[parsing]") {
  ASTUnit *from_ast =
    tooling::buildASTFromCodeWithArgs(code, systemc_clang::catch_test_args)
      .release();
          // Some more code here
}

If the SystemC model has compile errors, then they will be shown on the standard output. Otherwise, from_ast will point to the AST of the SystemC model.

Now that we have access to the AST, we can run systemc-clang. Inline comments describe each of the lines.

// Instantiate consumer.
SystemCConsumer consumer{from_ast};

// Run systemc-clang.
consumer.HandleTranslationUnit(from_ast->getASTContext());

// Get access to the internal model.
Model *model{consumer.getSystemCModel()};

// Get instance with name "counter_instance".
ModuleDecl *test_module{model->getInstance("counter_instance")};

The key observation is that model provides access to the parsed information. This includes all the modules that were instantiated, the ports and signals within it, any nested sub-modules, etc.

The test can use REQIRE() macro from Catch2 to assert for the information found about the model. The following assertion ensures that we are able to find an instance of a SystemC module that has the name counter_instance.

  REQUIRE(test_module != nullptr);

We can also check for the number of input ports found by systemc-clang, and likewise, the number of output ports.

  auto input_ports{test_module->getIPorts()};
  REQUIRE(input_ports.size() == 1);

Similarly, using other member functions of the systemc-clang’s Model class, one can access other components of a module instance.

  auto output_ports{test_module->getOPorts()};
  REQUIRE(output_ports.size() == 1);

Writing matchers with clang-query

clang-query is a clang tool that allows one to write AST matchers and test them. Using clang-query to write matchers to identify SystemC constructs is quite beneficial.

Warning

There are some differences in what clang-query accepts, and what the clang tool actually accepts. As a result, not all matchers that work in clang-query will compile in the clang tool. Nonetheless, clang-query is an excellent way to start experimenting with writing a matcher.

Pre-requisites

Ensure that the following environment variables have been set. * SYSTEMC

An example: Matching SystemC module declarations

The best way to illustrate the use of clang-query is with examples. Suppose we have the following SystemC module declaration.

#include <systemc.h>

SC_MODULE(counter) {
  // clock
  sc_in_clk clk;

  // output port
  sc_out<sc_uint<32>> count_out;

  // member variable
  sc_uint<32> keep_count;

  SC_CTOR(counter) {
    SC_METHOD(count_up);
    sensitive << clk.pos();
  }

  void count_up() {
    keep_count = keep_count + 1;
    count_out.write( keep_count );
  }

};

// Top level module.
SC_MODULE(DUT) {
  counter count;
  sc_clock clock;
  sc_signal< sc_uint<32> > counter_out;

  SC_CTOR(DUT): count{"counter_instance"} {
    // port bindings
    count.clk(clock);
    count.count_out(counter_out);
  };
};

int sc_main() {
  DUT dut{"design_under_test"};
  return 0;
};

Without a doubt, anyone who wishes to write an AST matcher must review the list of matchers that are available here: AST Matchers Reference.

To run this example, we can execute it in the following way (assuming we are in the root of the systemc-clang directory).

$ clang-query -extra-arg=-I$SYSTEMC/include docs/source/matcher/counter.cpp

The -extra-arg option in clang-query specified the path for SystemC includes. You will come to a clang-query prompt. This is where we can write our matcher.

Let us start by identifying the declarations of the SystemC modules in the model. These would be the counter and DUT modules. In order to do this, we need to understand that the SC_MODULE() macro essentially declares a class that is derived from the sc_module class. As a starter, we could write the following matcher.

match cxxRecordDecl()

Note that the command match tells that the string following it is the matcher to execute. When you run the above command, you will notice that this produces quite a few matches (around nine thousand of them). This is because the matcher is identifying all C++ declarations in the AST, which includes the SystemC library.

If we want to limit ourselves to only matching the file provided, then we can use the isExpansionInMainFile(). Please refer to the AST matcher reference to learn more about it.

match cxxRecordDecl(isExpansionInMainFile())

This matcher will produce four matches of the two SystemC modules in the model.

Match #1:

/home/twiga/code/github/systemc-clang/docs/source/developer/matchers/counter.cpp:3:1: note: "root" binds here
SC_MODULE(counter) {
^~~~~~~~~~~~~~~~~~~~
/home/twiga/code/systemc-2.3.3/systemc/include/sysc/kernel/sc_module.h:397:5: note: expanded from macro 'SC_MODULE'
    struct user_module_name : ::sc_core::sc_module
    ^

Match #2:

/home/twiga/code/github/systemc-clang/docs/source/developer/matchers/counter.cpp:3:1: note: "root" binds here
SC_MODULE(counter) {
^~~~~~~~~~~~~~~~~~
/home/twiga/code/systemc-2.3.3/systemc/include/sysc/kernel/sc_module.h:397:5: note: expanded from macro 'SC_MODULE'
    struct user_module_name : ::sc_core::sc_module
    ^~~~~~~~~~~~~~~~~~~~~~~

Match #3:

/home/twiga/code/github/systemc-clang/docs/source/developer/matchers/counter.cpp:26:1: note: "root" binds here
SC_MODULE(DUT) {
^~~~~~~~~~~~~~~~
/home/twiga/code/systemc-2.3.3/systemc/include/sysc/kernel/sc_module.h:397:5: note: expanded from macro 'SC_MODULE'
    struct user_module_name : ::sc_core::sc_module
    ^

Match #4:

/home/twiga/code/github/systemc-clang/docs/source/developer/matchers/counter.cpp:26:1: note: "root" binds here
SC_MODULE(DUT) {
^~~~~~~~~~~~~~
/home/twiga/code/systemc-2.3.3/systemc/include/sysc/kernel/sc_module.h:397:5: note: expanded from macro 'SC_MODULE'
    struct user_module_name : ::sc_core::sc_module
    ^~~~~~~~~~~~~~~~~~~~~~~
4 matches.

You will quickly note that clang-query doesn’t really provide a nice interface to go back to the previous command and edit it. Consequently, it is better to use a file to provide as an input to it with the matcher we wish to write.

Suppose that we create a separate file called control.dbg, which contains our matcher. We can then execute the script in the following way.

$ clang-query -extra-arg=-I$SYSTEMC/include docs/source/matcher/counter.cpp -f control.dbg

You will notice that we have multiple matches (more then 2), and we should only be having two matches for the two SystemC modules. To correct this, we have to make two changes: * First is to inform clang-query that we should only receive matches on nodes that we have bound a string to, and disable outputting any other matches that are not specific to the strings the matcher binds. We would do this by using set bind-root false. * Second, we have to remove implicit nodes that are created in the clang AST.

If we want to write a matcher that refers to the identified AST nodes, we have to bind the nodes to a string that we can then use to extract them. We can update our matcher to add a binding string.

match cxxRecordDecl(unless(isImplicit()), isExpansionInMainFile()).bind("modules")

Note

You may have noticed that we are finding the SystemC module declarations twice. The reason for this is that clang creates an implicit referenced node for each of the classes. To remove this from our matches, we need to include the unless(isImplicit()) predicate to the matcher.

This will produce two matches, which correctly identify the counter and DUT SystemC modules. If you wish to display the AST nodes for these matches, then you can add a command to control the output. This would be done with set output dump:

set bind-root false
set output dump
match cxxRecordDecl(unless(isImplicit()), isExpansionInMainFile()).bind("modules")

The output has not been shown, but hopefully you were able to see the AST dump.

Something that you may quickly notice that the matcher written would also identify classes that are not SystemC modules. In order to enforce that, we need to state that the class must be derived from the sc_module class. We would update our matcher in the following way.

set bind-root false
set output dump
match cxxRecordDecl(isDerivedFrom("::sc_core::sc_module"), unless(isImplicit()), isExpansionInMainFile()).bind("modules")

If you were to go and add non-SystemC classes to the original model, you will see that those will not be matched.