sim_object.hh revision 56 
1/*
2 * Copyright (c) 2003 The Regents of The University of Michigan
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are
7 * met: redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer;
9 * redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution;
12 * neither the name of the copyright holders nor the names of its
13 * contributors may be used to endorse or promote products derived from
14 * this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
17 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
18 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
19 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
20 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
21 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
22 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
26 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28
29/* @file
30 * User Console Definitions
31 */
32
33#ifndef __SIM_OBJECT_HH__
34#define __SIM_OBJECT_HH__
35
36#include <map>
37#include <list>
38#include <vector>
39#include <iostream>
40
41#include "sim/param.hh"
42#include "sim/serialize.hh"
43
44/*
45 * Abstract superclass for simulation objects.  Represents things that
46 * correspond to physical components and can be specified via the
47 * config file (CPUs, caches, etc.).
48 */
49class SimObject : public Serializeable
50{
51  private:
52    friend class Serializer;
53
54    typedef std::vector<SimObject *> SimObjectList;
55
56    // list of all instantiated simulation objects
57    static SimObjectList simObjectList;
58
59  public:
60    SimObject(const std::string &_name);
61
62    virtual ~SimObject() {}
63
64    // register statistics for this object
65    virtual void regStats();
66    virtual void regFormulas();
67
68    // print extra results for this object not covered by registered
69    // statistics (called at end of simulation)
70    virtual void printExtraOutput(std::ostream&);
71
72    // static: call reg_stats on all SimObjects
73    static void regAllStats();
74
75    // static: call printExtraOutput on all SimObjects
76    static void printAllExtraOutput(std::ostream&);
77};
78
79
80//
81// A SimObjectBuilder serves as an evaluation context for a set of
82// parameters that describe a specific instance of a SimObject.  This
83// evaluation context corresponds to a section in the .ini file (as
84// with the base ParamContext) plus an optional node in the
85// configuration hierarchy (the configNode member) for resolving
86// SimObject references.  SimObjectBuilder is an abstract superclass;
87// derived classes specialize the class for particular subclasses of
88// SimObject (e.g., BaseCache).
89//
90// For typical usage, see the definition of
91// SimObjectClass::createObject().
92//
93class SimObjectBuilder : public ParamContext
94{
95  private:
96    // name of the instance we are creating
97    std::string instanceName;
98
99    // The corresponding node in the configuration hierarchy.
100    // (optional: may be null if the created object is not in the
101    // hierarchy)
102    ConfigNode *configNode;
103
104    // The external SimObject class name (for error messages)
105    std::string simObjClassName;
106
107  public:
108    SimObjectBuilder(const std::string &_configClass,
109                     const std::string &_instanceName,
110                     ConfigNode *_configNode,
111                     const std::string &_simObjClassName)
112        : ParamContext(_configClass, true),
113          instanceName(_instanceName),
114          configNode(_configNode),
115          simObjClassName(_simObjClassName)
116    {
117    }
118
119    virtual ~SimObjectBuilder() {}
120
121    // call parse() on all params in this context to convert string
122    // representations to parameter values
123    virtual void parseParams(IniFile &iniFile);
124
125    // parameter error prolog (override of ParamContext)
126    virtual void printErrorProlog(std::ostream &);
127
128    // generate the name for this SimObject instance (derived from the
129    // configuration hierarchy node label and position)
130    virtual const std::string &getInstanceName() { return instanceName; }
131
132    // return the configuration hierarchy node for this context.
133    virtual ConfigNode *getConfigNode() { return configNode; }
134
135    // Create the actual SimObject corresponding to the parameter
136    // values in this context.  This function is overridden in derived
137    // classes to call a specific constructor for a particular
138    // subclass of SimObject.
139    virtual SimObject *create() = 0;
140};
141
142
143//
144// Handy macros for initializing parameter members of classes derived
145// from SimObjectBuilder.  Assumes that the name of the parameter
146// member object is the same as the textual parameter name seen by the
147// user.  (Note that '#p' is expanded by the preprocessor to '"p"'.)
148//
149#define INIT_PARAM(p, desc)		p(this, #p, desc)
150#define INIT_PARAM_DFLT(p, desc, dflt)	p(this, #p, desc, dflt)
151
152//
153// Initialize an enumeration variable... assumes that 'map' is the
154// name of an array of mappings (char * for SimpleEnumParam, or
155// EnumParamMap for MappedEnumParam).
156//
157#define INIT_ENUM_PARAM(p, desc, map)	\
158        p(this, #p, desc, map, sizeof(map)/sizeof(map[0]))
159#define INIT_ENUM_PARAM_DFLT(p, desc, map, dflt)	\
160        p(this, #p, desc, map, sizeof(map)/sizeof(map[0]), dflt)
161
162//
163// An instance of SimObjectClass corresponds to a class derived from
164// SimObject.  The SimObjectClass instance serves to bind the string
165// name (found in the config file) to a function that creates an
166// instance of the appropriate derived class.
167//
168// This would be much cleaner in Smalltalk or Objective-C, where types
169// are first-class objects themselves.
170//
171class SimObjectClass
172{
173  public:
174    // Type CreateFunc is a pointer to a function that creates a new
175    // simulation object builder based on a .ini-file parameter
176    // section (specified by the first string argument), a unique name
177    // for the object (specified by the second string argument), and
178    // an optional config hierarchy node (specified by the third
179    // argument).  A pointer to the new SimObjectBuilder is returned.
180    typedef SimObjectBuilder *(*CreateFunc)(const std::string &configClassName,
181                                            const std::string &objName,
182                                            ConfigNode *configNode,
183                                            const std::string &simObjClassName);
184
185    static std::map<std::string,CreateFunc> *classMap;
186
187    // Constructor.  For example:
188    //
189    // SimObjectClass baseCacheClass("BaseCache", newBaseCacheBuilder);
190    //
191    SimObjectClass(const std::string &className, CreateFunc createFunc);
192
193    // create SimObject given name of class and pointer to
194    // configuration hierarchy node
195    static SimObject *createObject(IniFile &configDB,
196                                   const std::string &configClassName,
197                                   const std::string &objName,
198                                   ConfigNode *configNode);
199
200    // print descriptions of all parameters registered with all
201    // SimObject classes
202    static void describeAllClasses(std::ostream &os);
203};
204
205//
206// Macros to encapsulate the magic of declaring & defining
207// SimObjectBuilder and SimObjectClass objects
208//
209
210#define BEGIN_DECLARE_SIM_OBJECT_PARAMS(OBJ_CLASS)		\
211class OBJ_CLASS##Builder : public SimObjectBuilder		\
212{								\
213  public:
214
215#define END_DECLARE_SIM_OBJECT_PARAMS(OBJ_CLASS)		\
216                                                                \
217    OBJ_CLASS##Builder(const std::string &configClass,		\
218                       const std::string &instanceName,		\
219                       ConfigNode *configNode,			\
220                       const std::string &simObjClassName);	\
221    virtual ~OBJ_CLASS##Builder() {}				\
222                                                                \
223    OBJ_CLASS *create();					\
224};
225
226#define BEGIN_INIT_SIM_OBJECT_PARAMS(OBJ_CLASS)				   \
227OBJ_CLASS##Builder::OBJ_CLASS##Builder(const std::string &configClass,	   \
228                                       const std::string &instanceName,	   \
229                                       ConfigNode *configNode,		   \
230                                       const std::string &simObjClassName) \
231    : SimObjectBuilder(configClass, instanceName,			   \
232                       configNode, simObjClassName),
233
234
235#define END_INIT_SIM_OBJECT_PARAMS(OBJ_CLASS)			\
236{								\
237}
238
239#define CREATE_SIM_OBJECT(OBJ_CLASS)				\
240OBJ_CLASS *OBJ_CLASS##Builder::create()
241
242#define REGISTER_SIM_OBJECT(CLASS_NAME, OBJ_CLASS)		\
243SimObjectBuilder *						\
244new##OBJ_CLASS##Builder(const std::string &configClass,		\
245                        const std::string &instanceName,	\
246                        ConfigNode *configNode,			\
247                        const std::string &simObjClassName)	\
248{								\
249    return new OBJ_CLASS##Builder(configClass, instanceName,	\
250                                  configNode, simObjClassName);	\
251}								\
252                                                                \
253SimObjectClass the##OBJ_CLASS##Class(CLASS_NAME,		\
254                                     new##OBJ_CLASS##Builder);	\
255                                                                \
256/* see param.hh */						\
257DEFINE_SIM_OBJECT_CLASS_NAME(CLASS_NAME, OBJ_CLASS)
258
259
260#endif // __SIM_OBJECT_HH__
261