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 * Authors: Andrew Bardsley
38 */
39
40/**
41 * @file
42 *
43 *  Top level definitions for exporting gem5 across a dlopen interface.
44 *
45 *  Gem5Control should be instantiated once to build the gem5 root.
46 *  Systems from that root's config file can then be instantiated as
47 *  Gem5System's using Gem5Control::makeSystem.
48 *
49 *  Gem5Control contains a Gem5TopLevelModule which is a SystemC
50 *  module providing the gem5 `simulate' function as its sole
51 *  thread action.
52 */
53
54#ifndef __SIM_SC_GEM5_CONTROL_HH__
55#define __SIM_SC_GEM5_CONTROL_HH__
56
57#include <string>
58#include <vector>
59
60class CxxConfigManager;
61
62namespace Gem5SystemC
63{
64
65class Gem5TopLevelModule;
66class Gem5Control;
67
68/** Gem5System's wrap CxxConfigManager's instantiating a gem5 System
69 *  object (and its children).  New Gem5Systems are created by
70 *  Gem5Control::makeSystem.  A new system can have its parameters
71 *  tweaked using setParam{,Vector} before being instantiated using
72 *  Gem5System::instantiate.  After instantiation, any external ports
73 *  declared by the system should be visible in SystemC.
74 *
75 *  It is recommended that a SystemC wrapper sc_module is declared to
76 *  own each Gem5System with the call to Gem5System::instantiate being
77 *  made in that wrapper's constructor
78 *
79 *  Note that *every* `normal' member function in this class *must*
80 *  be virtual to ensure that references to the functions go through
81 *  the pointer acquired using makeSystem and not looked up as
82 *  name-mangled symbols
83 *
84 *  */
85class Gem5System
86{
87  private:
88    /** Config management for *just* this system's objects (notably
89     *  excluding root */
90    CxxConfigManager *manager;
91
92    /** The config file prototype for the system */
93    std::string systemName;
94
95    /** The instantiated (in gem5) name of the system */
96    std::string instanceName;
97
98  public:
99    /** A constructor only used by Gem5Control */
100    Gem5System(CxxConfigManager *manager_,
101        const std::string &system_name, const std::string &instance_name);
102
103    virtual ~Gem5System();
104
105    /** Parameter setting functions callable before instantiate */
106    virtual void setParam(const std::string &object,
107        const std::string &param_name, const std::string &param_value);
108
109    virtual void setParamVector(const std::string &system_name,
110        const std::string &param_name,
111        const std::vector<std::string> &param_values);
112
113    /** Build the system's gem5 infrastructure, bind its ports (note
114     *  that all ports *must* be internal to the system), init and
115     *  SimObject::startup the system */
116    virtual void instantiate();
117};
118
119/** Singleton class containing gem5 simulation control.
120 *
121 *  Note that *every* `normal' member function in this class *must*
122 *  be virtual to ensure that references to the functions go through
123 *  the pointer acquired using makeGem5Control and not looked up as
124 *  name-mangled symbols
125 */
126class Gem5Control
127{
128  private:
129    /** Private SystemC module containing top level simulation control */
130    Gem5TopLevelModule *module;
131
132    /** One-time-settable version string */
133    std::string version;
134
135  public:
136    Gem5Control(const std::string &config_filename);
137
138    virtual ~Gem5Control();
139
140    /** Set/clear a gem5 debug flag */
141    virtual void setDebugFlag(const char *flag);
142    virtual void clearDebugFlag(const char *flag);
143
144    /** Choose a base port number for GDB to connect to the model
145     *  (0 disables connections) */
146    virtual void setRemoteGDBPort(unsigned int port);
147
148    /* Register an action to happen at the end of elaboration */
149    virtual void registerEndOfElaboration(void (*func)());
150
151    /** Make a System from the config file description for system
152     *  system_name and call it instance_name in gem5 */
153    virtual Gem5System *makeSystem(const std::string &system_name,
154        const std::string &top_instance);
155
156    /** set/get version string */
157    virtual const std::string &getVersion() const;
158    virtual void setVersion(const std::string &new_version);
159};
160
161}
162
163/** Instantiate a Gem5Control.  This can be called using dlopen/dlsym
164 *  to kick-start gem5 */
165extern "C" Gem5SystemC::Gem5Control *makeGem5Control(
166    const std::string &config_filename);
167
168#endif // __SIM_SC_GEM5_CONTROL_HH__
169