2 * Copyright (c) 2003-2005 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.
28 * Authors: Nathan Binkert
31 #ifndef __BUILDER_HH__
32 #define __BUILDER_HH__
39 #include "sim/param.hh"
44 // A SimObjectBuilder serves as an evaluation context for a set of
45 // parameters that describe a specific instance of a SimObject. This
46 // evaluation context corresponds to a section in the .ini file (as
47 // with the base ParamContext) plus an optional node in the
48 // configuration hierarchy (the configNode member) for resolving
49 // SimObject references. SimObjectBuilder is an abstract superclass;
50 // derived classes specialize the class for particular subclasses of
51 // SimObject (e.g., BaseCache).
53 // For typical usage, see the definition of
54 // SimObjectClass::createObject().
56 class SimObjectBuilder : public ParamContext
59 SimObjectBuilder(const std::string &_iniSection);
61 virtual ~SimObjectBuilder();
63 // call parse() on all params in this context to convert string
64 // representations to parameter values
65 virtual void parseParams(IniFile &iniFile);
67 // parameter error prolog (override of ParamContext)
68 virtual void printErrorProlog(std::ostream &);
70 // generate the name for this SimObject instance (derived from the
71 // configuration hierarchy node label and position)
72 virtual const std::string &getInstanceName() { return iniSection; }
74 // Create the actual SimObject corresponding to the parameter
75 // values in this context. This function is overridden in derived
76 // classes to call a specific constructor for a particular
77 // subclass of SimObject.
78 virtual SimObject *create() = 0;
83 // Handy macros for initializing parameter members of classes derived
84 // from SimObjectBuilder. Assumes that the name of the parameter
85 // member object is the same as the textual parameter name seen by the
86 // user. (Note that '#p' is expanded by the preprocessor to '"p"'.)
88 #define INIT_PARAM(p, desc) p(this, #p, desc)
89 #define INIT_PARAM_DFLT(p, desc, dflt) p(this, #p, desc, dflt)
92 // Initialize an enumeration variable... assumes that 'map' is the
93 // name of an array of mappings (char * for SimpleEnumParam, or
94 // EnumParamMap for MappedEnumParam).
96 #define INIT_ENUM_PARAM(p, desc, map) \
97 p(this, #p, desc, map, sizeof(map)/sizeof(map[0]))
98 #define INIT_ENUM_PARAM_DFLT(p, desc, map, dflt) \
99 p(this, #p, desc, map, sizeof(map)/sizeof(map[0]), dflt)
102 // An instance of SimObjectClass corresponds to a class derived from
103 // SimObject. The SimObjectClass instance serves to bind the string
104 // name (found in the config file) to a function that creates an
105 // instance of the appropriate derived class.
107 // This would be much cleaner in Smalltalk or Objective-C, where types
108 // are first-class objects themselves.
113 // Type CreateFunc is a pointer to a function that creates a new
114 // simulation object builder based on a .ini-file parameter
115 // section (specified by the first string argument), a unique name
116 // for the object (specified by the second string argument), and
117 // an optional config hierarchy node (specified by the third
118 // argument). A pointer to the new SimObjectBuilder is returned.
119 typedef SimObjectBuilder *(*CreateFunc)(const std::string &iniSection);
121 static std::map<std::string,CreateFunc> *classMap;
123 // Constructor. For example:
125 // SimObjectClass baseCacheClass("BaseCache", newBaseCacheBuilder);
127 SimObjectClass(const std::string &className, CreateFunc createFunc);
129 // create SimObject given name of class and pointer to
130 // configuration hierarchy node
131 static SimObject *createObject(IniFile &configDB,
132 const std::string &iniSection);
134 // print descriptions of all parameters registered with all
136 static void describeAllClasses(std::ostream &os);
140 // Macros to encapsulate the magic of declaring & defining
141 // SimObjectBuilder and SimObjectClass objects
144 #define BEGIN_DECLARE_SIM_OBJECT_PARAMS(OBJ_CLASS) \
145 class OBJ_CLASS##Builder : public SimObjectBuilder \
149 #define END_DECLARE_SIM_OBJECT_PARAMS(OBJ_CLASS) \
151 OBJ_CLASS##Builder(const std::string &iniSection); \
152 virtual ~OBJ_CLASS##Builder() {} \
154 OBJ_CLASS *create(); \
157 #define BEGIN_INIT_SIM_OBJECT_PARAMS(OBJ_CLASS) \
158 OBJ_CLASS##Builder::OBJ_CLASS##Builder(const std::string &iSec) \
159 : SimObjectBuilder(iSec),
162 #define END_INIT_SIM_OBJECT_PARAMS(OBJ_CLASS) \
166 #define CREATE_SIM_OBJECT(OBJ_CLASS) \
167 OBJ_CLASS *OBJ_CLASS##Builder::create()
169 #define REGISTER_SIM_OBJECT(CLASS_NAME, OBJ_CLASS) \
171 new##OBJ_CLASS##Builder(const std::string &iniSection) \
173 return new OBJ_CLASS##Builder(iniSection); \
176 SimObjectClass the##OBJ_CLASS##Class(CLASS_NAME, \
177 new##OBJ_CLASS##Builder); \
180 DEFINE_SIM_OBJECT_CLASS_NAME(CLASS_NAME, OBJ_CLASS)
182 /* Macros that use the namespace for sinic... yuk. */
183 #define BEGIN_DECLARE_SIM_OBJECT_PARAMS_WNS(NAME_SPACE, OBJ_CLASS) \
184 class NAME_SPACE##OBJ_CLASS##Builder : public SimObjectBuilder \
188 #define END_DECLARE_SIM_OBJECT_PARAMS_WNS(NAME_SPACE, OBJ_CLASS) \
190 NAME_SPACE##OBJ_CLASS##Builder(const std::string &iniSection); \
191 virtual ~NAME_SPACE##OBJ_CLASS##Builder() {} \
193 NAME_SPACE::OBJ_CLASS *create(); \
196 #define BEGIN_INIT_SIM_OBJECT_PARAMS_WNS(NAME_SPACE, OBJ_CLASS) \
197 NAME_SPACE::OBJ_CLASS##Builder::OBJ_CLASS##Builder(const std::string &iSec) \
198 : SimObjectBuilder(iSec),
201 #define END_INIT_SIM_OBJECT_PARAMS_WNS(NAME_SPACE, OBJ_CLASS) \
205 #define CREATE_SIM_OBJECT_WNS(NAME_SPACE, OBJ_CLASS) \
206 NAME_SPACE::OBJ_CLASS *NAME_SPACE##OBJ_CLASS##Builder::create()
208 #define REGISTER_SIM_OBJECT_WNS(NAME_SPACE, CLASS_NAME, OBJ_CLASS) \
210 new##NAME_SPACEi##OBJ_CLASS##Builder(const std::string &iniSection) \
212 return new NAME_SPACE##OBJ_CLASS##Builder(iniSection); \
215 SimObjectClass the##NAME_SPACE##OBJ_CLASS##Class(CLASS_NAME, \
216 new##NAME_SPACE##OBJ_CLASS##Builder); \
219 DEFINE_SIM_OBJECT_CLASS_NAME(CLASS_NAME, NAME_SPACE##OBJ_CLASS)
223 #endif // __BUILDER_HH__