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.
36 #include "sim/configfile.hh"
43 // The context of a parameter definition... usually a subclass of
44 // SimObjectBuilder (which derives from ParamContext), but abstracted
45 // here to support more global simulator control parameters as well.
51 // static list of all ParamContext objects, built as a side effect
52 // of the ParamContext constructor
53 static std::list<ParamContext *> *ctxList;
57 // .ini file (database) for parameter lookup... initialized on call
61 // .ini file section for parameter lookup
62 const std::string iniSection;
64 typedef std::vector<BaseParam *> ParamList;
66 // list of parameters defined in this context
69 ParamList *getParamList() {
71 paramList = new ParamList;
77 /// Initialization phases for ParamContext objects.
79 NoAutoInit = -1, ///< Don't initialize at all... params
80 /// will be parsed later (used by
81 /// SimObjectBuilder, which parses
82 /// params in SimObject::create().
83 OutputInitPhase = 0, ///< Output stream initialization
84 TraceInitPhase = 1, ///< Trace context initialization:
85 /// depends on output streams, but
86 /// needs to come before others so we
87 /// can use tracing in other
88 /// ParamContext init code
89 StatsInitPhase = 2, ///< Stats output initialization
90 DefaultInitPhase = 3 ///< Everything else
93 /// Records the initialization phase for this ParamContext.
97 /// @param _iniSection Name of .ini section corresponding to this context.
98 /// @param _initPhase Initialization phase (see InitPhase).
99 ParamContext(const std::string &_iniSection,
100 InitPhase _initPhase = DefaultInitPhase);
102 virtual ~ParamContext() {}
104 // add a parameter to the context... called from the parameter
105 // object's constructor (see BaseParam::BaseParam())
106 void addParam(BaseParam *);
108 // call parse() on all params in this context to convert string
109 // representations to parameter values
110 virtual void parseParams(IniFile &iniFile);
112 // Check parameter values for validity & consistency. Default
113 // implementation is no-op; derive subclass & override to add
114 // actual functionality here
115 virtual void checkParams();
117 // Clean up at end of execution: close file descriptors, etc.
118 // Default implementation is no-op; derive subclass & override to
119 // add actual functionality here
120 virtual void cleanup();
122 // dump parameter descriptions
123 void describeParams(std::ostream &);
125 // Display the parameters & values used
126 void showParams(std::ostream &);
128 // print context information for parameter error
129 virtual void printErrorProlog(std::ostream &);
131 // resolve a SimObject name in this context to an object pointer.
132 virtual SimObject *resolveSimObject(const std::string &name);
134 // generate the name for this instance of this context (used as a
135 // prefix to create unique names in resolveSimObject()
136 virtual const std::string &getInstanceName() { return iniSection; }
138 // return the configuration hierarchy node for this context. Bare
139 // ParamContext objects have no corresponding node, so the default
140 // implementation returns NULL.
141 virtual ConfigNode *getConfigNode() { return NULL; }
143 // Parse all parameters registered with all ParamContext objects.
144 static void parseAllContexts(IniFile &iniFile);
146 // Check all parameters registered with all ParamContext objects.
147 // (calls checkParams() on each)
148 static void checkAllContexts();
150 // Print all parameter values on indicated ostream.
151 static void showAllContexts(std::ostream &os);
153 // Clean up all registered ParamContext objects. (calls cleanup()
155 static void cleanupAllContexts();
157 // print descriptions of all parameters registered with all
158 // ParamContext objects
159 static void describeAllContexts(std::ostream &os);
164 // Base class for all parameter objects
170 ParamContext *context;
172 std::string description; // text description for help message
173 bool wasSet; // true if parameter was set by user
174 bool hasDefault; // true if parameter has default value
176 BaseParam(ParamContext *_context, const std::string &_name,
177 const std::string &_description, bool _hasDefault)
178 : context(_context), name(_name), description(_description),
179 wasSet(false), hasDefault(_hasDefault)
181 context->addParam(this);
184 virtual ~BaseParam() {}
186 // a parameter is valid only if its value was set by the user or
187 // it has a default value
190 return (wasSet || hasDefault);
193 // set value by parsing string
194 virtual void parse(const std::string &s) = 0;
196 // display value to stream
197 virtual void showValue(std::ostream &) const = 0;
199 // display type to stream
200 virtual void showType(std::ostream &) const = 0;
202 // signal parse or usage error
203 virtual void die(const std::string &err) const;
207 // Template classes to specialize parameters to specific types.
209 // Param<T> is for single-valued (scalar) parameters of type T.
210 // VectorParam<T> is for multi-valued (vector) parameters of type T.
211 // These are specified in the .ini file as a space-delimited list of
215 class Param : public BaseParam
223 // Param with default value: set value to default
224 Param(ParamContext *context,
225 const std::string &name, const std::string &description, T dfltValue)
226 : BaseParam(context, name, description, true),
231 // Param with no default value: leave value uninitialized
232 Param(ParamContext *context,
233 const std::string &name, const std::string &description)
234 : BaseParam(context, name, description, false)
242 // if we attempt to reference an invalid parameter (i.e., one
243 // with no default value that was not set by the user), die.
249 // display value to stream
250 virtual void showValue(std::ostream &os) const;
252 // display type to stream
253 virtual void showType(std::ostream &) const;
255 // set value by parsing string
256 virtual void parse(const std::string &s);
261 // Template class for vector-valued parameters (lists)
264 class VectorParam : public BaseParam
268 std::vector<T> value;
272 typedef typename std::vector<T>::size_type size_type;
274 // Param with default value: set value to default
275 VectorParam(ParamContext *context, const std::string &name,
276 const std::string &description,
277 const std::vector<T> &dfltValue)
278 : BaseParam(context, name, description, true),
283 // Param with no default value: leave value uninitialized
284 VectorParam(ParamContext *context,
285 const std::string &name, const std::string &description)
286 : BaseParam(context, name, description, false)
290 virtual ~VectorParam() {}
292 // basic vector access methods
293 size_type size() const
300 const T &operator[](size_type n) const
307 // return reference to value vector
308 operator std::vector<T>&()
315 // display value to stream
316 virtual void showValue(std::ostream &os) const;
318 // display type to stream
319 virtual void showType(std::ostream &) const;
321 // set value by parsing string
322 virtual void parse(const std::string &s);
326 // Specialization of Param<int> and VectorParam<int> to handle
327 // enumerated types is done in two ways, using SimpleEnumParam and
328 // MappedEnumParam (and their vector counterparts,
329 // SimpleEnumVectorParam and MappedEnumVectorParam). SimpleEnumParam
330 // takes an array of strings and maps them to integers based on array
331 // index. MappedEnumParam takes an array of string-to-int mappings,
332 // allowing for mapping strings to non-contiguous integer values, or
333 // mapping multiple strings to the same integer value.
335 // Both SimpleEnumParam and MappedEnumParam are implemented using a
336 // single template class, EnumParam<Map>, which takes the type of the map
337 // as a parameter (const char * or EnumParamMap). Similarly,
338 // SimpleEnumVectorParam and MappedEnumVectorParam are both
339 // implemented using EnumVectorParam<Map>.
342 class EnumParam : public Param<int>
344 const int num_values;
349 // Param with default value: set value to default
350 EnumParam(ParamContext *context,
351 const std::string &name, const std::string &description,
352 const Map *_map, int _num_values,
354 : Param<int>(context, name, description, dfltValue),
355 num_values(_num_values), map(_map)
359 // Param with no default value: leave value uninitialized
360 EnumParam(ParamContext *context,
361 const std::string &name, const std::string &description,
362 const Map *_map, int _num_values)
363 : Param<int>(context, name, description),
364 num_values(_num_values), map(_map)
368 virtual ~EnumParam() {}
370 // display value to stream
371 virtual void showValue(std::ostream &os) const;
373 // display type to stream
374 virtual void showType(std::ostream &) const;
376 // set value by parsing string
377 virtual void parse(const std::string &s);
381 // Vector counterpart to SimpleEnumParam
384 class EnumVectorParam : public VectorParam<int>
386 const int num_values;
391 // Param with default value: set value to default
392 EnumVectorParam(ParamContext *context,
393 const std::string &name, const std::string &description,
394 const Map *_map, int _num_values,
395 std::vector<int> &dfltValue)
396 : VectorParam<int>(context, name, description, dfltValue),
397 num_values(_num_values), map(_map)
401 // Param with no default value: leave value uninitialized
402 EnumVectorParam(ParamContext *context,
403 const std::string &name, const std::string &description,
404 const Map *_map, int _num_values)
405 : VectorParam<int>(context, name, description),
406 num_values(_num_values), map(_map)
410 virtual ~EnumVectorParam() {}
412 // display value to stream
413 virtual void showValue(std::ostream &os) const;
415 // display type to stream
416 virtual void showType(std::ostream &) const;
418 // set value by parsing string
419 virtual void parse(const std::string &s);
422 // Specialize EnumParam for a particular enumeration type ENUM
423 // (automates casting to get value of enum type)
425 template <class ENUM>
426 class SimpleEnumParam : public EnumParam<const char *>
430 SimpleEnumParam(ParamContext *context,
431 const std::string &name, const std::string &description,
432 const char **_map, int _num_values,
434 : EnumParam<const char *>(context, name, description,
435 _map, _num_values, (int)dfltValue)
439 SimpleEnumParam(ParamContext *context,
440 const std::string &name, const std::string &description,
441 const char **_map, int _num_values)
442 : EnumParam<const char *>(context, name, description,
447 operator ENUM() const
456 // Specialize EnumParam for a particular enumeration type ENUM
457 // (automates casting to get value of enum type)
459 template <class ENUM>
460 class SimpleEnumVectorParam : public EnumVectorParam<const char *>
464 // skip default value constructor: too much pain to convert
465 // vector<ENUM> initializer to vector<int>
468 SimpleEnumVectorParam(ParamContext *context,
469 const std::string &name,
470 const std::string &description,
471 const char **_map, int _num_values)
472 : EnumVectorParam<const char *>(context, name, description,
477 ENUM operator[](size_type n)
481 return (ENUM)value[n];
487 // Handle enums via string-to-int map (see comment above).
490 // An array of string-to-int mappings must be supplied using the
497 // Specialize EnumParam for a particular enumeration type ENUM
498 // (automates casting to get value of enum type)
500 template <class ENUM>
501 class MappedEnumParam : public EnumParam<EnumParamMap>
505 MappedEnumParam(ParamContext *context,
506 const std::string &name, const std::string &description,
507 const EnumParamMap *_map, int _num_values,
509 : EnumParam<EnumParamMap>(context, name, description,
510 _map, _num_values, (int)dfltValue)
514 MappedEnumParam(ParamContext *context,
515 const std::string &name, const std::string &description,
516 const EnumParamMap *_map, int _num_values)
517 : EnumParam<EnumParamMap>(context, name, description,
526 return (ENUM)value[n];
531 // Specialize EnumParam for a particular enumeration type ENUM
532 // (automates casting to get value of enum type)
534 template <class ENUM>
535 class MappedEnumVectorParam : public EnumVectorParam<EnumParamMap>
539 // skip default value constructor: too much pain to convert
540 // vector<ENUM> initializer to vector<int>
543 MappedEnumVectorParam(ParamContext *context,
544 const std::string &name,
545 const std::string &description,
546 const EnumParamMap *_map, int _num_values)
547 : EnumVectorParam<EnumParamMap>(context, name, description,
552 ENUM operator[](size_type n)
556 return (ENUM)value[n];
562 // Parameters that point to other simulation objects (e.g. caches,
563 // busses, etc.) are handled by specializing SimObjectBaseParam to the
564 // specific subtype. The main purpose of SimObjectBaseParam is to
565 // provide a place to stick several helper functions common to all
566 // SimObject-derived parameters.
568 class SimObjectBaseParam : public BaseParam
572 SimObjectBaseParam(ParamContext *context, const std::string &name,
573 const std::string &description, bool hasDefault)
574 : BaseParam(context, name, description, hasDefault)
578 virtual ~SimObjectBaseParam() {}
580 // helper function for SimObjectParam<T>::showValue()
581 void showValue(std::ostream &os, SimObject *obj) const;
583 // helper function for SimObjectParam<T>::parse()
584 void parse(const std::string &s, SimObject *&value);
586 // helper function for SimObjectParam<T>::parse()
587 void parse(const std::string &s, std::vector<SimObject *>&value_vec);
592 // Parameter to a specific type of SimObject. Note that T must be a
593 // pointer to a class derived from SimObject (e.g., <CPU *>).
596 template <class T> class SimObjectParam;
599 class SimObjectParam<T *> : public SimObjectBaseParam
607 // initialization w/o default
608 SimObjectParam(ParamContext *context,
609 const std::string &name, const std::string &description)
610 : SimObjectBaseParam(context, name, description, false)
614 // initialization wit=h default
615 SimObjectParam(ParamContext *context,
616 const std::string &name, const std::string &description,
618 : SimObjectBaseParam(context, name, description, true),
623 virtual ~SimObjectParam() {}
625 // convert to pointer
633 T *operator->() const
640 // display value to stream
641 virtual void showValue(std::ostream &os) const
643 SimObjectBaseParam::showValue(os, value);
646 // display type to stream: see REGISTER_SIM_OBJECT macro in
647 // sim_object.hh for declaration
648 virtual void showType(std::ostream &os) const;
650 // set value by parsing string
651 virtual void parse(const std::string &s)
654 // first parse to generic SimObject *
655 SimObjectBaseParam::parse(s, so_ptr);
656 // now dynamic_cast to specific derived type
657 value = dynamic_cast<T *>(so_ptr);
658 // check for failure of dynamic_cast
659 if (value == NULL && so_ptr != NULL)
660 die("not of appropriate type");
666 // Vector counterpart to SimObjectParam<T>
669 template <class T> class SimObjectVectorParam;
672 class SimObjectVectorParam<T *> : public SimObjectBaseParam
676 std::vector<T *> value;
680 typedef typename std::vector<T *>::size_type size_type;
682 SimObjectVectorParam(ParamContext *context,
683 const std::string &name,
684 const std::string &description)
685 : SimObjectBaseParam(context, name, description, false)
689 SimObjectVectorParam(ParamContext *context,
690 const std::string &name,
691 const std::string &description,
692 std::vector<T *> dfltValue)
693 : SimObjectBaseParam(context, name, description, true),
698 virtual ~SimObjectVectorParam() {}
700 // basic vector access methods
701 size_type size() const
708 T *&operator[](size_type n)
715 // return reference to value vector
716 operator std::vector<T *>&()
723 // display value to stream
724 virtual void showValue(std::ostream &os) const
726 for (int i = 0; i < value.size(); i++) {
729 SimObjectBaseParam::showValue(os, value[i]);
733 // display type to stream: see
734 virtual void showType(std::ostream &os) const;
736 // set value by parsing string
737 virtual void parse(const std::string &s)
739 std::vector<SimObject *> so_ptr_vec;
740 // first parse to generic SimObject * vector (from SimObjectBaseParam)
741 SimObjectBaseParam::parse(s, so_ptr_vec);
743 value.resize(so_ptr_vec.size());
745 for (int i = 0; i < so_ptr_vec.size(); ++i) {
746 // now dynamic_cast to specific derived type
747 value[i] = dynamic_cast<T *>(so_ptr_vec[i]);
748 // check for failure of dynamic_cast
749 if (value[i] == NULL && so_ptr_vec[i] != NULL)
750 die("not of appropriate type");
756 // Macro to define showType() methods for SimObjectParam &
757 // SimObjectVectorParam. Can't do this automatically as it requires a
758 // string name for the type, which you can't get from a template
759 // argument. For concrete derived SimObject types, this macro is
760 // automatically invoked by REGISTER_SIM_OBJECT() (see sim_object.hh).
762 #define DEFINE_SIM_OBJECT_CLASS_NAME(CLASS_NAME, OBJ_CLASS) \
764 SimObjectParam<OBJ_CLASS *>::showType(std::ostream &os) const \
770 SimObjectVectorParam<OBJ_CLASS *>::showType(std::ostream &os) const \
772 os << "vector of " << CLASS_NAME; \
777 // Declarations for low-level parsing & displaying functions. These
778 // are used internally, but should not be used directly by clients of
779 // the parameter mechanism, but are declared here so they can be
780 // shared with the serialization code (see sim/serialize.cc).
781 template <class T> bool parseParam(const std::string &str, T &data);
782 template <class T> void showParam(std::ostream &os, const T &data);