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.
36 #include "sim/configfile.hh"
44 // The context of a parameter definition... usually a subclass of
45 // SimObjectBuilder (which derives from ParamContext), but abstracted
46 // here to support more global simulator control parameters as well.
52 // static list of all ParamContext objects, built as a side effect
53 // of the ParamContext constructor
54 static std::list<ParamContext *> *ctxList;
58 // .ini file (database) for parameter lookup... initialized on call
62 // .ini file section for parameter lookup
63 const std::string iniSection;
65 typedef std::vector<BaseParam *> ParamList;
67 // list of parameters defined in this context
70 ParamList *getParamList() {
72 paramList = new ParamList;
78 // Second arg, if set to true, says don't put on paramContextList
79 // (i.e. don't automatically parse params). Used by derived
80 // SimObjectBuilder class, where parsing is done in
81 // SimObject::create()
82 ParamContext(const std::string &_iniSection, bool noAutoParse = false);
84 virtual ~ParamContext() {}
86 // add a parameter to the context... called from the parameter
87 // object's constructor (see BaseParam::BaseParam())
88 void addParam(BaseParam *);
90 // call parse() on all params in this context to convert string
91 // representations to parameter values
92 virtual void parseParams(IniFile &iniFile);
94 // Check parameter values for validity & consistency. Default
95 // implementation is no-op; derive subclass & override to add
96 // actual functionality here
97 virtual void checkParams();
99 // Clean up at end of execution: close file descriptors, etc.
100 // Default implementation is no-op; derive subclass & override to
101 // add actual functionality here
102 virtual void cleanup();
104 // dump parameter descriptions
105 void describeParams(std::ostream &);
107 // Display the parameters & values used
108 void showParams(std::ostream &);
110 // print context information for parameter error
111 virtual void printErrorProlog(std::ostream &);
113 // resolve a SimObject name in this context to an object pointer.
114 virtual SimObject *resolveSimObject(const std::string &name);
116 // generate the name for this instance of this context (used as a
117 // prefix to create unique names in resolveSimObject()
118 virtual const std::string &getInstanceName() { return iniSection; }
120 // return the configuration hierarchy node for this context. Bare
121 // ParamContext objects have no corresponding node, so the default
122 // implementation returns NULL.
123 virtual ConfigNode *getConfigNode() { return NULL; }
125 // Parse all parameters registered with all ParamContext objects.
126 static void parseAllContexts(IniFile &iniFile);
128 // Check all parameters registered with all ParamContext objects.
129 // (calls checkParams() on each)
130 static void checkAllContexts();
132 // Print all parameter values on indicated ostream.
133 static void showAllContexts(std::ostream &os);
135 // Clean up all registered ParamContext objects. (calls cleanup()
137 static void cleanupAllContexts();
139 // print descriptions of all parameters registered with all
140 // ParamContext objects
141 static void describeAllContexts(std::ostream &os);
146 // Base class for all parameter objects
152 ParamContext *context;
154 std::string description; // text description for help message
155 bool wasSet; // true if parameter was set by user
156 bool hasDefault; // true if parameter has default value
158 BaseParam(ParamContext *_context, const std::string &_name,
159 const std::string &_description, bool _hasDefault)
160 : context(_context), name(_name), description(_description),
161 wasSet(false), hasDefault(_hasDefault)
163 context->addParam(this);
166 virtual ~BaseParam() {}
168 // a parameter is valid only if its value was set by the user or
169 // it has a default value
172 return (wasSet || hasDefault);
175 // set value by parsing string
176 virtual void parse(const std::string &s) = 0;
178 // display value to stream
179 virtual void showValue(std::ostream &) const = 0;
181 // display type to stream
182 virtual void showType(std::ostream &) const = 0;
184 // signal parse or usage error
185 virtual void die(const std::string &err) const;
189 // Template classes to specialize parameters to specific types.
191 // Param<T> is for single-valued (scalar) parameters of type T.
192 // VectorParam<T> is for multi-valued (vector) parameters of type T.
193 // These are specified in the .ini file as a space-delimited list of
197 class Param : public BaseParam
205 // Param with default value: set value to default
206 Param(ParamContext *context,
207 const std::string &name, const std::string &description, T dfltValue)
208 : BaseParam(context, name, description, true),
213 // Param with no default value: leave value uninitialized
214 Param(ParamContext *context,
215 const std::string &name, const std::string &description)
216 : BaseParam(context, name, description, false)
224 // if we attempt to reference an invalid parameter (i.e., one
225 // with no default value that was not set by the user), die.
231 // display value to stream
232 virtual void showValue(std::ostream &os) const;
234 // display type to stream
235 virtual void showType(std::ostream &) const;
237 // set value by parsing string
238 virtual void parse(const std::string &s);
243 // Template class for vector-valued parameters (lists)
246 class VectorParam : public BaseParam
250 std::vector<T> value;
254 typedef typename std::vector<T>::size_type size_type;
256 // Param with default value: set value to default
257 VectorParam(ParamContext *context, const std::string &name,
258 const std::string &description,
259 const std::vector<T> &dfltValue)
260 : BaseParam(context, name, description, true),
265 // Param with no default value: leave value uninitialized
266 VectorParam(ParamContext *context,
267 const std::string &name, const std::string &description)
268 : BaseParam(context, name, description, false)
272 virtual ~VectorParam() {}
274 // basic vector access methods
275 size_type size() const
282 const T &operator[](size_type n) const
289 // return reference to value vector
290 operator std::vector<T>&()
297 // display value to stream
298 virtual void showValue(std::ostream &os) const;
300 // display type to stream
301 virtual void showType(std::ostream &) const;
303 // set value by parsing string
304 virtual void parse(const std::string &s);
308 // Specialization of Param<int> and VectorParam<int> to handle
309 // enumerated types is done in two ways, using SimpleEnumParam and
310 // MappedEnumParam (and their vector counterparts,
311 // SimpleEnumVectorParam and MappedEnumVectorParam). SimpleEnumParam
312 // takes an array of strings and maps them to integers based on array
313 // index. MappedEnumParam takes an array of string-to-int mappings,
314 // allowing for mapping strings to non-contiguous integer values, or
315 // mapping multiple strings to the same integer value.
317 // Both SimpleEnumParam and MappedEnumParam are implemented using a
318 // single template class, EnumParam<Map>, which takes the type of the map
319 // as a parameter (const char * or EnumParamMap). Similarly,
320 // SimpleEnumVectorParam and MappedEnumVectorParam are both
321 // implemented using EnumVectorParam<Map>.
324 class EnumParam : public Param<int>
326 const int num_values;
331 // Param with default value: set value to default
332 EnumParam(ParamContext *context,
333 const std::string &name, const std::string &description,
334 const Map *_map, int _num_values,
336 : Param<int>(context, name, description, dfltValue),
337 num_values(_num_values), map(_map)
341 // Param with no default value: leave value uninitialized
342 EnumParam(ParamContext *context,
343 const std::string &name, const std::string &description,
344 const Map *_map, int _num_values)
345 : Param<int>(context, name, description),
346 num_values(_num_values), map(_map)
350 virtual ~EnumParam() {}
352 // display value to stream
353 virtual void showValue(std::ostream &os) const;
355 // display type to stream
356 virtual void showType(std::ostream &) const;
358 // set value by parsing string
359 virtual void parse(const std::string &s);
363 // Vector counterpart to SimpleEnumParam
366 class EnumVectorParam : public VectorParam<int>
368 const int num_values;
373 // Param with default value: set value to default
374 EnumVectorParam(ParamContext *context,
375 const std::string &name, const std::string &description,
376 const Map *_map, int _num_values,
377 std::vector<int> &dfltValue)
378 : VectorParam<int>(context, name, description, dfltValue),
379 num_values(_num_values), map(_map)
383 // Param with no default value: leave value uninitialized
384 EnumVectorParam(ParamContext *context,
385 const std::string &name, const std::string &description,
386 const Map *_map, int _num_values)
387 : VectorParam<int>(context, name, description),
388 num_values(_num_values), map(_map)
392 virtual ~EnumVectorParam() {}
394 // display value to stream
395 virtual void showValue(std::ostream &os) const;
397 // display type to stream
398 virtual void showType(std::ostream &) const;
400 // set value by parsing string
401 virtual void parse(const std::string &s);
404 // Specialize EnumParam for a particular enumeration type ENUM
405 // (automates casting to get value of enum type)
407 template <class ENUM>
408 class SimpleEnumParam : public EnumParam<const char *>
412 SimpleEnumParam(ParamContext *context,
413 const std::string &name, const std::string &description,
414 const char **_map, int _num_values,
416 : EnumParam<const char *>(context, name, description,
417 _map, _num_values, (int)dfltValue)
421 SimpleEnumParam(ParamContext *context,
422 const std::string &name, const std::string &description,
423 const char **_map, int _num_values)
424 : EnumParam<const char *>(context, name, description,
429 operator ENUM() const
438 // Specialize EnumParam for a particular enumeration type ENUM
439 // (automates casting to get value of enum type)
441 template <class ENUM>
442 class SimpleEnumVectorParam : public EnumVectorParam<const char *>
446 // skip default value constructor: too much pain to convert
447 // vector<ENUM> initializer to vector<int>
450 SimpleEnumVectorParam(ParamContext *context,
451 const std::string &name,
452 const std::string &description,
453 const char **_map, int _num_values)
454 : EnumVectorParam<const char *>(context, name, description,
459 ENUM operator[](size_type n)
463 return (ENUM)value[n];
469 // Handle enums via string-to-int map (see comment above).
472 // An array of string-to-int mappings must be supplied using the
479 // Specialize EnumParam for a particular enumeration type ENUM
480 // (automates casting to get value of enum type)
482 template <class ENUM>
483 class MappedEnumParam : public EnumParam<EnumParamMap>
487 MappedEnumParam(ParamContext *context,
488 const std::string &name, const std::string &description,
489 const EnumParamMap *_map, int _num_values,
491 : EnumParam<EnumParamMap>(context, name, description,
492 _map, _num_values, (int)dfltValue)
496 MappedEnumParam(ParamContext *context,
497 const std::string &name, const std::string &description,
498 const EnumParamMap *_map, int _num_values)
499 : EnumParam<EnumParamMap>(context, name, description,
508 return (ENUM)value[n];
513 // Specialize EnumParam for a particular enumeration type ENUM
514 // (automates casting to get value of enum type)
516 template <class ENUM>
517 class MappedEnumVectorParam : public EnumVectorParam<EnumParamMap>
521 // skip default value constructor: too much pain to convert
522 // vector<ENUM> initializer to vector<int>
525 MappedEnumVectorParam(ParamContext *context,
526 const std::string &name,
527 const std::string &description,
528 const EnumParamMap *_map, int _num_values)
529 : EnumVectorParam<EnumParamMap>(context, name, description,
534 ENUM operator[](size_type n)
538 return (ENUM)value[n];
544 // Parameters that point to other simulation objects (e.g. caches,
545 // busses, etc.) are handled by specializing SimObjectBaseParam to the
546 // specific subtype. The main purpose of SimObjectBaseParam is to
547 // provide a place to stick several helper functions common to all
548 // SimObject-derived parameters.
550 class SimObjectBaseParam : public BaseParam
554 SimObjectBaseParam(ParamContext *context, const std::string &name,
555 const std::string &description, bool hasDefault)
556 : BaseParam(context, name, description, hasDefault)
560 virtual ~SimObjectBaseParam() {}
562 // helper function for SimObjectParam<T>::showValue()
563 void showValue(std::ostream &os, SimObject *obj) const;
565 // helper function for SimObjectParam<T>::parse()
566 void parse(const std::string &s, SimObject *&value);
568 // helper function for SimObjectParam<T>::parse()
569 void parse(const std::string &s, std::vector<SimObject *>&value_vec);
574 // Parameter to a specific type of SimObject. Note that T must be a
575 // pointer to a class derived from SimObject (e.g., <CPU *>).
578 template <class T> class SimObjectParam;
581 class SimObjectParam<T *> : public SimObjectBaseParam
589 // initialization w/o default
590 SimObjectParam(ParamContext *context,
591 const std::string &name, const std::string &description)
592 : SimObjectBaseParam(context, name, description, false)
596 // initialization wit=h default
597 SimObjectParam(ParamContext *context,
598 const std::string &name, const std::string &description,
600 : SimObjectBaseParam(context, name, description, true),
605 virtual ~SimObjectParam() {}
607 // convert to pointer
615 T *operator->() const
622 // display value to stream
623 virtual void showValue(std::ostream &os) const
625 SimObjectBaseParam::showValue(os, value);
628 // display type to stream: see REGISTER_SIM_OBJECT macro in
629 // sim_object.hh for declaration
630 virtual void showType(std::ostream &os) const;
632 // set value by parsing string
633 virtual void parse(const std::string &s)
636 // first parse to generic SimObject *
637 SimObjectBaseParam::parse(s, so_ptr);
638 // now dynamic_cast to specific derived type
639 value = dynamic_cast<T *>(so_ptr);
640 // check for failure of dynamic_cast
641 if (value == NULL && so_ptr != NULL)
642 die("not of appropriate type");
648 // Vector counterpart to SimObjectParam<T>
651 template <class T> class SimObjectVectorParam;
654 class SimObjectVectorParam<T *> : public SimObjectBaseParam
658 std::vector<T *> value;
662 typedef typename std::vector<T *>::size_type size_type;
664 SimObjectVectorParam(ParamContext *context,
665 const std::string &name,
666 const std::string &description)
667 : SimObjectBaseParam(context, name, description, false)
671 SimObjectVectorParam(ParamContext *context,
672 const std::string &name,
673 const std::string &description,
674 std::vector<T *> dfltValue)
675 : SimObjectBaseParam(context, name, description, true),
680 virtual ~SimObjectVectorParam() {}
682 // basic vector access methods
683 size_type size() const
690 T *&operator[](size_type n)
697 // return reference to value vector
698 operator std::vector<T *>&()
705 // display value to stream
706 virtual void showValue(std::ostream &os) const
708 for (int i = 0; i < value.size(); i++) {
711 SimObjectBaseParam::showValue(os, value[i]);
715 // display type to stream: see
716 virtual void showType(std::ostream &os) const;
718 // set value by parsing string
719 virtual void parse(const std::string &s)
721 std::vector<SimObject *> so_ptr_vec;
722 // first parse to generic SimObject * vector (from SimObjectBaseParam)
723 SimObjectBaseParam::parse(s, so_ptr_vec);
725 value.resize(so_ptr_vec.size());
727 for (int i = 0; i < so_ptr_vec.size(); ++i) {
728 // now dynamic_cast to specific derived type
729 value[i] = dynamic_cast<T *>(so_ptr_vec[i]);
730 // check for failure of dynamic_cast
731 if (value[i] == NULL && so_ptr_vec[i] != NULL)
732 die("not of appropriate type");
738 // Macro to define showType() methods for SimObjectParam &
739 // SimObjectVectorParam. Can't do this automatically as it requires a
740 // string name for the type, which you can't get from a template
741 // argument. For concrete derived SimObject types, this macro is
742 // automatically invoked by REGISTER_SIM_OBJECT() (see sim_object.hh).
744 #define DEFINE_SIM_OBJECT_CLASS_NAME(CLASS_NAME, OBJ_CLASS) \
746 SimObjectParam<OBJ_CLASS *>::showType(std::ostream &os) const \
752 SimObjectVectorParam<OBJ_CLASS *>::showType(std::ostream &os) const \
754 os << "vector of " << CLASS_NAME; \