misc: Clean up and complete the gem5<->SystemC-TLM bridge [4/10]

The current TLM bridge only provides a Slave Port that allows the gem5
world to send request to the SystemC world. This patch series refractors
and cleans up the existing code, and adds a Master Port that allows the
SystemC world to send requests to the gem5 world.

This patch:
 * Move common code of the example to a common directory.  Move the cli
 * parsing from the SimControl module to a separate example object.  Add
 * comments describing the Gem5SimControl module.

Testing Done: Examples compile and run.

Reviewed at http://reviews.gem5.org/r/3695/

Signed-off-by: Jason Lowe-Power <jason@lowepower.com>

8 files changed, 357 insertions, 64 deletions

diff --git a/util/tlm/examples/common/cli_parser.cc b/util/tlm/examples/common/cli_parser.cc
new file mode 100644
index 000000000..b86e99fb8
--- /dev/null
+++ b/util/tlm/examples/common/cli_parser.cc
@@ -0,0 +1,126 @@
+/*
+ * Copyright (c) 2016, Dresden University of Technology (TU Dresden)
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * 3. Neither the name of the copyright holder nor the names of its
+ *    contributors may be used to endorse or promote products derived from
+ *    this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER
+ * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * Authors: Christian Menard
+ */
+
+#include <iostream>
+#include <sstream>
+
+#include "cli_parser.hh"
+#include "sim/cxx_manager.hh"
+
+void
+CliParser::usage(const std::string& prog_name)
+{
+    std::cerr
+      << "Usage: " << prog_name
+      << (" <config_file.ini> [ <option> ]\n\n"
+          "OPTIONS:\n"
+
+          "    -o <offset>                  -- set memory offset\n"
+          "    -d <flag>                    -- set a gem5 debug flag\n"
+          "                                    (-<flag> clears a flag)\n"
+          "    -v                           -- verbose output\n"
+          "    -e <ticks>                   -- end of simulation after a \n"
+          "                                    given number of ticks\n"
+          "\n");
+    std::exit(EXIT_FAILURE);
+}
+
+void
+CliParser::parse(int argc, char** argv)
+{
+    std::string prog_name(argv[0]);
+
+    unsigned int arg_ptr = 1;
+
+    if (argc == 1) {
+        usage(prog_name);
+    }
+
+    configFile = std::string(argv[arg_ptr]);
+    arg_ptr++;
+
+    // default values
+    verboseFlag = false;
+    simulationEnd = 0;
+    memoryOffset = 0;
+
+    try {
+        while (arg_ptr < argc) {
+            std::string option(argv[arg_ptr]);
+            arg_ptr++;
+            unsigned num_args = argc - arg_ptr;
+
+            if (option == "-d") {
+                if (num_args < 1) {
+                    usage(prog_name);
+                }
+                std::string flag(argv[arg_ptr]);
+                arg_ptr++;
+                debugFlags.push_back(flag);
+            } else if (option == "-e") {
+                if (num_args < 1) {
+                    usage(prog_name);
+                }
+                std::istringstream(argv[arg_ptr]) >> simulationEnd;
+                arg_ptr++;
+            } else if (option == "-v") {
+                verboseFlag = true;
+            } else if (option == "-o") {
+                if (num_args < 1) {
+                    usage(prog_name);
+                }
+                std::istringstream(argv[arg_ptr]) >> memoryOffset;
+                arg_ptr++;
+                /* code */
+            } else {
+                usage(prog_name);
+            }
+        }
+    } catch (CxxConfigManager::Exception &e) {
+        std::cerr << e.name << ": " << e.message << "\n";
+        std::exit(EXIT_FAILURE);
+    }
+
+    parsed = true;
+}
+
+std::string
+CliParser::getDebugFlags()
+{
+    std::stringstream ss;
+    for (auto& flag : debugFlags) {
+        ss << flag << ' ';
+    }
+    return ss.str();
+}
diff --git a/util/tlm/examples/common/cli_parser.hh b/util/tlm/examples/common/cli_parser.hh
new file mode 100644
index 000000000..3f8913115
--- /dev/null
+++ b/util/tlm/examples/common/cli_parser.hh
@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2016, Dresden University of Technology (TU Dresden)
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * 3. Neither the name of the copyright holder nor the names of its
+ *    contributors may be used to endorse or promote products derived from
+ *    this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER
+ * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * Authors: Christian Menard
+ */
+
+#ifndef __CLI_PARSER_HH__
+#define __CLI_PARSER_HH__
+
+#include <cassert>
+#include <string>
+#include <vector>
+
+class CliParser
+{
+  private:
+    int argc;
+    char** argv;
+
+    bool parsed;
+
+    uint64_t memoryOffset;
+    uint64_t simulationEnd;
+    bool verboseFlag;
+    std::vector<std::string> debugFlags;
+    std::string configFile;
+
+    void usage(const std::string& prog_name);
+  public:
+
+    CliParser() : parsed(false) {}
+
+    void parse(int argc, char** argv);
+
+    uint64_t getMemoryOffset()  { assert(parsed); return memoryOffset; }
+    uint64_t getSimulationEnd() { assert(parsed); return simulationEnd; }
+    bool getVerboseFlag()       { assert(parsed); return verboseFlag; }
+    std::string getConfigFile() { assert(parsed); return configFile; }
+    std::string getDebugFlags();
+};
+
+#endif
diff --git a/util/tlm/examples/common/report_handler.cc b/util/tlm/examples/common/report_handler.cc
new file mode 100644
index 000000000..56a03ec31
--- /dev/null
+++ b/util/tlm/examples/common/report_handler.cc
@@ -0,0 +1,87 @@
+/*
+ * Copyright (c) 2016, Dresden University of Technology (TU Dresden)
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * 3. Neither the name of the copyright holder nor the names of its
+ *    contributors may be used to endorse or promote products derived from
+ *    this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER
+ * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * Authors: Christian Menard
+ */
+
+#include <iostream>
+#include <systemc>
+
+#include <sim/core.hh>
+#include <sim/simulate.hh>
+
+#include "report_handler.hh"
+
+using namespace sc_core;
+
+void
+reportHandler(const sc_report &report, const sc_actions &actions)
+{
+    uint64_t systemc_time = report.get_time().value();
+    uint64_t gem5_time = curTick();
+
+    if (actions & SC_DO_NOTHING)
+        return;
+
+    if (actions & SC_DISPLAY || actions & SC_LOG)
+    {
+        std::ostream& stream = actions & SC_DISPLAY ? std::cout : std::cerr;
+
+        stream << report.get_time();
+
+        if (gem5_time < systemc_time) {
+            stream << " (<) ";
+        } else if (gem5_time > systemc_time) {
+            stream << " (!) ";
+        } else {
+            stream << " (=) ";
+        }
+
+        stream << ": " << report.get_msg_type()
+               << ' ' << report.get_msg() << '\n';
+    }
+
+    if (actions & SC_THROW) {
+        std::cerr << "warning: the report handler ignored a SC_THROW action\n";
+    } else if (actions & SC_INTERRUPT) {
+        std::cerr << "warning: the report handler ignored a SC_INTERRUPT"
+                  << "action\n";
+    } else if (actions & SC_CACHE_REPORT) {
+        std::cerr << "warning: the report handler ignored a SC_CACHE_REPORT"
+                  << "action\n";
+    }
+
+    if (actions & SC_STOP)
+        sc_stop();
+
+    if (actions & SC_ABORT)
+        abort();
+}
diff --git a/util/tlm/examples/common/report_handler.hh b/util/tlm/examples/common/report_handler.hh
new file mode 100644
index 000000000..bd91b77d0
--- /dev/null
+++ b/util/tlm/examples/common/report_handler.hh
@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2016, Dresden University of Technology (TU Dresden)
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *
+ * 3. Neither the name of the copyright holder nor the names of its
+ *    contributors may be used to endorse or promote products derived from
+ *    this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER
+ * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * Authors: Matthias Jung
+ *          Christian Menard
+ */
+
+#ifndef __REPORT_HANDLER_HH__
+#define __REPORT_HANDLER_HH__
+
+void reportHandler(const sc_core::sc_report &report,
+                   const sc_core::sc_actions &actions);
+
+#endif
diff --git a/util/tlm/examples/master_port/SConstruct b/util/tlm/examples/master_port/SConstruct
index 8ca9959a0..a896a34e4 100644
--- a/util/tlm/examples/master_port/SConstruct
+++ b/util/tlm/examples/master_port/SConstruct
@@ -54,7 +54,8 @@ env.ParseConfig('pkg-config --cflags --libs systemc')
 # add include dirs
 env.Append(CPPPATH=[gem5_root + '/build/' + gem5_arch,
                     gem5_root + '/util/systemc',
-                    gem5_root + '/util/tlm'])
+                    gem5_root + '/util/tlm',
+                    '../common'])
 
 env.Append(LIBS=['gem5_' + gem5_variant])
 env.Append(LIBPATH=[gem5_root + '/build/' + gem5_arch])
