Using existing unit test frameworks with SystemC

Question

I am working on a project in SystemC and want to incorporate unit testing. Is it possible to use existing unit test frameworks with SystemC?

I ask this because it seems like the SystemC modules only get executed with the simulation kernel, and I want to use unit tests on the modules themselves.

Answer 1

You must create all necessary SystemC signals, SystemC modules and make connection between them before you run any test in GTest. This requires to create own gtest_main.cc implementation. Naturally in SystemC you must put everything in sc_main function.

For this, I would use registry design pattern.

First create registry class (registry + factory + singleton). This class will be responsible for storing registered constructors using dynamic allocation with new and smart pointer in lambda expression (see factory::add class). Create all objects using factory::create() method before running all tests. Then you can get object using factory::get()method in you test execution.

factory.hpp

#ifndef FACTORY_HPP
#define FACTORY_HPP

#include <map>
#include <string>
#include <memory>
#include <functional>

class factory {
public:
    static factory& get_instance();

    template<typename T, typename ...Args>
    class add {
    public:
        add(Args&&... args);

        add(const std::string& name, Args&&... args);
    };

    template<typename T>
    static T* get(const std::string& name = "");

    void create();

    void destroy();
private:
    using destructor = std::function<void(void*)>;
    using object = std::unique_ptr<void, destructor>;
    using constructor = std::function<object(void)>;

    factory();

    factory(const factory& other) = delete;

    factory& operator=(const factory& other) = delete;

    void add_object(const std::string& name, constructor create);

    void* get_object(const std::string& name);

    std::map<std::string, constructor> m_constructors;
    std::map<std::string, object> m_objects;
};

template<typename T, typename ...Args>
factory::add<T, Args...>::add(Args&&... args) {
    add("", args...);
}

template<typename T, typename ...Args>
factory::add<T, Args...>::add(const std::string& name, Args&&... args) {
    factory::get_instance().add_object(name,
        [args...] () -> object {
            return object{
                new T(std::forward<Args>(args)...),
                [] (void* obj) {
                    delete static_cast<T*>(obj);
                }
            };
        }
    );
}

template<typename T> auto
factory::get(const std::string& name) -> T* {
    return static_cast<T*>(factory::get_instance().get_object(name));
}

#endif /* FACTORY_HPP */

factory.cpp

#include "factory.hpp"

#include <stdexcept>

auto factory::get_instance() -> factory& {
    static factory instance{};
    return instance;
}

factory::factory() :
    m_constructors{},
    m_objects{}
{ }

void factory::create() {
    for (const auto& item : m_constructors) {
        m_objects[item.first] = item.second();
    }
}

void factory::destroy() {
    m_objects.clear();
}

void factory::add_object(const std::string& name, constructor create) {
    auto it = m_constructors.find(name);

    if (it == m_constructors.cend()) {
        m_constructors[name] = create;
    }
    else {
        throw std::runtime_error("factory::add(): "
                + name + " object already exist in factory");
    }
}

auto factory::get_object(const std::string& name) -> void* {
    auto it = m_objects.find(name);

    if (it == m_objects.cend()) {
        throw std::runtime_error("factory::get(): "
                + name + " object doesn't exist in factory");
    }

    return it->second.get();
}

Create your own version of gtest_main.cc implementation. Call factory::create() method to create all SystemC signals and SystemC modules before running any tests RUN_ALL_TESTS(). Because factory class is a singleton design pattern, call factory::destroy() method after finishing all tests to destroy all created SystemC objects.

main.cpp

#include "factory.hpp"

#include <systemc>
#include <gtest/gtest.h>

int sc_main(int argc, char* argv[]) {

    factory::get_instance().create();

    testing::InitGoogleTest(&argc, argv);
    int status = RUN_ALL_TESTS();

    factory::get_instance().destroy();

    return status;
}

