2 * Copyright (c) 2002-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: Steve Reinhardt
31 #ifndef __SIM_PARAM_HH__
32 #define __SIM_PARAM_HH__
39 #include "sim/configfile.hh"
40 #include "sim/startup.hh"
47 // The context of a parameter definition... usually a subclass of
48 // SimObjectBuilder (which derives from ParamContext), but abstracted
49 // here to support more global simulator control parameters as well.
51 class ParamContext : protected StartupCallback
55 // static list of all ParamContext objects, built as a side effect
56 // of the ParamContext constructor
57 static std::list<ParamContext *> *ctxList;
61 // .ini file (database) for parameter lookup... initialized on call
65 // .ini file section for parameter lookup
66 const std::string iniSection;
68 typedef std::vector<BaseParam *> ParamList;
70 // list of parameters defined in this context
73 ParamList *getParamList() {
75 paramList = new ParamList;
81 /// Initialization phases for ParamContext objects.
83 NoAutoInit = -1, ///< Don't initialize at all... params
84 /// will be parsed later (used by
85 /// SimObjectBuilder, which parses
86 /// params in SimObject::create().
87 OutputInitPhase = 0, ///< Output stream initialization
88 TraceInitPhase = 1, ///< Trace context initialization:
89 /// depends on output streams, but
90 /// needs to come before others so we
91 /// can use tracing in other
92 /// ParamContext init code
93 StatsInitPhase = 2, ///< Stats output initialization
94 DefaultInitPhase = 3 ///< Everything else
97 /// Records the initialization phase for this ParamContext.
101 /// @param _iniSection Name of .ini section corresponding to this context.
102 /// @param _initPhase Initialization phase (see InitPhase).
103 ParamContext(const std::string &_iniSection,
104 InitPhase _initPhase = DefaultInitPhase);
106 virtual ~ParamContext() {}
108 // add a parameter to the context... called from the parameter
109 // object's constructor (see BaseParam::BaseParam())
110 void addParam(BaseParam *);
112 // call parse() on all params in this context to convert string
113 // representations to parameter values
114 virtual void parseParams(IniFile &iniFile);
116 // Check parameter values for validity & consistency. Default
117 // implementation is no-op; derive subclass & override to add
118 // actual functionality here
119 virtual void checkParams();
121 // Clean up at end of execution: close file descriptors, etc.
122 // Default implementation is no-op; derive subclass & override to
123 // add actual functionality here
124 virtual void cleanup();
126 // dump parameter descriptions
127 void describeParams(std::ostream &);
129 // Display the parameters & values used
130 void showParams(std::ostream &);
132 // print context information for parameter error
133 virtual void printErrorProlog(std::ostream &);
135 // resolve a SimObject name in this context to an object pointer.
136 virtual SimObject *resolveSimObject(const std::string &name);
138 // generate the name for this instance of this context (used as a
139 // prefix to create unique names in resolveSimObject()
140 virtual const std::string &getInstanceName() { return iniSection; }
142 // return the configuration hierarchy node for this context. Bare
143 // ParamContext objects have no corresponding node, so the default
144 // implementation returns NULL.
145 virtual ConfigNode *getConfigNode() { return NULL; }
147 // Parse all parameters registered with all ParamContext objects.
148 static void parseAllContexts(IniFile &iniFile);
150 // Check all parameters registered with all ParamContext objects.
151 // (calls checkParams() on each)
152 static void checkAllContexts();
154 // Print all parameter values on indicated ostream.
155 static void showAllContexts(std::ostream &os);
157 // Clean up all registered ParamContext objects. (calls cleanup()
159 static void cleanupAllContexts();
161 // print descriptions of all parameters registered with all
162 // ParamContext objects
163 static void describeAllContexts(std::ostream &os);
168 // Base class for all parameter objects
174 ParamContext *context;
176 std::string description; // text description for help message
177 bool wasSet; // true if parameter was set by user
178 bool hasDefault; // true if parameter has default value
180 BaseParam(ParamContext *_context, const std::string &_name,
181 const std::string &_description, bool _hasDefault)
182 : context(_context), name(_name), description(_description),
183 wasSet(false), hasDefault(_hasDefault)
185 context->addParam(this);
188 virtual ~BaseParam() {}
190 // a parameter is valid only if its value was set by the user or
191 // it has a default value
194 return (wasSet || hasDefault);
197 // set value by parsing string
198 virtual void parse(const std::string &s) = 0;
200 // display value to stream
201 virtual void showValue(std::ostream &) const = 0;
203 // display type to stream
204 virtual void showType(std::ostream &) const = 0;
206 // signal parse or usage error
207 virtual void die(const std::string &err) const;
211 // Template classes to specialize parameters to specific types.
213 // Param<T> is for single-valued (scalar) parameters of type T.
214 // VectorParam<T> is for multi-valued (vector) parameters of type T.
215 // These are specified in the .ini file as a space-delimited list of
219 class Param : public BaseParam
227 // Param with default value: set value to default
228 Param(ParamContext *context,
229 const std::string &name, const std::string &description, T dfltValue)
230 : BaseParam(context, name, description, true),
235 // Param with no default value: leave value uninitialized
236 Param(ParamContext *context,
237 const std::string &name, const std::string &description)
238 : BaseParam(context, name, description, false)
246 // if we attempt to reference an invalid parameter (i.e., one
247 // with no default value that was not set by the user), die.
253 // display value to stream
254 virtual void showValue(std::ostream &os) const;
256 // display type to stream
257 virtual void showType(std::ostream &) const;
259 // set value by parsing string
260 virtual void parse(const std::string &s);
265 // Template class for vector-valued parameters (lists)
268 class VectorParam : public BaseParam
272 std::vector<T> value;
276 typedef typename std::vector<T>::size_type size_type;
278 // Param with default value: set value to default
279 VectorParam(ParamContext *context, const std::string &name,
280 const std::string &description,
281 const std::vector<T> &dfltValue)
282 : BaseParam(context, name, description, true),
287 // Param with no default value: leave value uninitialized
288 VectorParam(ParamContext *context,
289 const std::string &name, const std::string &description)
290 : BaseParam(context, name, description, false)
294 virtual ~VectorParam() {}
296 // basic vector access methods
297 size_type size() const
304 const T &operator[](size_type n) const
311 // return reference to value vector
312 operator std::vector<T>&()
319 // display value to stream
320 virtual void showValue(std::ostream &os) const;
322 // display type to stream
323 virtual void showType(std::ostream &) const;
325 // set value by parsing string
326 virtual void parse(const std::string &s);
330 // Specialization of Param<int> and VectorParam<int> to handle
331 // enumerated types is done in two ways, using SimpleEnumParam and
332 // MappedEnumParam (and their vector counterparts,
333 // SimpleEnumVectorParam and MappedEnumVectorParam). SimpleEnumParam
334 // takes an array of strings and maps them to integers based on array
335 // index. MappedEnumParam takes an array of string-to-int mappings,
336 // allowing for mapping strings to non-contiguous integer values, or
337 // mapping multiple strings to the same integer value.
339 // Both SimpleEnumParam and MappedEnumParam are implemented using a
340 // single template class, EnumParam<Map>, which takes the type of the map
341 // as a parameter (const char * or EnumParamMap). Similarly,
342 // SimpleEnumVectorParam and MappedEnumVectorParam are both
343 // implemented using EnumVectorParam<Map>.
346 class EnumParam : public Param<int>
348 const int num_values;
353 // Param with default value: set value to default
354 EnumParam(ParamContext *context,
355 const std::string &name, const std::string &description,
356 const Map *_map, int _num_values,
358 : Param<int>(context, name, description, dfltValue),
359 num_values(_num_values), map(_map)
363 // Param with no default value: leave value uninitialized
364 EnumParam(ParamContext *context,
365 const std::string &name, const std::string &description,
366 const Map *_map, int _num_values)
367 : Param<int>(context, name, description),
368 num_values(_num_values), map(_map)
372 virtual ~EnumParam() {}
374 // display value to stream
375 virtual void showValue(std::ostream &os) const;
377 // display type to stream
378 virtual void showType(std::ostream &) const;
380 // set value by parsing string
381 virtual void parse(const std::string &s);
385 // Vector counterpart to SimpleEnumParam
388 class EnumVectorParam : public VectorParam<int>
390 const int num_values;
395 // Param with default value: set value to default
396 EnumVectorParam(ParamContext *context,
397 const std::string &name, const std::string &description,
398 const Map *_map, int _num_values,
399 std::vector<int> &dfltValue)
400 : VectorParam<int>(context, name, description, dfltValue),
401 num_values(_num_values), map(_map)
405 // Param with no default value: leave value uninitialized
406 EnumVectorParam(ParamContext *context,
407 const std::string &name, const std::string &description,
408 const Map *_map, int _num_values)
409 : VectorParam<int>(context, name, description),
410 num_values(_num_values), map(_map)
414 virtual ~EnumVectorParam() {}
416 // display value to stream
417 virtual void showValue(std::ostream &os) const;
419 // display type to stream
420 virtual void showType(std::ostream &) const;
422 // set value by parsing string
423 virtual void parse(const std::string &s);
426 // Specialize EnumParam for a particular enumeration type ENUM
427 // (automates casting to get value of enum type)
429 template <class ENUM>
430 class SimpleEnumParam : public EnumParam<const char *>
434 SimpleEnumParam(ParamContext *context,
435 const std::string &name, const std::string &description,
436 const char **_map, int _num_values,
438 : EnumParam<const char *>(context, name, description,
439 _map, _num_values, (int)dfltValue)
443 SimpleEnumParam(ParamContext *context,
444 const std::string &name, const std::string &description,
445 const char **_map, int _num_values)
446 : EnumParam<const char *>(context, name, description,
451 operator ENUM() const
460 // Specialize EnumParam for a particular enumeration type ENUM
461 // (automates casting to get value of enum type)
463 template <class ENUM>
464 class SimpleEnumVectorParam : public EnumVectorParam<const char *>
468 // skip default value constructor: too much pain to convert
469 // vector<ENUM> initializer to vector<int>
472 SimpleEnumVectorParam(ParamContext *context,
473 const std::string &name,
474 const std::string &description,
475 const char **_map, int _num_values)
476 : EnumVectorParam<const char *>(context, name, description,
481 ENUM operator[](size_type n)
485 return (ENUM)value[n];
491 // Handle enums via string-to-int map (see comment above).
494 // An array of string-to-int mappings must be supplied using the
501 // Specialize EnumParam for a particular enumeration type ENUM
502 // (automates casting to get value of enum type)
504 template <class ENUM>
505 class MappedEnumParam : public EnumParam<EnumParamMap>
509 MappedEnumParam(ParamContext *context,
510 const std::string &name, const std::string &description,
511 const EnumParamMap *_map, int _num_values,
513 : EnumParam<EnumParamMap>(context, name, description,
514 _map, _num_values, (int)dfltValue)
518 MappedEnumParam(ParamContext *context,
519 const std::string &name, const std::string &description,
520 const EnumParamMap *_map, int _num_values)
521 : EnumParam<EnumParamMap>(context, name, description,
530 return (ENUM)value[this->n];
535 // Specialize EnumParam for a particular enumeration type ENUM
536 // (automates casting to get value of enum type)
538 template <class ENUM>
539 class MappedEnumVectorParam : public EnumVectorParam<EnumParamMap>
543 // skip default value constructor: too much pain to convert
544 // vector<ENUM> initializer to vector<int>
547 MappedEnumVectorParam(ParamContext *context,
548 const std::string &name,
549 const std::string &description,
550 const EnumParamMap *_map, int _num_values)
551 : EnumVectorParam<EnumParamMap>(context, name, description,
556 ENUM operator[](size_type n)
560 return (ENUM)value[n];
566 // Parameters that point to other simulation objects (e.g. caches,
567 // busses, etc.) are handled by specializing SimObjectBaseParam to the
568 // specific subtype. The main purpose of SimObjectBaseParam is to
569 // provide a place to stick several helper functions common to all
570 // SimObject-derived parameters.
572 class SimObjectBaseParam : public BaseParam
576 SimObjectBaseParam(ParamContext *context, const std::string &name,
577 const std::string &description, bool hasDefault)
578 : BaseParam(context, name, description, hasDefault)
582 virtual ~SimObjectBaseParam() {}
584 // helper function for SimObjectParam<T>::showValue()
585 void showValue(std::ostream &os, SimObject *obj) const;
587 // helper function for SimObjectParam<T>::parse()
588 void parse(const std::string &s, SimObject *&value);
590 // helper function for SimObjectParam<T>::parse()
591 void parse(const std::string &s, std::vector<SimObject *>&value_vec);
596 // Parameter to a specific type of SimObject. Note that T must be a
597 // pointer to a class derived from SimObject (e.g., <CPU *>).
600 template <class T> class SimObjectParam;
603 class SimObjectParam<T *> : public SimObjectBaseParam
611 // initialization w/o default
612 SimObjectParam(ParamContext *context,
613 const std::string &name, const std::string &description)
614 : SimObjectBaseParam(context, name, description, false)
618 // initialization wit=h default
619 SimObjectParam(ParamContext *context,
620 const std::string &name, const std::string &description,
622 : SimObjectBaseParam(context, name, description, true),
627 virtual ~SimObjectParam() {}
629 // convert to pointer
637 T *operator->() const
644 // display value to stream
645 virtual void showValue(std::ostream &os) const
647 SimObjectBaseParam::showValue(os, value);
650 // display type to stream: see REGISTER_SIM_OBJECT macro in
651 // sim_object.hh for declaration
652 virtual void showType(std::ostream &os) const;
654 // set value by parsing string
655 virtual void parse(const std::string &s)
658 // first parse to generic SimObject *
659 SimObjectBaseParam::parse(s, so_ptr);
660 // now dynamic_cast to specific derived type
661 value = dynamic_cast<T *>(so_ptr);
662 // check for failure of dynamic_cast
663 if (value == NULL && so_ptr != NULL)
664 die("not of appropriate type");
670 // Vector counterpart to SimObjectParam<T>
673 template <class T> class SimObjectVectorParam;
676 class SimObjectVectorParam<T *> : public SimObjectBaseParam
680 std::vector<T *> value;
684 typedef typename std::vector<T *>::size_type size_type;
686 SimObjectVectorParam(ParamContext *context,
687 const std::string &name,
688 const std::string &description)
689 : SimObjectBaseParam(context, name, description, false)
693 SimObjectVectorParam(ParamContext *context,
694 const std::string &name,
695 const std::string &description,
696 std::vector<T *> dfltValue)
697 : SimObjectBaseParam(context, name, description, true),
702 virtual ~SimObjectVectorParam() {}
704 // basic vector access methods
705 size_type size() const
712 T *&operator[](size_type n)
719 // return reference to value vector
720 operator std::vector<T *>&()
727 // display value to stream
728 virtual void showValue(std::ostream &os) const
730 for (int i = 0; i < value.size(); i++) {
733 SimObjectBaseParam::showValue(os, value[i]);
737 // display type to stream: see
738 virtual void showType(std::ostream &os) const;
740 // set value by parsing string
741 virtual void parse(const std::string &s)
743 std::vector<SimObject *> so_ptr_vec;
744 // first parse to generic SimObject * vector (from SimObjectBaseParam)
745 SimObjectBaseParam::parse(s, so_ptr_vec);
747 value.resize(so_ptr_vec.size());
749 for (int i = 0; i < so_ptr_vec.size(); ++i) {
750 // now dynamic_cast to specific derived type
751 value[i] = dynamic_cast<T *>(so_ptr_vec[i]);
752 // check for failure of dynamic_cast
753 if (value[i] == NULL && so_ptr_vec[i] != NULL)
754 die("not of appropriate type");
760 // Macro to define showType() methods for SimObjectParam &
761 // SimObjectVectorParam. Can't do this automatically as it requires a
762 // string name for the type, which you can't get from a template
763 // argument. For concrete derived SimObject types, this macro is
764 // automatically invoked by REGISTER_SIM_OBJECT() (see sim_object.hh).
766 #define DEFINE_SIM_OBJECT_CLASS_NAME(CLASS_NAME, OBJ_CLASS) \
769 SimObjectParam<OBJ_CLASS *>::showType(std::ostream &os) const \
776 SimObjectVectorParam<OBJ_CLASS *>::showType(std::ostream &os) const \
778 os << "vector of " << CLASS_NAME; \
783 // Declarations for low-level parsing & displaying functions. These
784 // are used internally, but should not be used directly by clients of
785 // the parameter mechanism, but are declared here so they can be
786 // shared with the serialization code (see sim/serialize.cc).
787 template <class T> bool parseParam(const std::string &str, T &data);
788 template <class T> void showParam(std::ostream &os, const T &data);
790 #endif // _SIM_PARAM_HH_