src/sim/serialize.hh

   1 /*
   2  * Copyright (c) 2015 ARM Limited
   3  * All rights reserved
   4  *
   5  * The license below extends only to copyright in the software and shall
   6  * not be construed as granting a license to any other intellectual
   7  * property including but not limited to intellectual property relating
   8  * to a hardware implementation of the functionality of the software
   9  * licensed hereunder.  You may use the software subject to the license
  10  * terms below provided that you ensure that this notice is replicated
  11  * unmodified and in its entirety in all distributions of the software,
  12  * modified or unmodified, in source code or in binary form.
  13  *
  14  * Copyright (c) 2002-2005 The Regents of The University of Michigan
  15  * All rights reserved.
  16  *
  17  * Redistribution and use in source and binary forms, with or without
  18  * modification, are permitted provided that the following conditions are
  19  * met: redistributions of source code must retain the above copyright
  20  * notice, this list of conditions and the following disclaimer;
  21  * redistributions in binary form must reproduce the above copyright
  22  * notice, this list of conditions and the following disclaimer in the
  23  * documentation and/or other materials provided with the distribution;
  24  * neither the name of the copyright holders nor the names of its
  25  * contributors may be used to endorse or promote products derived from
  26  * this software without specific prior written permission.
  27  *
  28  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  29  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  30  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  31  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  32  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  33  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  34  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  35  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  36  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  37  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  38  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  39  *
  40  * Authors: Nathan Binkert
  41  *          Erik Hallnor
  42  *          Steve Reinhardt
  43  *          Andreas Sandberg
  44  */
  45
  46 /* @file
  47  * Serialization Interface Declarations
  48  */
  49
  50 #ifndef __SERIALIZE_HH__
  51 #define __SERIALIZE_HH__
  52
  53
  54 #include <iostream>
  55 #include <list>
  56 #include <map>
  57 #include <stack>
  58 #include <vector>
  59
  60 #include "base/bitunion.hh"
  61 #include "base/types.hh"
  62
  63 class IniFile;
  64 class Serializable;
  65 class CheckpointIn;
  66 class SimObject;
  67 class SimObjectResolver;
  68 class EventQueue;
  69
  70 typedef std::ostream CheckpointOut;
  71
  72
  73 /** The current version of the checkpoint format.
  74  * This should be incremented by 1 and only 1 for every new version, where a new
  75  * version is defined as a checkpoint created before this version won't work on
  76  * the current version until the checkpoint format is updated. Adding a new
  77  * SimObject shouldn't cause the version number to increase, only changes to
  78  * existing objects such as serializing/unserializing more state, changing sizes
  79  * of serialized arrays, etc. */
  80 static const uint64_t gem5CheckpointVersion = 0x000000000000000f;
  81
  82 template <class T>
  83 void paramOut(CheckpointOut &cp, const std::string &name, const T &param);
  84
  85 template <typename DataType, typename BitUnion>
  86 void paramOut(CheckpointOut &cp, const std::string &name,
  87               const BitfieldBackend::BitUnionOperators<DataType, BitUnion> &p)
  88 {
  89     paramOut(cp, name, p.__data);
  90 }
  91
  92 template <class T>
  93 void paramIn(CheckpointIn &cp, const std::string &name, T &param);
  94
  95 template <typename DataType, typename BitUnion>
  96 void paramIn(CheckpointIn &cp, const std::string &name,
  97              BitfieldBackend::BitUnionOperators<DataType, BitUnion> &p)
  98 {
  99     paramIn(cp, name, p.__data);
 100 }
 101
 102 template <class T>
 103 bool optParamIn(CheckpointIn &cp, const std::string &name, T &param);
 104
 105 template <typename DataType, typename BitUnion>
 106 bool optParamIn(CheckpointIn &cp, const std::string &name,
 107                 BitfieldBackend::BitUnionOperators<DataType, BitUnion> &p)
 108 {
 109     return optParamIn(cp, name, p.__data);
 110 }
 111
 112 template <class T>
 113 void arrayParamOut(CheckpointOut &cp, const std::string &name,
 114                    const T *param, unsigned size);
 115
 116 template <class T>
 117 void arrayParamOut(CheckpointOut &cp, const std::string &name,
 118                    const std::vector<T> &param);
 119
 120 template <class T>
 121 void arrayParamOut(CheckpointOut &cp, const std::string &name,
 122                    const std::list<T> &param);
 123
 124 template <class T>
 125 void arrayParamIn(CheckpointIn &cp, const std::string &name,
 126                   T *param, unsigned size);
 127
 128 template <class T>
 129 void arrayParamIn(CheckpointIn &cp, const std::string &name,
 130                   std::vector<T> &param);
 131
 132 template <class T>
 133 void arrayParamIn(CheckpointIn &cp, const std::string &name,
 134                   std::list<T> &param);
 135
 136 void
 137 objParamIn(CheckpointIn &cp, const std::string &name, SimObject * &param);
 138
 139 //
 140 // These macros are streamlined to use in serialize/unserialize
 141 // functions.  It's assumed that serialize() has a parameter 'os' for
 142 // the ostream, and unserialize() has parameters 'cp' and 'section'.
 143 #define SERIALIZE_SCALAR(scalar)        paramOut(cp, #scalar, scalar)
 144
 145 #define UNSERIALIZE_SCALAR(scalar)      paramIn(cp, #scalar, scalar)
 146 #define UNSERIALIZE_OPT_SCALAR(scalar)      optParamIn(cp, #scalar, scalar)
 147
 148 // ENUMs are like SCALARs, but we cast them to ints on the way out
 149 #define SERIALIZE_ENUM(scalar)          paramOut(cp, #scalar, (int)scalar)
 150
 151 #define UNSERIALIZE_ENUM(scalar)                        \
 152     do {                                                \
 153         int tmp;                                        \
 154         paramIn(cp, #scalar, tmp);                      \
 155         scalar = static_cast<decltype(scalar)>(tmp);    \
 156     } while (0)
 157
 158 #define SERIALIZE_ARRAY(member, size)           \
 159         arrayParamOut(cp, #member, member, size)
 160
 161 #define UNSERIALIZE_ARRAY(member, size)         \
 162         arrayParamIn(cp, #member, member, size)
 163
 164 #define SERIALIZE_CONTAINER(member)             \
 165         arrayParamOut(cp, #member, member)
 166
 167 #define UNSERIALIZE_CONTAINER(member)           \
 168         arrayParamIn(cp, #member, member)
 169
 170 #define SERIALIZE_EVENT(event) event.serializeSection(cp, #event);
 171
 172 #define UNSERIALIZE_EVENT(event)                        \
 173     do {                                                \
 174         event.unserializeSection(cp, #event);           \
 175         eventQueue()->checkpointReschedule(&event);     \
 176     } while(0)
 177
 178 #define SERIALIZE_OBJ(obj) obj.serializeSection(cp, #obj)
 179 #define UNSERIALIZE_OBJ(obj) obj.unserializeSection(cp, #obj)
 180
 181 #define SERIALIZE_OBJPTR(objptr)        paramOut(cp, #objptr, (objptr)->name())
 182
 183 #define UNSERIALIZE_OBJPTR(objptr)                      \
 184     do {                                                \
 185         SimObject *sptr;                                \
 186         objParamIn(cp, #objptr, sptr);                  \
 187         objptr = dynamic_cast<decltype(objptr)>(sptr);  \
 188     } while (0)
 189
 190 /**
 191  * Basic support for object serialization.
 192  *
 193  * Objects that support serialization should derive from this
 194  * class. Such objects can largely be divided into two categories: 1)
 195  * True SimObjects (deriving from SimObject), and 2) child objects
 196  * (non-SimObjects).
 197  *
 198  * SimObjects are serialized automatically into their own sections
 199  * automatically by the SimObject base class (see
 200  * SimObject::serializeAll().
 201  *
 202  * SimObjects can contain other serializable objects that are not
 203  * SimObjects. Much like normal serialized members are not serialized
 204  * automatically, these objects will not be serialized automatically
 205  * and it is expected that the objects owning such serializable
 206  * objects call the required serialization/unserialization methods on
 207  * child objects. The preferred method to serialize a child object is
 208  * to call serializeSection() on the child, which serializes the
 209  * object into a new subsection in the current section. Another option
 210  * is to call serialize() directly, which serializes the object into
 211  * the current section. The latter is not recommended as it can lead
 212  * to naming clashes between objects.
 213  *
 214  * @note Many objects that support serialization need to be put in a
 215  * consistent state when serialization takes place. We refer to the
 216  * action of forcing an object into a consistent state as
 217  * 'draining'. Objects that need draining inherit from Drainable. See
 218  * Drainable for more information.
 219  */
 220 class Serializable
 221 {
 222   protected:
 223     /**
 224      * Scoped checkpoint section helper class
 225      *
 226      * This helper class creates a section within a checkpoint without
 227      * the need for a separate serializeable object. It is mainly used
 228      * within the Serializable class when serializing or unserializing
 229      * section (see serializeSection() and unserializeSection()). It
 230      * can also be used to maintain backwards compatibility in
 231      * existing code that serializes structs that are not inheriting
 232      * from Serializable into subsections.
 233      *
 234      * When the class is instantiated, it appends a name to the active
 235      * path in a checkpoint. The old path is later restored when the
 236      * instance is destroyed. For example, serializeSection() could be
 237      * implemented by instantiating a ScopedCheckpointSection and then
 238      * calling serialize() on an object.
 239      */
 240     class ScopedCheckpointSection {
 241       public:
 242         template<class CP>
 243         ScopedCheckpointSection(CP &cp, const char *name) {
 244             pushName(name);
 245             nameOut(cp);
 246         }
 247
 248         template<class CP>
 249         ScopedCheckpointSection(CP &cp, const std::string &name) {
 250             pushName(name.c_str());
 251             nameOut(cp);
 252         }
 253
 254         ~ScopedCheckpointSection();
 255
 256         ScopedCheckpointSection() = delete;
 257         ScopedCheckpointSection(const ScopedCheckpointSection &) = delete;
 258         ScopedCheckpointSection &operator=(
 259             const ScopedCheckpointSection &) = delete;
 260         ScopedCheckpointSection &operator=(
 261             ScopedCheckpointSection &&) = delete;
 262
 263       private:
 264         void pushName(const char *name);
 265         void nameOut(CheckpointOut &cp);
 266         void nameOut(CheckpointIn &cp) {};
 267     };
 268
 269   public:
 270     Serializable();
 271     virtual ~Serializable();
 272
 273     /**
 274      * Serialize an object
 275      *
 276      * Output an object's state into the current checkpoint section.
 277      *
 278      * @param cp Checkpoint state
 279      */
 280     virtual void serialize(CheckpointOut &cp) const = 0;
 281
 282     /**
 283      * Unserialize an object
 284      *
 285      * Read an object's state from the current checkpoint section.
 286      *
 287      * @param cp Checkpoint state
 288      */
 289     virtual void unserialize(CheckpointIn &cp) = 0;
 290
 291     /**
 292      * Serialize an object into a new section
 293      *
 294      * This method creates a new section in a checkpoint and calls
 295      * serialize() to serialize the current object into that
 296      * section. The name of the section is appended to the current
 297      * checkpoint path.
 298      *
 299      * @param cp Checkpoint state
 300      * @param name Name to append to the active path
 301      */
 302     void serializeSection(CheckpointOut &cp, const char *name) const;
 303
 304     void serializeSection(CheckpointOut &cp, const std::string &name) const {
 305         serializeSection(cp, name.c_str());
 306     }
 307
 308     /**
 309      * Unserialize an a child object
 310      *
 311      * This method loads a child object from a checkpoint. The object
 312      * name is appended to the active path to form a fully qualified
 313      * section name and unserialize() is called.
 314      *
 315      * @param cp Checkpoint state
 316      * @param name Name to append to the active path
 317      */
 318     void unserializeSection(CheckpointIn &cp, const char *name);
 319
 320     void unserializeSection(CheckpointIn &cp, const std::string &name) {
 321         unserializeSection(cp, name.c_str());
 322     }
 323
 324     /**
 325      * @{
 326      * @name Legacy interface
 327      *
 328      * Interface for objects that insist on changing their state when
 329      * serializing. Such state change should be done in drain(),
 330      * memWriteback(), or memInvalidate() and not in the serialization
 331      * method. In general, if state changes occur in serialize, it
 332      * complicates testing since it breaks assumptions about draining
 333      * and serialization. It potentially also makes components more
 334      * fragile since they there are no ordering guarantees when
 335      * serializing SimObjects.
 336      *
 337      * @warn This interface is considered deprecated and should never
 338      * be used.
 339      */
 340
 341     virtual void serializeOld(CheckpointOut &cp) {
 342         serialize(cp);
 343     }
 344     void serializeSectionOld(CheckpointOut &cp, const char *name);
 345     void serializeSectionOld(CheckpointOut &cp, const std::string &name) {
 346         serializeSectionOld(cp, name.c_str());
 347     }
 348     /** @} */
 349
 350     /** Get the fully-qualified name of the active section */
 351     static const std::string &currentSection();
 352
 353     static Serializable *create(CheckpointIn &cp, const std::string &section);
 354
 355     static int ckptCount;
 356     static int ckptMaxCount;
 357     static int ckptPrevCount;
 358     static void serializeAll(const std::string &cpt_dir);
 359     static void unserializeGlobals(CheckpointIn &cp);
 360
 361   private:
 362     static std::stack<std::string> path;
 363 };
 364
 365 void debug_serialize(const std::string &cpt_dir);
 366
 367 //
 368 // An instance of SerializableClass corresponds to a class derived from
 369 // Serializable.  The SerializableClass instance serves to bind the string
 370 // name (found in the config file) to a function that creates an
 371 // instance of the appropriate derived class.
 372 //
 373 // This would be much cleaner in Smalltalk or Objective-C, where types
 374 // are first-class objects themselves.
 375 //
 376 class SerializableClass
 377 {
 378   public:
 379
 380     // Type CreateFunc is a pointer to a function that creates a new
 381     // simulation object builder based on a .ini-file parameter
 382     // section (specified by the first string argument), a unique name
 383     // for the object (specified by the second string argument), and
 384     // an optional config hierarchy node (specified by the third
 385     // argument).  A pointer to the new SerializableBuilder is returned.
 386     typedef Serializable *(*CreateFunc)(CheckpointIn &cp,
 387                                         const std::string &section);
 388
 389     static std::map<std::string,CreateFunc> *classMap;
 390
 391     // Constructor.  For example:
 392     //
 393     // SerializableClass baseCacheSerializableClass("BaseCacheSerializable",
 394     //                         newBaseCacheSerializableBuilder);
 395     //
 396     SerializableClass(const std::string &className, CreateFunc createFunc);
 397
 398     // create Serializable given name of class and pointer to
 399     // configuration hierarchy node
 400     static Serializable *createObject(CheckpointIn &cp,
 401                                       const std::string &section);
 402 };
 403
 404 //
 405 // Macros to encapsulate the magic of declaring & defining
 406 // SerializableBuilder and SerializableClass objects
 407 //
 408
 409 #define REGISTER_SERIALIZEABLE(CLASS_NAME, OBJ_CLASS)                      \
 410 SerializableClass the##OBJ_CLASS##Class(CLASS_NAME,                        \
 411                                          OBJ_CLASS::createForUnserialize);
 412
 413
 414 class CheckpointIn
 415 {
 416   private:
 417
 418     IniFile *db;
 419
 420     SimObjectResolver &objNameResolver;
 421
 422   public:
 423     CheckpointIn(const std::string &cpt_dir, SimObjectResolver &resolver);
 424     ~CheckpointIn();
 425
 426     const std::string cptDir;
 427
 428     bool find(const std::string &section, const std::string &entry,
 429               std::string &value);
 430
 431     bool findObj(const std::string &section, const std::string &entry,
 432                  SimObject *&value);
 433
 434     bool sectionExists(const std::string &section);
 435
 436     // The following static functions have to do with checkpoint
 437     // creation rather than restoration.  This class makes a handy
 438     // namespace for them though.  Currently no Checkpoint object is
 439     // created on serialization (only unserialization) so we track the
 440     // directory name as a global.  It would be nice to change this
 441     // someday
 442
 443   private:
 444     // current directory we're serializing into.
 445     static std::string currentDirectory;
 446
 447   public:
 448     // Set the current directory.  This function takes care of
 449     // inserting curTick() if there's a '%d' in the argument, and
 450     // appends a '/' if necessary.  The final name is returned.
 451     static std::string setDir(const std::string &base_name);
 452
 453     // Export current checkpoint directory name so other objects can
 454     // derive filenames from it (e.g., memory).  The return value is
 455     // guaranteed to end in '/' so filenames can be directly appended.
 456     // This function is only valid while a checkpoint is being created.
 457     static std::string dir();
 458
 459     // Filename for base checkpoint file within directory.
 460     static const char *baseFilename;
 461 };
 462
 463 #endif // __SERIALIZE_HH__