Then define dut class in your test than will create SystemC signals and SystemC modules. In constructor do connection between created SystemC signals and modules. Register defined dut class to registry object using global constructor like this factory::add g. After than you can get your dut object using simple factory::get() method.

test.cpp

#include "my_module.h"
#include "factory.hpp"

#include <gtest/gtest.h>
#include <systemc>

class dut {
public:
    sc_core::sc_clock aclk{"aclk"};
    sc_core::sc_signal<bool> areset_n{"areset_n"};
    sc_core::sc_signal<bool> in{"in"};
    sc_core::sc_signal<bool> out{"out"};

    dut() {
        m_dut.aclk(aclk);
        m_dut.areset_n(areset_n);
        m_dut.in(in);
        m_dut.out(out);
    }
private:
    my_module m_dut{"my_module"};
};

static factory::add<dut> g;

TEST(my_module, simple) {
    auto test = factory::get<dut>();

    test->areset_n = 0;
    test->in = 0;
    sc_start(3, SC_NS);

    test->areset_n = 1;
    test->in = 1;
    sc_start(3, SC_NS);

    EXPECT_TRUE(test->out.read());
}

my_module.h

#ifndef MY_MODULE_H
#define MY_MODULE_H

#include <systemc>

struct my_module : public sc_core::sc_module {
    my_module(const sc_core::sc_module_name& name): sc_core::sc_module(name) {
        SC_HAS_PROCESS(my_module);
        SC_METHOD(flip_flop_impl);
        sensitive << aclk.pos();
                  << areset_n.neg();
        dont_initialize();
    }

    void flip_flop_impl() {
        if(areset_n.read()) {
            out.write(in.read());
        } else {
            out.write(false);
        }
    }

    sc_core::sc_in<bool> aclk{"aclk"};
    sc_core::sc_in<bool> areset_n{"areset_n"};
    sc_core::sc_in<bool> in{"in"};
    sc_core::sc_out<bool> out{"out"};
}; //< my_module

#endif /* MY_MODULE_H */

CMakeLists.txt

cmake_minimum_required(VERSION 3.5)

project(factory_gtest)

find_package(SystemCLanguage CONFIG REQUIRED)
set(CMAKE_CXX_STANDARD ${SystemC_CXX_STANDARD})
find_package(GTest REQUIRED)

enable_testing()

add_executable(${PROJECT_NAME} main.cpp factory.cpp test.cpp)
target_link_libraries(${PROJECT_NAME} ${GTEST_LIBRARIES} SystemC::systemc)
target_include_directories(${PROJECT_NAME} PRIVATE ${GTEST_INCLUDE_DIRS})

add_test(SystemCGTestExample ${PROJECT_NAME})

For more inspiration, you can check my logic library for SystemC verification: https://github.com/tymonx/logic

Answer 2

Very often SystemC Device-under-test (DUT) can be resetted to initial state by asserting some signal. You can utilize this fact and enable any C++ unit testing framework you want. Just reset you DUT before running each test, so you don't need to elaborate it twice.

Here is an example with Google Test, and a simple "Accumulator" DUT

1. Initialize GTest (::testing::InitGoogleTest(&argc, argv);) from sc_main
2. Elaborate your model
3. Run tests from some thread inside sc_module by calling RUN_ALL_TESTS()
4. You will need somehow to pass pointer to SystemC DUT interface to your tests. I've used global variable for that purpose

Source:

#include <systemc.h>
#include "gtest/gtest.h"

struct test_driver;

test_driver *test_driver_p = nullptr;

void register_test_driver(test_driver *td) {
    test_driver_p = td;
}

test_driver* get_test_driver() {
    assert(test_driver_p);
    return test_driver_p;
}


SC_MODULE(dut_accum) {
    sc_in_clk   clk{"clk"};
    sc_in<bool> reset{"reset"};

    sc_in<bool> en{"en"};
    sc_in<int>  din{"din"};
    sc_out<int> dout{"dout"};

    SC_CTOR(dut_accum) {
        SC_METHOD(accum_method);
        sensitive << clk.pos();
    };

    void accum_method() {
        if (reset)
            dout = 0;
        else if (en)
            dout = dout + din;
    }
};

