util/systemc/gem5_within_systemc/sc_gem5_control.hh

   1 /*
   2  * Copyright (c) 2014 ARM Limited
   3  * All rights reserved
   4  *
   5  * The license below extends only to copyright in the software and shall
   6  * not be construed as granting a license to any other intellectual
   7  * property including but not limited to intellectual property relating
   8  * to a hardware implementation of the functionality of the software
   9  * licensed hereunder.  You may use the software subject to the license
  10  * terms below provided that you ensure that this notice is replicated
  11  * unmodified and in its entirety in all distributions of the software,
  12  * modified or unmodified, in source code or in binary form.
  13  *
  14  * Redistribution and use in source and binary forms, with or without
  15  * modification, are permitted provided that the following conditions are
  16  * met: redistributions of source code must retain the above copyright
  17  * notice, this list of conditions and the following disclaimer;
  18  * redistributions in binary form must reproduce the above copyright
  19  * notice, this list of conditions and the following disclaimer in the
  20  * documentation and/or other materials provided with the distribution;
  21  * neither the name of the copyright holders nor the names of its
  22  * contributors may be used to endorse or promote products derived from
  23  * this software without specific prior written permission.
  24  *
  25  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  26  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  27  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  28  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  29  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  30  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  31  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  32  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  33  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  34  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  35  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  36  */
  37
  38 /**
  39  * @file
  40  *
  41  *  Top level definitions for exporting gem5 across a dlopen interface.
  42  *
  43  *  Gem5Control should be instantiated once to build the gem5 root.
  44  *  Systems from that root's config file can then be instantiated as
  45  *  Gem5System's using Gem5Control::makeSystem.
  46  *
  47  *  Gem5Control contains a Gem5TopLevelModule which is a SystemC
  48  *  module providing the gem5 `simulate' function as its sole
  49  *  thread action.
  50  */
  51
  52 #ifndef __SIM_SC_GEM5_CONTROL_HH__
  53 #define __SIM_SC_GEM5_CONTROL_HH__
  54
  55 #include <string>
  56 #include <vector>
  57
  58 class CxxConfigManager;
  59
  60 namespace Gem5SystemC
  61 {
  62
  63 class Gem5TopLevelModule;
  64 class Gem5Control;
  65
  66 /** Gem5System's wrap CxxConfigManager's instantiating a gem5 System
  67  *  object (and its children).  New Gem5Systems are created by
  68  *  Gem5Control::makeSystem.  A new system can have its parameters
  69  *  tweaked using setParam{,Vector} before being instantiated using
  70  *  Gem5System::instantiate.  After instantiation, any external ports
  71  *  declared by the system should be visible in SystemC.
  72  *
  73  *  It is recommended that a SystemC wrapper sc_module is declared to
  74  *  own each Gem5System with the call to Gem5System::instantiate being
  75  *  made in that wrapper's constructor
  76  *
  77  *  Note that *every* `normal' member function in this class *must*
  78  *  be virtual to ensure that references to the functions go through
  79  *  the pointer acquired using makeSystem and not looked up as
  80  *  name-mangled symbols
  81  *
  82  *  */
  83 class Gem5System
  84 {
  85   private:
  86     /** Config management for *just* this system's objects (notably
  87      *  excluding root */
  88     CxxConfigManager *manager;
  89
  90     /** The config file prototype for the system */
  91     std::string systemName;
  92
  93     /** The instantiated (in gem5) name of the system */
  94     std::string instanceName;
  95
  96   public:
  97     /** A constructor only used by Gem5Control */
  98     Gem5System(CxxConfigManager *manager_,
  99         const std::string &system_name, const std::string &instance_name);
 100
 101     virtual ~Gem5System();
 102
 103     /** Parameter setting functions callable before instantiate */
 104     virtual void setParam(const std::string &object,
 105         const std::string &param_name, const std::string &param_value);
 106
 107     virtual void setParamVector(const std::string &system_name,
 108         const std::string &param_name,
 109         const std::vector<std::string> &param_values);
 110
 111     /** Build the system's gem5 infrastructure, bind its ports (note
 112      *  that all ports *must* be internal to the system), init and
 113      *  SimObject::startup the system */
 114     virtual void instantiate();
 115 };
 116
 117 /** Singleton class containing gem5 simulation control.
 118  *
 119  *  Note that *every* `normal' member function in this class *must*
 120  *  be virtual to ensure that references to the functions go through
 121  *  the pointer acquired using makeGem5Control and not looked up as
 122  *  name-mangled symbols
 123  */
 124 class Gem5Control
 125 {
 126   private:
 127     /** Private SystemC module containing top level simulation control */
 128     Gem5TopLevelModule *module;
 129
 130     /** One-time-settable version string */
 131     std::string version;
 132
 133   public:
 134     Gem5Control(const std::string &config_filename);
 135
 136     virtual ~Gem5Control();
 137
 138     /** Set/clear a gem5 debug flag */
 139     virtual void setDebugFlag(const char *flag);
 140     virtual void clearDebugFlag(const char *flag);
 141
 142     /** Choose a base port number for GDB to connect to the model
 143      *  (0 disables connections) */
 144     virtual void setRemoteGDBPort(unsigned int port);
 145
 146     /* Register an action to happen at the end of elaboration */
 147     virtual void registerEndOfElaboration(void (*func)());
 148
 149     /** Make a System from the config file description for system
 150      *  system_name and call it instance_name in gem5 */
 151     virtual Gem5System *makeSystem(const std::string &system_name,
 152         const std::string &top_instance);
 153
 154     /** set/get version string */
 155     virtual const std::string &getVersion() const;
 156     virtual void setVersion(const std::string &new_version);
 157 };
 158
 159 }
 160
 161 /** Instantiate a Gem5Control.  This can be called using dlopen/dlsym
 162  *  to kick-start gem5 */
 163 extern "C" Gem5SystemC::Gem5Control *makeGem5Control(
 164     const std::string &config_filename);
 165
 166 #endif // __SIM_SC_GEM5_CONTROL_HH__