@@ -72,6 +73,6 @@ src_systemc = [gem5_root + '/util/systemc/sc_gem5_control.cc',
                gem5_root + '/util/systemc/stats.cc']
 
 src_tlm     = Glob(gem5_root + '/util/tlm/*.cc')
-src_main    = Glob('*.cc')
+src_main    = Glob('*.cc') + Glob('../common/*.cc')
 
 main = env.Program(target, src_systemc + src_tlm + src_main)
diff --git a/util/tlm/examples/master_port/main.cc b/util/tlm/examples/master_port/main.cc
index 205e430ae..588d81156 100644
--- a/util/tlm/examples/master_port/main.cc
+++ b/util/tlm/examples/master_port/main.cc
@@ -35,44 +35,27 @@
 #include <systemc>
 #include <tlm>
 
+#include "cli_parser.hh"
+#include "report_handler.hh"
 #include "sc_master_port.hh"
 #include "sim_control.hh"
 #include "stats.hh"
 #include "traffic_generator.hh"
 
-// Defining global string variable decalred in stats.hh
-std::string filename;
-
-void
-reportHandler(const sc_core::sc_report& report,
-              const sc_core::sc_actions& actions)
-{
-    uint64_t systemc_time = report.get_time().value();
-    uint64_t gem5_time = curTick();
-
-    std::cerr << report.get_time();
-
-    if (gem5_time < systemc_time) {
-        std::cerr << " (<) ";
-    } else if (gem5_time > systemc_time) {
-        std::cerr << " (!) ";
-    } else {
-        std::cerr << " (=) ";
-    }
-
-    std::cerr << ": " << report.get_msg_type() << ' ' << report.get_msg()
-              << '\n';
-}
-
 int
 sc_main(int argc, char** argv)
 {
+    CliParser parser;
+    parser.parse(argc, argv);
+
     sc_core::sc_report_handler::set_handler(reportHandler);
 
-    SimControl simControl("gem5", argc, argv);
-    TrafficGenerator trafficGenerator("traffic_generator");
+    Gem5SystemC::Gem5SimControl simControl("gem5",
+                                           parser.getConfigFile(),
+                                           parser.getSimulationEnd(),
+                                           parser.getDebugFlags());
 
-    filename = "m5out/stats-systemc.txt";
+    TrafficGenerator trafficGenerator("traffic_generator");
 
     tlm::tlm_target_socket<>* mem_port =
       dynamic_cast<tlm::tlm_target_socket<>*>(
@@ -86,7 +69,7 @@ sc_main(int argc, char** argv)
         std::exit(EXIT_FAILURE);
     }
 
-    std::cout << "Starting sc_main" << std::endl;
+    SC_REPORT_INFO("sc_main", "Start of Simulation");
 
     sc_core::sc_start(); // Run to end of simulation
 
diff --git a/util/tlm/examples/slave_port/SConstruct b/util/tlm/examples/slave_port/SConstruct
index 8ca9959a0..a896a34e4 100644
--- a/util/tlm/examples/slave_port/SConstruct
+++ b/util/tlm/examples/slave_port/SConstruct
@@ -54,7 +54,8 @@ env.ParseConfig('pkg-config --cflags --libs systemc')
 # add include dirs
 env.Append(CPPPATH=[gem5_root + '/build/' + gem5_arch,
                     gem5_root + '/util/systemc',
-                    gem5_root + '/util/tlm'])
+                    gem5_root + '/util/tlm',
+                    '../common'])
 
 env.Append(LIBS=['gem5_' + gem5_variant])
 env.Append(LIBPATH=[gem5_root + '/build/' + gem5_arch])