SC_MODULE(test_driver) {

    sc_signal<bool> reset{"reset",1};
    sc_signal<bool> en{"en",0};
    sc_signal<int> din{"din",0};
    sc_signal<int> dout{"dout"};

    SC_CTOR(test_driver) {
        dut_inst.clk(clk);
        dut_inst.reset(reset);
        dut_inst.en(en);
        dut_inst.din(din);
        dut_inst.dout(dout);
        SC_THREAD(test_thread);
        sensitive << clk.posedge_event();
        register_test_driver(this);
    }

private:
    void test_thread() {
        if (RUN_ALL_TESTS())
            SC_REPORT_ERROR("Gtest", "Some test FAILED");
        sc_stop();
    }

    dut_accum dut_inst{"dut_inst"};
    sc_clock clk{"clk", 10, SC_NS};
};



namespace {
    // The fixture for testing dut_accum
    class accum_test: public ::testing::Test {
    protected:

        test_driver & td;

        accum_test(): td(*get_test_driver()){
            reset_dut();
        }

        virtual ~accum_test() {}

        void reset_dut(){
            td.reset = 1;
            wait();
            td.reset = 0;
        }
    };

    TEST_F(accum_test, test0) {
        td.din = 10;
        td.en = 1;
        wait();
        wait();
        EXPECT_EQ(td.dout.read(), 10);
    }

    TEST_F(accum_test, test1_no_en) {
        td.din = 10;
        td.en = 0;
        wait();
        wait();
        EXPECT_EQ(td.dout.read(), 10); // this test will fail, since en is 0
    }

    TEST_F(accum_test, test2_reset_asserted) {
        td.din = 10;
        td.en = 1;
        td.reset = 1;
        wait();
        wait();
        EXPECT_EQ(td.dout.read(), 0);
    }
}

int sc_main(int argc, char **argv) {
    ::testing::InitGoogleTest(&argc, argv);
    test_driver td{"td"};
    sc_start();
}

CMakeLists.txt (requires installed SystemC 2.3.2 )

cmake_minimum_required(VERSION 3.8)
project(systemc_gtest)

find_package(SystemCLanguage CONFIG REQUIRED)

set (CMAKE_CXX_STANDARD ${SystemC_CXX_STANDARD})

find_package(GTest REQUIRED)

enable_testing()

add_executable(systemc_gtest main.cpp)
target_link_libraries(systemc_gtest ${GTEST_LIBRARIES} SystemC::systemc )
target_include_directories(systemc_gtest PRIVATE ${GTEST_INCLUDE_DIRS})
add_test(AllTestsInSystemCGtest systemc_gtest)

Answer 3

I have a second solution to this question that uses CMkae and CTest (http://cmake.org/). The setup I used creates a binary for each test. Here's the CMakeLists.txt file I used:

project(sc_unit_test)
include_directories(/home/stephan/local/include)
find_library(systemc systemc /home/stephan/local/lib-linux64)
link_directories(/home/stephan/local/lib-linux64)

add_executable(test_1 test_1.cxx)
target_link_libraries(test_1 systemc)

add_executable(test_2 test_2.cxx)
target_link_libraries(test_2 systemc)

enable_testing()
add_test(test_1 test_1)
add_test(test_2 test_2)

Each test_*.cxx file has a sc_main method that executes the test and the return value indicates whether or not the test passed or failed. To run the tests simply do:

$ cmake .
$ make
$ ctest
Test project
  1/  2 Testing test_1                           Passed
  2/  2 Testing test_2                           Passed

100% tests passed, 0 tests failed out of 2

If you don't want to run the simulator, you can simply skip the call to sc_start and exit the application after doing whatever specific testing you want on a particular module.