serialize.hh revision 10861
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/bitunion.hh" 47#include "base/types.hh" 48 49class IniFile; 50class Serializable; 51class Checkpoint; 52class SimObject; 53class EventQueue; 54 55/** The current version of the checkpoint format. 56 * This should be incremented by 1 and only 1 for every new version, where a new 57 * version is defined as a checkpoint created before this version won't work on 58 * the current version until the checkpoint format is updated. Adding a new 59 * SimObject shouldn't cause the version number to increase, only changes to 60 * existing objects such as serializing/unserializing more state, changing sizes 61 * of serialized arrays, etc. */ 62static const uint64_t gem5CheckpointVersion = 0x000000000000000e; 63 64template <class T> 65void paramOut(std::ostream &os, const std::string &name, const T ¶m); 66 67template <typename DataType, typename BitUnion> 68void paramOut(std::ostream &os, const std::string &name, 69 const BitfieldBackend::BitUnionOperators<DataType, BitUnion> &p) 70{ 71 paramOut(os, name, p.__data); 72} 73 74template <class T> 75void paramIn(Checkpoint *cp, const std::string §ion, 76 const std::string &name, T ¶m); 77 78template <typename DataType, typename BitUnion> 79void paramIn(Checkpoint *cp, const std::string §ion, 80 const std::string &name, 81 BitfieldBackend::BitUnionOperators<DataType, BitUnion> &p) 82{ 83 paramIn(cp, section, name, p.__data); 84} 85 86template <class T> 87bool optParamIn(Checkpoint *cp, const std::string §ion, 88 const std::string &name, T ¶m); 89 90template <typename DataType, typename BitUnion> 91bool optParamIn(Checkpoint *cp, const std::string §ion, 92 const std::string &name, 93 BitfieldBackend::BitUnionOperators<DataType, BitUnion> &p) 94{ 95 return optParamIn(cp, section, name, p.__data); 96} 97 98template <class T> 99void arrayParamOut(std::ostream &os, const std::string &name, 100 const T *param, unsigned size); 101 102template <class T> 103void arrayParamOut(std::ostream &os, const std::string &name, 104 const std::vector<T> ¶m); 105 106template <class T> 107void arrayParamOut(std::ostream &os, const std::string &name, 108 const std::list<T> ¶m); 109 110template <class T> 111void arrayParamIn(Checkpoint *cp, const std::string §ion, 112 const std::string &name, T *param, unsigned size); 113 114template <class T> 115void arrayParamIn(Checkpoint *cp, const std::string §ion, 116 const std::string &name, std::vector<T> ¶m); 117 118template <class T> 119void arrayParamIn(Checkpoint *cp, const std::string §ion, 120 const std::string &name, std::list<T> ¶m); 121 122void 123objParamIn(Checkpoint *cp, const std::string §ion, 124 const std::string &name, SimObject * ¶m); 125 126template <typename T> 127void fromInt(T &t, int i) 128{ 129 t = (T)i; 130} 131 132template <typename T> 133void fromSimObject(T &t, SimObject *s) 134{ 135 t = dynamic_cast<T>(s); 136} 137 138// 139// These macros are streamlined to use in serialize/unserialize 140// functions. It's assumed that serialize() has a parameter 'os' for 141// the ostream, and unserialize() has parameters 'cp' and 'section'. 142#define SERIALIZE_SCALAR(scalar) paramOut(os, #scalar, scalar) 143 144#define UNSERIALIZE_SCALAR(scalar) paramIn(cp, section, #scalar, scalar) 145#define UNSERIALIZE_OPT_SCALAR(scalar) optParamIn(cp, section, #scalar, scalar) 146 147// ENUMs are like SCALARs, but we cast them to ints on the way out 148#define SERIALIZE_ENUM(scalar) paramOut(os, #scalar, (int)scalar) 149 150#define UNSERIALIZE_ENUM(scalar) \ 151 do { \ 152 int tmp; \ 153 paramIn(cp, section, #scalar, tmp); \ 154 fromInt(scalar, tmp); \ 155 } while (0) 156 157#define SERIALIZE_ARRAY(member, size) \ 158 arrayParamOut(os, #member, member, size) 159 160#define UNSERIALIZE_ARRAY(member, size) \ 161 arrayParamIn(cp, section, #member, member, size) 162 163#define SERIALIZE_OBJPTR(objptr) paramOut(os, #objptr, (objptr)->name()) 164 165#define UNSERIALIZE_OBJPTR(objptr) \ 166 do { \ 167 SimObject *sptr; \ 168 objParamIn(cp, section, #objptr, sptr); \ 169 fromSimObject(objptr, sptr); \ 170 } while (0) 171 172/** 173 * Basic support for object serialization. 174 * 175 * @note Many objects that support serialization need to be put in a 176 * consistent state when serialization takes place. We refer to the 177 * action of forcing an object into a consistent state as 178 * 'draining'. Objects that need draining inherit from Drainable. See 179 * Drainable for more information. 180 */ 181class Serializable 182{ 183 protected: 184 void nameOut(std::ostream &os); 185 void nameOut(std::ostream &os, const std::string &_name); 186 187 public: 188 Serializable(); 189 virtual ~Serializable(); 190 191 // manditory virtual function, so objects must provide names 192 virtual const std::string name() const = 0; 193 194 virtual void serialize(std::ostream &os); 195 virtual void unserialize(Checkpoint *cp, const std::string §ion); 196 197 static Serializable *create(Checkpoint *cp, const std::string §ion); 198 199 static int ckptCount; 200 static int ckptMaxCount; 201 static int ckptPrevCount; 202 static void serializeAll(const std::string &cpt_dir); 203 static void unserializeGlobals(Checkpoint *cp); 204}; 205 206void debug_serialize(const std::string &cpt_dir); 207 208// 209// A SerializableBuilder serves as an evaluation context for a set of 210// parameters that describe a specific instance of a Serializable. This 211// evaluation context corresponds to a section in the .ini file (as 212// with the base ParamContext) plus an optional node in the 213// configuration hierarchy (the configNode member) for resolving 214// Serializable references. SerializableBuilder is an abstract superclass; 215// derived classes specialize the class for particular subclasses of 216// Serializable (e.g., BaseCache). 217// 218// For typical usage, see the definition of 219// SerializableClass::createObject(). 220// 221class SerializableBuilder 222{ 223 public: 224 225 SerializableBuilder() {} 226 227 virtual ~SerializableBuilder() {} 228 229 // Create the actual Serializable corresponding to the parameter 230 // values in this context. This function is overridden in derived 231 // classes to call a specific constructor for a particular 232 // subclass of Serializable. 233 virtual Serializable *create() = 0; 234}; 235 236// 237// An instance of SerializableClass corresponds to a class derived from 238// Serializable. The SerializableClass instance serves to bind the string 239// name (found in the config file) to a function that creates an 240// instance of the appropriate derived class. 241// 242// This would be much cleaner in Smalltalk or Objective-C, where types 243// are first-class objects themselves. 244// 245class SerializableClass 246{ 247 public: 248 249 // Type CreateFunc is a pointer to a function that creates a new 250 // simulation object builder based on a .ini-file parameter 251 // section (specified by the first string argument), a unique name 252 // for the object (specified by the second string argument), and 253 // an optional config hierarchy node (specified by the third 254 // argument). A pointer to the new SerializableBuilder is returned. 255 typedef Serializable *(*CreateFunc)(Checkpoint *cp, 256 const std::string §ion); 257 258 static std::map<std::string,CreateFunc> *classMap; 259 260 // Constructor. For example: 261 // 262 // SerializableClass baseCacheSerializableClass("BaseCacheSerializable", 263 // newBaseCacheSerializableBuilder); 264 // 265 SerializableClass(const std::string &className, CreateFunc createFunc); 266 267 // create Serializable given name of class and pointer to 268 // configuration hierarchy node 269 static Serializable *createObject(Checkpoint *cp, 270 const std::string §ion); 271}; 272 273// 274// Macros to encapsulate the magic of declaring & defining 275// SerializableBuilder and SerializableClass objects 276// 277 278#define REGISTER_SERIALIZEABLE(CLASS_NAME, OBJ_CLASS) \ 279SerializableClass the##OBJ_CLASS##Class(CLASS_NAME, \ 280 OBJ_CLASS::createForUnserialize); 281 282// Base class to wrap object resolving functionality. This can be 283// provided to Checkpoint to allow it to map object names onto 284// object C++ objects in which to unserialize 285class SimObjectResolver 286{ 287 public: 288 virtual ~SimObjectResolver() { } 289 290 // Find a SimObject given a full path name 291 virtual SimObject *resolveSimObject(const std::string &name) = 0; 292}; 293 294class Checkpoint 295{ 296 private: 297 298 IniFile *db; 299 300 SimObjectResolver &objNameResolver; 301 302 public: 303 Checkpoint(const std::string &cpt_dir, SimObjectResolver &resolver); 304 ~Checkpoint(); 305 306 const std::string cptDir; 307 308 bool find(const std::string §ion, const std::string &entry, 309 std::string &value); 310 311 bool findObj(const std::string §ion, const std::string &entry, 312 SimObject *&value); 313 314 bool sectionExists(const std::string §ion); 315 316 // The following static functions have to do with checkpoint 317 // creation rather than restoration. This class makes a handy 318 // namespace for them though. Currently no Checkpoint object is 319 // created on serialization (only unserialization) so we track the 320 // directory name as a global. It would be nice to change this 321 // someday 322 323 private: 324 // current directory we're serializing into. 325 static std::string currentDirectory; 326 327 public: 328 // Set the current directory. This function takes care of 329 // inserting curTick() if there's a '%d' in the argument, and 330 // appends a '/' if necessary. The final name is returned. 331 static std::string setDir(const std::string &base_name); 332 333 // Export current checkpoint directory name so other objects can 334 // derive filenames from it (e.g., memory). The return value is 335 // guaranteed to end in '/' so filenames can be directly appended. 336 // This function is only valid while a checkpoint is being created. 337 static std::string dir(); 338 339 // Filename for base checkpoint file within directory. 340 static const char *baseFilename; 341}; 342 343#endif // __SERIALIZE_HH__ 344