@@ -72,6 +73,6 @@ src_systemc = [gem5_root + '/util/systemc/sc_gem5_control.cc',
                gem5_root + '/util/systemc/stats.cc']
 
 src_tlm     = Glob(gem5_root + '/util/tlm/*.cc')
-src_main    = Glob('*.cc')
+src_main    = Glob('*.cc') + Glob('../common/*.cc')
 
 main = env.Program(target, src_systemc + src_tlm + src_main)
diff --git a/util/tlm/examples/slave_port/main.cc b/util/tlm/examples/slave_port/main.cc
index 256a99d1b..9f1cadc8d 100644
--- a/util/tlm/examples/slave_port/main.cc
+++ b/util/tlm/examples/slave_port/main.cc
@@ -43,48 +43,30 @@
  *
  */
 
-#include <tlm_utils/simple_target_socket.h>
-
 #include <systemc>
 #include <tlm>
 
+#include "cli_parser.hh"
+#include "report_handler.hh"
 #include "sc_target.hh"
 #include "sim_control.hh"
 #include "stats.hh"
 
-// Defining global string variable decalred in stats.hh
-std::string filename;
-
-void
-reportHandler(const sc_core::sc_report &report,
-              const sc_core::sc_actions &actions)
-{
-    uint64_t systemc_time = report.get_time().value();
-    uint64_t gem5_time = curTick();
-
-    std::cerr << report.get_time();
-
-    if (gem5_time < systemc_time) {
-        std::cerr << " (<) ";
-    } else if (gem5_time > systemc_time) {
-        std::cerr << " (!) ";
-    } else {
-        std::cerr << " (=) ";
-    }
-
-    std::cerr << ": " << report.get_msg_type()
-              << ' ' << report.get_msg() << '\n';
-}
-
 int
 sc_main(int argc, char **argv)
 {
+    CliParser parser;
+    parser.parse(argc, argv);
+
     sc_core::sc_report_handler::set_handler(reportHandler);
 
-    SimControl sim_control("gem5", argc, argv);
+    Gem5SystemC::Gem5SimControl simControl("gem5",
+                                           parser.getConfigFile(),
+                                           parser.getSimulationEnd(),
+                                           parser.getDebugFlags());
     Target *memory;
 
-    filename = "m5out/stats-systemc.txt";
+    unsigned long long int memorySize = 512*1024*1024ULL;
 
     tlm::tlm_initiator_socket <> *mem_port =
         dynamic_cast<tlm::tlm_initiator_socket<> *>(
@@ -93,11 +75,10 @@ sc_main(int argc, char **argv)
 
     if (mem_port) {
         SC_REPORT_INFO("sc_main", "Port Found");
-        unsigned long long int size = 512*1024*1024ULL;
         memory = new Target("memory",
-                            sim_control.getDebugFlag(),
-                            size,
-                            sim_control.getOffset());
+                            parser.getVerboseFlag(),
+                            memorySize,
+                            parser.getMemoryOffset());
 
         memory->socket.bind(*mem_port);
     } else {
@@ -105,6 +86,8 @@ sc_main(int argc, char **argv)
         std::exit(EXIT_FAILURE);
     }
 
+    SC_REPORT_INFO("sc_main", "Start of Simulation");
+
     sc_core::sc_start();
 
     SC_REPORT_INFO("sc_main", "End of Simulation");