src/sim/serialize.hh

   1 /*
   2  * Copyright (c) 2002-2005 The Regents of The University of Michigan
   3  * All rights reserved.
   4  *
   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.
  15  *
  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.
  27  *
  28  * Authors: Nathan Binkert
  29  *          Erik Hallnor
  30  *          Steve Reinhardt
  31  */
  32
  33 /* @file
  34  * Serialization Interface Declarations
  35  */
  36
  37 #ifndef __SERIALIZE_HH__
  38 #define __SERIALIZE_HH__
  39
  40
  41 #include <iostream>
  42 #include <list>
  43 #include <map>
  44 #include <vector>
  45
  46 #include "base/types.hh"
  47
  48 class IniFile;
  49 class Serializable;
  50 class Checkpoint;
  51 class SimObject;
  52
  53 template <class T>
  54 void paramOut(std::ostream &os, const std::string &name, const T &param);
  55
  56 template <class T>
  57 void paramIn(Checkpoint *cp, const std::string &section,
  58              const std::string &name, T &param);
  59
  60 template <class T>
  61 bool optParamIn(Checkpoint *cp, const std::string &section,
  62              const std::string &name, T &param);
  63
  64 template <class T>
  65 void arrayParamOut(std::ostream &os, const std::string &name,
  66                    const T *param, unsigned size);
  67
  68 template <class T>
  69 void arrayParamOut(std::ostream &os, const std::string &name,
  70                    const std::vector<T> &param);
  71
  72 template <class T>
  73 void arrayParamOut(std::ostream &os, const std::string &name,
  74                    const std::list<T> &param);
  75
  76 template <class T>
  77 void arrayParamIn(Checkpoint *cp, const std::string &section,
  78                   const std::string &name, T *param, unsigned size);
  79
  80 template <class T>
  81 void arrayParamIn(Checkpoint *cp, const std::string &section,
  82                   const std::string &name, std::vector<T> &param);
  83
  84 template <class T>
  85 void arrayParamIn(Checkpoint *cp, const std::string &section,
  86                   const std::string &name, std::list<T> &param);
  87
  88 void
  89 objParamIn(Checkpoint *cp, const std::string &section,
  90            const std::string &name, SimObject * &param);
  91
  92
  93 //
  94 // These macros are streamlined to use in serialize/unserialize
  95 // functions.  It's assumed that serialize() has a parameter 'os' for
  96 // the ostream, and unserialize() has parameters 'cp' and 'section'.
  97 #define SERIALIZE_SCALAR(scalar)        paramOut(os, #scalar, scalar)
  98
  99 #define UNSERIALIZE_SCALAR(scalar)      paramIn(cp, section, #scalar, scalar)
 100 #define UNSERIALIZE_OPT_SCALAR(scalar)      optParamIn(cp, section, #scalar, scalar)
 101
 102 // ENUMs are like SCALARs, but we cast them to ints on the way out
 103 #define SERIALIZE_ENUM(scalar)          paramOut(os, #scalar, (int)scalar)
 104
 105 #define UNSERIALIZE_ENUM(scalar)                \
 106  do {                                           \
 107     int tmp;                                    \
 108     paramIn(cp, section, #scalar, tmp);         \
 109     scalar = (typeof(scalar))tmp;               \
 110   } while (0)
 111
 112 #define SERIALIZE_ARRAY(member, size)           \
 113         arrayParamOut(os, #member, member, size)
 114
 115 #define UNSERIALIZE_ARRAY(member, size)         \
 116         arrayParamIn(cp, section, #member, member, size)
 117
 118 #define SERIALIZE_OBJPTR(objptr)        paramOut(os, #objptr, (objptr)->name())
 119
 120 #define UNSERIALIZE_OBJPTR(objptr)                      \
 121   do {                                                  \
 122     SimObject *sptr;                                    \
 123     objParamIn(cp, section, #objptr, sptr);             \
 124     objptr = dynamic_cast<typeof(objptr)>(sptr);        \
 125   } while (0)
 126
 127 /*
 128  * Basic support for object serialization.
 129  */
 130 class Serializable
 131 {
 132   protected:
 133     void nameOut(std::ostream &os);
 134     void nameOut(std::ostream &os, const std::string &_name);
 135
 136   public:
 137     Serializable();
 138     virtual ~Serializable();
 139
 140     // manditory virtual function, so objects must provide names
 141     virtual const std::string name() const = 0;
 142
 143     virtual void serialize(std::ostream &os);
 144     virtual void unserialize(Checkpoint *cp, const std::string &section);
 145
 146     static Serializable *create(Checkpoint *cp, const std::string &section);
 147
 148     static int ckptCount;
 149     static int ckptMaxCount;
 150     static int ckptPrevCount;
 151     static void serializeAll(const std::string &cpt_dir);
 152     static void unserializeGlobals(Checkpoint *cp);
 153 };
 154
 155 //
 156 // A SerializableBuilder serves as an evaluation context for a set of
 157 // parameters that describe a specific instance of a Serializable.  This
 158 // evaluation context corresponds to a section in the .ini file (as
 159 // with the base ParamContext) plus an optional node in the
 160 // configuration hierarchy (the configNode member) for resolving
 161 // Serializable references.  SerializableBuilder is an abstract superclass;
 162 // derived classes specialize the class for particular subclasses of
 163 // Serializable (e.g., BaseCache).
 164 //
 165 // For typical usage, see the definition of
 166 // SerializableClass::createObject().
 167 //
 168 class SerializableBuilder
 169 {
 170   public:
 171
 172     SerializableBuilder() {}
 173
 174     virtual ~SerializableBuilder() {}
 175
 176     // Create the actual Serializable corresponding to the parameter
 177     // values in this context.  This function is overridden in derived
 178     // classes to call a specific constructor for a particular
 179     // subclass of Serializable.
 180     virtual Serializable *create() = 0;
 181 };
 182
 183 //
 184 // An instance of SerializableClass corresponds to a class derived from
 185 // Serializable.  The SerializableClass instance serves to bind the string
 186 // name (found in the config file) to a function that creates an
 187 // instance of the appropriate derived class.
 188 //
 189 // This would be much cleaner in Smalltalk or Objective-C, where types
 190 // are first-class objects themselves.
 191 //
 192 class SerializableClass
 193 {
 194   public:
 195
 196     // Type CreateFunc is a pointer to a function that creates a new
 197     // simulation object builder based on a .ini-file parameter
 198     // section (specified by the first string argument), a unique name
 199     // for the object (specified by the second string argument), and
 200     // an optional config hierarchy node (specified by the third
 201     // argument).  A pointer to the new SerializableBuilder is returned.
 202     typedef Serializable *(*CreateFunc)(Checkpoint *cp,
 203                                         const std::string &section);
 204
 205     static std::map<std::string,CreateFunc> *classMap;
 206
 207     // Constructor.  For example:
 208     //
 209     // SerializableClass baseCacheSerializableClass("BaseCacheSerializable",
 210     //                         newBaseCacheSerializableBuilder);
 211     //
 212     SerializableClass(const std::string &className, CreateFunc createFunc);
 213
 214     // create Serializable given name of class and pointer to
 215     // configuration hierarchy node
 216     static Serializable *createObject(Checkpoint *cp,
 217                                       const std::string &section);
 218 };
 219
 220 //
 221 // Macros to encapsulate the magic of declaring & defining
 222 // SerializableBuilder and SerializableClass objects
 223 //
 224
 225 #define REGISTER_SERIALIZEABLE(CLASS_NAME, OBJ_CLASS)                      \
 226 SerializableClass the##OBJ_CLASS##Class(CLASS_NAME,                        \
 227                                          OBJ_CLASS::createForUnserialize);
 228
 229 class Checkpoint
 230 {
 231   private:
 232
 233     IniFile *db;
 234
 235   public:
 236     Checkpoint(const std::string &cpt_dir);
 237
 238     const std::string cptDir;
 239
 240     bool find(const std::string &section, const std::string &entry,
 241               std::string &value);
 242
 243     bool findObj(const std::string &section, const std::string &entry,
 244                  SimObject *&value);
 245
 246     bool sectionExists(const std::string &section);
 247
 248     // The following static functions have to do with checkpoint
 249     // creation rather than restoration.  This class makes a handy
 250     // namespace for them though.  Currently no Checkpoint object is
 251     // created on serialization (only unserialization) so we track the
 252     // directory name as a global.  It would be nice to change this
 253     // someday
 254
 255   private:
 256     // current directory we're serializing into.
 257     static std::string currentDirectory;
 258
 259   public:
 260     // Set the current directory.  This function takes care of
 261     // inserting curTick() if there's a '%d' in the argument, and
 262     // appends a '/' if necessary.  The final name is returned.
 263     static std::string setDir(const std::string &base_name);
 264
 265     // Export current checkpoint directory name so other objects can
 266     // derive filenames from it (e.g., memory).  The return value is
 267     // guaranteed to end in '/' so filenames can be directly appended.
 268     // This function is only valid while a checkpoint is being created.
 269     static std::string dir();
 270
 271     // Filename for base checkpoint file within directory.
 272     static const char *baseFilename;
 273 };
 274
 275 #endif // __SERIALIZE_HH__