2 * Copyright (c) 2002-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 __SIM_PARAM_HH__
30 #define __SIM_PARAM_HH__
37 #include "sim/configfile.hh"
38 #include "sim/startup.hh"
45 // The context of a parameter definition... usually a subclass of
46 // SimObjectBuilder (which derives from ParamContext), but abstracted
47 // here to support more global simulator control parameters as well.
49 class ParamContext : protected StartupCallback
53 // static list of all ParamContext objects, built as a side effect
54 // of the ParamContext constructor
55 static std::list<ParamContext *> *ctxList;
59 // .ini file (database) for parameter lookup... initialized on call
63 // .ini file section for parameter lookup
64 const std::string iniSection;
66 typedef std::vector<BaseParam *> ParamList;
68 // list of parameters defined in this context
71 ParamList *getParamList() {
73 paramList = new ParamList;
79 /// Initialization phases for ParamContext objects.
81 NoAutoInit = -1, ///< Don't initialize at all... params
82 /// will be parsed later (used by
83 /// SimObjectBuilder, which parses
84 /// params in SimObject::create().
85 OutputInitPhase = 0, ///< Output stream initialization
86 TraceInitPhase = 1, ///< Trace context initialization:
87 /// depends on output streams, but
88 /// needs to come before others so we
89 /// can use tracing in other
90 /// ParamContext init code
91 StatsInitPhase = 2, ///< Stats output initialization
92 DefaultInitPhase = 3 ///< Everything else
95 /// Records the initialization phase for this ParamContext.
99 /// @param _iniSection Name of .ini section corresponding to this context.
100 /// @param _initPhase Initialization phase (see InitPhase).
101 ParamContext(const std::string &_iniSection,
102 InitPhase _initPhase = DefaultInitPhase);
104 virtual ~ParamContext() {}
106 // add a parameter to the context... called from the parameter
107 // object's constructor (see BaseParam::BaseParam())
108 void addParam(BaseParam *);
110 // call parse() on all params in this context to convert string
111 // representations to parameter values
112 virtual void parseParams(IniFile &iniFile);
114 // Check parameter values for validity & consistency. Default
115 // implementation is no-op; derive subclass & override to add
116 // actual functionality here
117 virtual void checkParams();
119 // Clean up at end of execution: close file descriptors, etc.
120 // Default implementation is no-op; derive subclass & override to
121 // add actual functionality here
122 virtual void cleanup();
124 // dump parameter descriptions
125 void describeParams(std::ostream &);
127 // Display the parameters & values used
128 void showParams(std::ostream &);
130 // print context information for parameter error
131 virtual void printErrorProlog(std::ostream &);
133 // resolve a SimObject name in this context to an object pointer.
134 virtual SimObject *resolveSimObject(const std::string &name);
136 // generate the name for this instance of this context (used as a
137 // prefix to create unique names in resolveSimObject()
138 virtual const std::string &getInstanceName() { return iniSection; }
140 // return the configuration hierarchy node for this context. Bare
141 // ParamContext objects have no corresponding node, so the default
142 // implementation returns NULL.
143 virtual ConfigNode *getConfigNode() { return NULL; }
145 // Parse all parameters registered with all ParamContext objects.
146 static void parseAllContexts(IniFile &iniFile);
148 // Check all parameters registered with all ParamContext objects.
149 // (calls checkParams() on each)
150 static void checkAllContexts();
152 // Print all parameter values on indicated ostream.
153 static void showAllContexts(std::ostream &os);
155 // Clean up all registered ParamContext objects. (calls cleanup()
157 static void cleanupAllContexts();
159 // print descriptions of all parameters registered with all
160 // ParamContext objects
161 static void describeAllContexts(std::ostream &os);
166 // Base class for all parameter objects
172 ParamContext *context;
174 std::string description; // text description for help message
175 bool wasSet; // true if parameter was set by user
176 bool hasDefault; // true if parameter has default value
178 BaseParam(ParamContext *_context, const std::string &_name,
179 const std::string &_description, bool _hasDefault)
180 : context(_context), name(_name), description(_description),
181 wasSet(false), hasDefault(_hasDefault)
183 context->addParam(this);
186 virtual ~BaseParam() {}
188 // a parameter is valid only if its value was set by the user or
189 // it has a default value
192 return (wasSet || hasDefault);
195 // set value by parsing string
196 virtual void parse(const std::string &s) = 0;
198 // display value to stream
199 virtual void showValue(std::ostream &) const = 0;
201 // display type to stream
202 virtual void showType(std::ostream &) const = 0;
204 // signal parse or usage error
205 virtual void die(const std::string &err) const;
209 // Template classes to specialize parameters to specific types.
211 // Param<T> is for single-valued (scalar) parameters of type T.
212 // VectorParam<T> is for multi-valued (vector) parameters of type T.
213 // These are specified in the .ini file as a space-delimited list of
217 class Param : public BaseParam
225 // Param with default value: set value to default
226 Param(ParamContext *context,
227 const std::string &name, const std::string &description, T dfltValue)
228 : BaseParam(context, name, description, true),
233 // Param with no default value: leave value uninitialized
234 Param(ParamContext *context,
235 const std::string &name, const std::string &description)
236 : BaseParam(context, name, description, false)
244 // if we attempt to reference an invalid parameter (i.e., one
245 // with no default value that was not set by the user), die.
251 // display value to stream
252 virtual void showValue(std::ostream &os) const;
254 // display type to stream
255 virtual void showType(std::ostream &) const;
257 // set value by parsing string
258 virtual void parse(const std::string &s);
263 // Template class for vector-valued parameters (lists)
266 class VectorParam : public BaseParam
270 std::vector<T> value;
274 typedef typename std::vector<T>::size_type size_type;
276 // Param with default value: set value to default
277 VectorParam(ParamContext *context, const std::string &name,
278 const std::string &description,
279 const std::vector<T> &dfltValue)
280 : BaseParam(context, name, description, true),
285 // Param with no default value: leave value uninitialized
286 VectorParam(ParamContext *context,
287 const std::string &name, const std::string &description)
288 : BaseParam(context, name, description, false)
292 virtual ~VectorParam() {}
294 // basic vector access methods
295 size_type size() const
302 const T &operator[](size_type n) const
309 // return reference to value vector
310 operator std::vector<T>&()
317 // display value to stream
318 virtual void showValue(std::ostream &os) const;
320 // display type to stream
321 virtual void showType(std::ostream &) const;
323 // set value by parsing string
324 virtual void parse(const std::string &s);
328 // Specialization of Param<int> and VectorParam<int> to handle
329 // enumerated types is done in two ways, using SimpleEnumParam and
330 // MappedEnumParam (and their vector counterparts,
331 // SimpleEnumVectorParam and MappedEnumVectorParam). SimpleEnumParam
332 // takes an array of strings and maps them to integers based on array
333 // index. MappedEnumParam takes an array of string-to-int mappings,
334 // allowing for mapping strings to non-contiguous integer values, or
335 // mapping multiple strings to the same integer value.
337 // Both SimpleEnumParam and MappedEnumParam are implemented using a
338 // single template class, EnumParam<Map>, which takes the type of the map
339 // as a parameter (const char * or EnumParamMap). Similarly,
340 // SimpleEnumVectorParam and MappedEnumVectorParam are both
341 // implemented using EnumVectorParam<Map>.
344 class EnumParam : public Param<int>
346 const int num_values;
351 // Param with default value: set value to default
352 EnumParam(ParamContext *context,
353 const std::string &name, const std::string &description,
354 const Map *_map, int _num_values,
356 : Param<int>(context, name, description, dfltValue),
357 num_values(_num_values), map(_map)
361 // Param with no default value: leave value uninitialized
362 EnumParam(ParamContext *context,
363 const std::string &name, const std::string &description,
364 const Map *_map, int _num_values)
365 : Param<int>(context, name, description),
366 num_values(_num_values), map(_map)
370 virtual ~EnumParam() {}
372 // display value to stream
373 virtual void showValue(std::ostream &os) const;
375 // display type to stream
376 virtual void showType(std::ostream &) const;
378 // set value by parsing string
379 virtual void parse(const std::string &s);
383 // Vector counterpart to SimpleEnumParam
386 class EnumVectorParam : public VectorParam<int>
388 const int num_values;
393 // Param with default value: set value to default
394 EnumVectorParam(ParamContext *context,
395 const std::string &name, const std::string &description,
396 const Map *_map, int _num_values,
397 std::vector<int> &dfltValue)
398 : VectorParam<int>(context, name, description, dfltValue),
399 num_values(_num_values), map(_map)
403 // Param with no default value: leave value uninitialized
404 EnumVectorParam(ParamContext *context,
405 const std::string &name, const std::string &description,
406 const Map *_map, int _num_values)
407 : VectorParam<int>(context, name, description),
408 num_values(_num_values), map(_map)
412 virtual ~EnumVectorParam() {}
414 // display value to stream
415 virtual void showValue(std::ostream &os) const;
417 // display type to stream
418 virtual void showType(std::ostream &) const;
420 // set value by parsing string
421 virtual void parse(const std::string &s);
424 // Specialize EnumParam for a particular enumeration type ENUM
425 // (automates casting to get value of enum type)
427 template <class ENUM>
428 class SimpleEnumParam : public EnumParam<const char *>
432 SimpleEnumParam(ParamContext *context,
433 const std::string &name, const std::string &description,
434 const char **_map, int _num_values,
436 : EnumParam<const char *>(context, name, description,
437 _map, _num_values, (int)dfltValue)
441 SimpleEnumParam(ParamContext *context,
442 const std::string &name, const std::string &description,
443 const char **_map, int _num_values)
444 : EnumParam<const char *>(context, name, description,
449 operator ENUM() const
458 // Specialize EnumParam for a particular enumeration type ENUM
459 // (automates casting to get value of enum type)
461 template <class ENUM>
462 class SimpleEnumVectorParam : public EnumVectorParam<const char *>
466 // skip default value constructor: too much pain to convert
467 // vector<ENUM> initializer to vector<int>
470 SimpleEnumVectorParam(ParamContext *context,
471 const std::string &name,
472 const std::string &description,
473 const char **_map, int _num_values)
474 : EnumVectorParam<const char *>(context, name, description,
479 ENUM operator[](size_type n)
483 return (ENUM)value[n];
489 // Handle enums via string-to-int map (see comment above).
492 // An array of string-to-int mappings must be supplied using the
499 // Specialize EnumParam for a particular enumeration type ENUM
500 // (automates casting to get value of enum type)
502 template <class ENUM>
503 class MappedEnumParam : public EnumParam<EnumParamMap>
507 MappedEnumParam(ParamContext *context,
508 const std::string &name, const std::string &description,
509 const EnumParamMap *_map, int _num_values,
511 : EnumParam<EnumParamMap>(context, name, description,
512 _map, _num_values, (int)dfltValue)
516 MappedEnumParam(ParamContext *context,
517 const std::string &name, const std::string &description,
518 const EnumParamMap *_map, int _num_values)
519 : EnumParam<EnumParamMap>(context, name, description,
528 return (ENUM)value[this->n];
533 // Specialize EnumParam for a particular enumeration type ENUM
534 // (automates casting to get value of enum type)
536 template <class ENUM>
537 class MappedEnumVectorParam : public EnumVectorParam<EnumParamMap>
541 // skip default value constructor: too much pain to convert
542 // vector<ENUM> initializer to vector<int>
545 MappedEnumVectorParam(ParamContext *context,
546 const std::string &name,
547 const std::string &description,
548 const EnumParamMap *_map, int _num_values)
549 : EnumVectorParam<EnumParamMap>(context, name, description,
554 ENUM operator[](size_type n)
558 return (ENUM)value[n];
564 // Parameters that point to other simulation objects (e.g. caches,
565 // busses, etc.) are handled by specializing SimObjectBaseParam to the
566 // specific subtype. The main purpose of SimObjectBaseParam is to
567 // provide a place to stick several helper functions common to all
568 // SimObject-derived parameters.
570 class SimObjectBaseParam : public BaseParam
574 SimObjectBaseParam(ParamContext *context, const std::string &name,
575 const std::string &description, bool hasDefault)
576 : BaseParam(context, name, description, hasDefault)
580 virtual ~SimObjectBaseParam() {}
582 // helper function for SimObjectParam<T>::showValue()
583 void showValue(std::ostream &os, SimObject *obj) const;
585 // helper function for SimObjectParam<T>::parse()
586 void parse(const std::string &s, SimObject *&value);
588 // helper function for SimObjectParam<T>::parse()
589 void parse(const std::string &s, std::vector<SimObject *>&value_vec);
594 // Parameter to a specific type of SimObject. Note that T must be a
595 // pointer to a class derived from SimObject (e.g., <CPU *>).
598 template <class T> class SimObjectParam;
601 class SimObjectParam<T *> : public SimObjectBaseParam
609 // initialization w/o default
610 SimObjectParam(ParamContext *context,
611 const std::string &name, const std::string &description)
612 : SimObjectBaseParam(context, name, description, false)
616 // initialization wit=h default
617 SimObjectParam(ParamContext *context,
618 const std::string &name, const std::string &description,
620 : SimObjectBaseParam(context, name, description, true),
625 virtual ~SimObjectParam() {}
627 // convert to pointer
635 T *operator->() const
642 // display value to stream
643 virtual void showValue(std::ostream &os) const
645 SimObjectBaseParam::showValue(os, value);
648 // display type to stream: see REGISTER_SIM_OBJECT macro in
649 // sim_object.hh for declaration
650 virtual void showType(std::ostream &os) const;
652 // set value by parsing string
653 virtual void parse(const std::string &s)
656 // first parse to generic SimObject *
657 SimObjectBaseParam::parse(s, so_ptr);
658 // now dynamic_cast to specific derived type
659 value = dynamic_cast<T *>(so_ptr);
660 // check for failure of dynamic_cast
661 if (value == NULL && so_ptr != NULL)
662 die("not of appropriate type");
668 // Vector counterpart to SimObjectParam<T>
671 template <class T> class SimObjectVectorParam;
674 class SimObjectVectorParam<T *> : public SimObjectBaseParam
678 std::vector<T *> value;
682 typedef typename std::vector<T *>::size_type size_type;
684 SimObjectVectorParam(ParamContext *context,
685 const std::string &name,
686 const std::string &description)
687 : SimObjectBaseParam(context, name, description, false)
691 SimObjectVectorParam(ParamContext *context,
692 const std::string &name,
693 const std::string &description,
694 std::vector<T *> dfltValue)
695 : SimObjectBaseParam(context, name, description, true),
700 virtual ~SimObjectVectorParam() {}
702 // basic vector access methods
703 size_type size() const
710 T *&operator[](size_type n)
717 // return reference to value vector
718 operator std::vector<T *>&()
725 // display value to stream
726 virtual void showValue(std::ostream &os) const
728 for (int i = 0; i < value.size(); i++) {
731 SimObjectBaseParam::showValue(os, value[i]);
735 // display type to stream: see
736 virtual void showType(std::ostream &os) const;
738 // set value by parsing string
739 virtual void parse(const std::string &s)
741 std::vector<SimObject *> so_ptr_vec;
742 // first parse to generic SimObject * vector (from SimObjectBaseParam)
743 SimObjectBaseParam::parse(s, so_ptr_vec);
745 value.resize(so_ptr_vec.size());
747 for (int i = 0; i < so_ptr_vec.size(); ++i) {
748 // now dynamic_cast to specific derived type
749 value[i] = dynamic_cast<T *>(so_ptr_vec[i]);
750 // check for failure of dynamic_cast
751 if (value[i] == NULL && so_ptr_vec[i] != NULL)
752 die("not of appropriate type");
758 // Macro to define showType() methods for SimObjectParam &
759 // SimObjectVectorParam. Can't do this automatically as it requires a
760 // string name for the type, which you can't get from a template
761 // argument. For concrete derived SimObject types, this macro is
762 // automatically invoked by REGISTER_SIM_OBJECT() (see sim_object.hh).
764 #define DEFINE_SIM_OBJECT_CLASS_NAME(CLASS_NAME, OBJ_CLASS) \
766 SimObjectParam<OBJ_CLASS *>::showType(std::ostream &os) const \
772 SimObjectVectorParam<OBJ_CLASS *>::showType(std::ostream &os) const \
774 os << "vector of " << CLASS_NAME; \
779 // Declarations for low-level parsing & displaying functions. These
780 // are used internally, but should not be used directly by clients of
781 // the parameter mechanism, but are declared here so they can be
782 // shared with the serialization code (see sim/serialize.cc).
783 template <class T> bool parseParam(const std::string &str, T &data);
784 template <class T> void showParam(std::ostream &os, const T &data);
786 #endif // _SIM_PARAM_HH_