sim_object.hh revision 2 
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 "param.hh"
42#include "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 reg_stats(struct stat_sdb_t *sdb);
66    virtual void regStats();
67    virtual void regFormulas();
68
69    // print extra results for this object not covered by registered
70    // statistics (called at end of simulation)
71    virtual void printExtraOutput(std::ostream&);
72
73    // static: call reg_stats on all SimObjects
74    static void regAllStats();
75
76    // static: call printExtraOutput on all SimObjects
77    static void printAllExtraOutput(std::ostream&);
78};
79
80
81//
82// A SimObjectBuilder serves as an evaluation context for a set of
83// parameters that describe a specific instance of a SimObject.  This
84// evaluation context corresponds to a section in the .ini file (as
85// with the base ParamContext) plus an optional node in the
86// configuration hierarchy (the configNode member) for resolving
87// SimObject references.  SimObjectBuilder is an abstract superclass;
88// derived classes specialize the class for particular subclasses of
89// SimObject (e.g., BaseCache).
90//
91// For typical usage, see the definition of
92// SimObjectClass::createObject().
93//
94class SimObjectBuilder : public ParamContext
95{
96  private:
97    // name of the instance we are creating
98    std::string instanceName;
99
100    // The corresponding node in the configuration hierarchy.
101    // (optional: may be null if the created object is not in the
102    // hierarchy)
103    ConfigNode *configNode;
104
105    // The external SimObject class name (for error messages)
106    std::string simObjClassName;
107
108  public:
109    SimObjectBuilder(const std::string &_configClass,
110                     const std::string &_instanceName,
111                     ConfigNode *_configNode,
112                     const std::string &_simObjClassName)
113        : ParamContext(_configClass, true),
114          instanceName(_instanceName),
115          configNode(_configNode),
116          simObjClassName(_simObjClassName)
117    {
118    }
119
120    virtual ~SimObjectBuilder() {}
121
122    // call parse() on all params in this context to convert string
123    // representations to parameter values
124    virtual void parseParams(IniFile &iniFile);
125
126    // parameter error prolog (override of ParamContext)
127    virtual void printErrorProlog(std::ostream &);
128
129    // generate the name for this SimObject instance (derived from the
130    // configuration hierarchy node label and position)
131    virtual const std::string &getInstanceName() { return instanceName; }
132
133    // return the configuration hierarchy node for this context.
134    virtual ConfigNode *getConfigNode() { return configNode; }
135
136    // Create the actual SimObject corresponding to the parameter
137    // values in this context.  This function is overridden in derived
138    // classes to call a specific constructor for a particular
139    // subclass of SimObject.
140    virtual SimObject *create() = 0;
141};
142
143
144//
145// Handy macros for initializing parameter members of classes derived
146// from SimObjectBuilder.  Assumes that the name of the parameter
147// member object is the same as the textual parameter name seen by the
148// user.  (Note that '#p' is expanded by the preprocessor to '"p"'.)
149//
150#define INIT_PARAM(p, desc)		p(this, #p, desc)
151#define INIT_PARAM_DFLT(p, desc, dflt)	p(this, #p, desc, dflt)
152
153//
154// Initialize an enumeration variable... assumes that 'map' is the
155// name of an array of mappings (char * for SimpleEnumParam, or
156// EnumParamMap for MappedEnumParam).
157//
158#define INIT_ENUM_PARAM(p, desc, map)	\
159        p(this, #p, desc, map, sizeof(map)/sizeof(map[0]))
160#define INIT_ENUM_PARAM_DFLT(p, desc, map, dflt)	\
161        p(this, #p, desc, map, sizeof(map)/sizeof(map[0]), dflt)
162
163//
164// An instance of SimObjectClass corresponds to a class derived from
165// SimObject.  The SimObjectClass instance serves to bind the string
166// name (found in the config file) to a function that creates an
167// instance of the appropriate derived class.
168//
169// This would be much cleaner in Smalltalk or Objective-C, where types
170// are first-class objects themselves.
171//
172class SimObjectClass
173{
174  public:
175    // Type CreateFunc is a pointer to a function that creates a new
176    // simulation object builder based on a .ini-file parameter
177    // section (specified by the first string argument), a unique name
178    // for the object (specified by the second string argument), and
179    // an optional config hierarchy node (specified by the third
180    // argument).  A pointer to the new SimObjectBuilder is returned.
181    typedef SimObjectBuilder *(*CreateFunc)(const std::string &configClassName,
182                                            const std::string &objName,
183                                            ConfigNode *configNode,
184                                            const std::string &simObjClassName);
185
186    static std::map<std::string,CreateFunc> *classMap;
187
188    // Constructor.  For example:
189    //
190    // SimObjectClass baseCacheClass("BaseCache", newBaseCacheBuilder);
191    //
192    SimObjectClass(const std::string &className, CreateFunc createFunc);
193
194    // create SimObject given name of class and pointer to
195    // configuration hierarchy node
196    static SimObject *createObject(IniFile &configDB,
197                                   const std::string &configClassName,
198                                   const std::string &objName,
199                                   ConfigNode *configNode);
200
201    // print descriptions of all parameters registered with all
202    // SimObject classes
203    static void describeAllClasses(std::ostream &os);
204};
205
206//
207// Macros to encapsulate the magic of declaring & defining
208// SimObjectBuilder and SimObjectClass objects
209//
210
211#define BEGIN_DECLARE_SIM_OBJECT_PARAMS(OBJ_CLASS)		\
212class OBJ_CLASS##Builder : public SimObjectBuilder		\
213{								\
214  public:
215
216#define END_DECLARE_SIM_OBJECT_PARAMS(OBJ_CLASS)		\
217                                                                \
218    OBJ_CLASS##Builder(const std::string &configClass,		\
219                       const std::string &instanceName,		\
220                       ConfigNode *configNode,			\
221                       const std::string &simObjClassName);	\
222    virtual ~OBJ_CLASS##Builder() {}				\
223                                                                \
224    OBJ_CLASS *create();					\
225};
226
227#define BEGIN_INIT_SIM_OBJECT_PARAMS(OBJ_CLASS)				   \
228OBJ_CLASS##Builder::OBJ_CLASS##Builder(const std::string &configClass,	   \
229                                       const std::string &instanceName,	   \
230                                       ConfigNode *configNode,		   \
231                                       const std::string &simObjClassName) \
232    : SimObjectBuilder(configClass, instanceName,			   \
233                       configNode, simObjClassName),
234
235
236#define END_INIT_SIM_OBJECT_PARAMS(OBJ_CLASS)			\
237{								\
238}
239
240#define CREATE_SIM_OBJECT(OBJ_CLASS)				\
241OBJ_CLASS *OBJ_CLASS##Builder::create()
242
243#define REGISTER_SIM_OBJECT(CLASS_NAME, OBJ_CLASS)		\
244SimObjectBuilder *						\
245new##OBJ_CLASS##Builder(const std::string &configClass,		\
246                        const std::string &instanceName,	\
247                        ConfigNode *configNode,			\
248                        const std::string &simObjClassName)	\
249{								\
250    return new OBJ_CLASS##Builder(configClass, instanceName,	\
251                                  configNode, simObjClassName);	\
252}								\
253                                                                \
254SimObjectClass the##OBJ_CLASS##Class(CLASS_NAME,		\
255                                     new##OBJ_CLASS##Builder);	\
256                                                                \
257/* see param.hh */						\
258DEFINE_SIM_OBJECT_CLASS_NAME(CLASS_NAME, OBJ_CLASS)
259
260
261#endif // __SIM_OBJECT_HH__
262