2 * Copyright (c) 2003 The Regents of The University of Michigan
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.
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.
29 #ifndef __BUILDER_HH__
30 #define __BUILDER_HH__
37 #include "sim/param.hh"
42 // A SimObjectBuilder serves as an evaluation context for a set of
43 // parameters that describe a specific instance of a SimObject. This
44 // evaluation context corresponds to a section in the .ini file (as
45 // with the base ParamContext) plus an optional node in the
46 // configuration hierarchy (the configNode member) for resolving
47 // SimObject references. SimObjectBuilder is an abstract superclass;
48 // derived classes specialize the class for particular subclasses of
49 // SimObject (e.g., BaseCache).
51 // For typical usage, see the definition of
52 // SimObjectClass::createObject().
54 class SimObjectBuilder : public ParamContext
57 // name of the instance we are creating
58 std::string instanceName;
60 // The corresponding node in the configuration hierarchy.
61 // (optional: may be null if the created object is not in the
63 ConfigNode *configNode;
65 // The external SimObject class name (for error messages)
66 std::string simObjClassName;
69 SimObjectBuilder(const std::string &_configClass,
70 const std::string &_instanceName,
71 ConfigNode *_configNode,
72 const std::string &_simObjClassName)
73 : ParamContext(_configClass, true),
74 instanceName(_instanceName),
75 configNode(_configNode),
76 simObjClassName(_simObjClassName)
80 virtual ~SimObjectBuilder() {}
82 // call parse() on all params in this context to convert string
83 // representations to parameter values
84 virtual void parseParams(IniFile &iniFile);
86 // parameter error prolog (override of ParamContext)
87 virtual void printErrorProlog(std::ostream &);
89 // generate the name for this SimObject instance (derived from the
90 // configuration hierarchy node label and position)
91 virtual const std::string &getInstanceName() { return instanceName; }
93 // return the configuration hierarchy node for this context.
94 virtual ConfigNode *getConfigNode() { return configNode; }
96 // Create the actual SimObject corresponding to the parameter
97 // values in this context. This function is overridden in derived
98 // classes to call a specific constructor for a particular
99 // subclass of SimObject.
100 virtual SimObject *create() = 0;
105 // Handy macros for initializing parameter members of classes derived
106 // from SimObjectBuilder. Assumes that the name of the parameter
107 // member object is the same as the textual parameter name seen by the
108 // user. (Note that '#p' is expanded by the preprocessor to '"p"'.)
110 #define INIT_PARAM(p, desc) p(this, #p, desc)
111 #define INIT_PARAM_DFLT(p, desc, dflt) p(this, #p, desc, dflt)
114 // Initialize an enumeration variable... assumes that 'map' is the
115 // name of an array of mappings (char * for SimpleEnumParam, or
116 // EnumParamMap for MappedEnumParam).
118 #define INIT_ENUM_PARAM(p, desc, map) \
119 p(this, #p, desc, map, sizeof(map)/sizeof(map[0]))
120 #define INIT_ENUM_PARAM_DFLT(p, desc, map, dflt) \
121 p(this, #p, desc, map, sizeof(map)/sizeof(map[0]), dflt)
124 // An instance of SimObjectClass corresponds to a class derived from
125 // SimObject. The SimObjectClass instance serves to bind the string
126 // name (found in the config file) to a function that creates an
127 // instance of the appropriate derived class.
129 // This would be much cleaner in Smalltalk or Objective-C, where types
130 // are first-class objects themselves.
135 // Type CreateFunc is a pointer to a function that creates a new
136 // simulation object builder based on a .ini-file parameter
137 // section (specified by the first string argument), a unique name
138 // for the object (specified by the second string argument), and
139 // an optional config hierarchy node (specified by the third
140 // argument). A pointer to the new SimObjectBuilder is returned.
141 typedef SimObjectBuilder *(*CreateFunc)(const std::string &configClassName,
142 const std::string &objName,
143 ConfigNode *configNode,
144 const std::string &simObjClassName);
146 static std::map<std::string,CreateFunc> *classMap;
148 // Constructor. For example:
150 // SimObjectClass baseCacheClass("BaseCache", newBaseCacheBuilder);
152 SimObjectClass(const std::string &className, CreateFunc createFunc);
154 // create SimObject given name of class and pointer to
155 // configuration hierarchy node
156 static SimObject *createObject(IniFile &configDB,
157 const std::string &configClassName,
158 const std::string &objName,
159 ConfigNode *configNode);
161 // print descriptions of all parameters registered with all
163 static void describeAllClasses(std::ostream &os);
167 // Macros to encapsulate the magic of declaring & defining
168 // SimObjectBuilder and SimObjectClass objects
171 #define BEGIN_DECLARE_SIM_OBJECT_PARAMS(OBJ_CLASS) \
172 class OBJ_CLASS##Builder : public SimObjectBuilder \
176 #define END_DECLARE_SIM_OBJECT_PARAMS(OBJ_CLASS) \
178 OBJ_CLASS##Builder(const std::string &configClass, \
179 const std::string &instanceName, \
180 ConfigNode *configNode, \
181 const std::string &simObjClassName); \
182 virtual ~OBJ_CLASS##Builder() {} \
184 OBJ_CLASS *create(); \
187 #define BEGIN_INIT_SIM_OBJECT_PARAMS(OBJ_CLASS) \
188 OBJ_CLASS##Builder::OBJ_CLASS##Builder(const std::string &configClass, \
189 const std::string &instanceName, \
190 ConfigNode *configNode, \
191 const std::string &simObjClassName) \
192 : SimObjectBuilder(configClass, instanceName, \
193 configNode, simObjClassName),
196 #define END_INIT_SIM_OBJECT_PARAMS(OBJ_CLASS) \
200 #define CREATE_SIM_OBJECT(OBJ_CLASS) \
201 OBJ_CLASS *OBJ_CLASS##Builder::create()
203 #define REGISTER_SIM_OBJECT(CLASS_NAME, OBJ_CLASS) \
205 new##OBJ_CLASS##Builder(const std::string &configClass, \
206 const std::string &instanceName, \
207 ConfigNode *configNode, \
208 const std::string &simObjClassName) \
210 return new OBJ_CLASS##Builder(configClass, instanceName, \
211 configNode, simObjClassName); \
214 SimObjectClass the##OBJ_CLASS##Class(CLASS_NAME, \
215 new##OBJ_CLASS##Builder); \
218 DEFINE_SIM_OBJECT_CLASS_NAME(CLASS_NAME, OBJ_CLASS)
221 #endif // __BUILDER_HH__