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 <set>
  59 #include <vector>
  60
  61 #include "base/bitunion.hh"
  62
  63 class CheckpointIn;
  64 class IniFile;
  65 class Serializable;
  66 class SimObject;
  67 class SimObjectResolver;
  68
  69 typedef std::ostream CheckpointOut;
  70
  71
  72 template <class T>
  73 void paramOut(CheckpointOut &cp, const std::string &name, const T &param);
  74
  75 template <typename DataType, typename BitUnion>
  76 void paramOut(CheckpointOut &cp, const std::string &name,
  77               const BitfieldBackend::BitUnionOperators<DataType, BitUnion> &p)
  78 {
  79     paramOut(cp, name, p.__data);
  80 }
  81
  82 template <class T>
  83 void paramIn(CheckpointIn &cp, const std::string &name, T &param);
  84
  85 template <typename DataType, typename BitUnion>
  86 void paramIn(CheckpointIn &cp, const std::string &name,
  87              BitfieldBackend::BitUnionOperators<DataType, BitUnion> &p)
  88 {
  89     paramIn(cp, name, p.__data);
  90 }
  91
  92 template <class T>
  93 bool optParamIn(CheckpointIn &cp, const std::string &name, T &param,
  94                 bool warn = true);
  95
  96 template <typename DataType, typename BitUnion>
  97 bool optParamIn(CheckpointIn &cp, const std::string &name,
  98                 BitfieldBackend::BitUnionOperators<DataType, BitUnion> &p,
  99                 bool warn = true)
 100 {
 101     return optParamIn(cp, name, p.__data, warn);
 102 }
 103
 104 template <class T>
 105 void arrayParamOut(CheckpointOut &cp, const std::string &name,
 106                    const T *param, unsigned size);
 107
 108 template <class T>
 109 void arrayParamOut(CheckpointOut &cp, const std::string &name,
 110                    const std::vector<T> &param);
 111
 112 template <class T>
 113 void arrayParamOut(CheckpointOut &cp, const std::string &name,
 114                    const std::list<T> &param);
 115
 116 template <class T>
 117 void arrayParamOut(CheckpointOut &cp, const std::string &name,
 118                    const std::set<T> &param);
 119
 120 template <class T>
 121 void arrayParamIn(CheckpointIn &cp, const std::string &name,
 122                   T *param, unsigned size);
 123
 124 template <class T>
 125 void arrayParamIn(CheckpointIn &cp, const std::string &name,
 126                   std::vector<T> &param);
 127
 128 template <class T>
 129 void arrayParamIn(CheckpointIn &cp, const std::string &name,
 130                   std::list<T> &param);
 131
 132 template <class T>
 133 void arrayParamIn(CheckpointIn &cp, const std::string &name,
 134                   std::set<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     /** Get the fully-qualified name of the active section */
 325     static const std::string &currentSection();
 326
 327     static int ckptCount;
 328     static int ckptMaxCount;
 329     static int ckptPrevCount;
 330     static void serializeAll(const std::string &cpt_dir);
 331     static void unserializeGlobals(CheckpointIn &cp);
 332
 333   private:
 334     static std::stack<std::string> path;
 335 };
 336
 337 void debug_serialize(const std::string &cpt_dir);
 338
 339
 340 class CheckpointIn
 341 {
 342   private:
 343
 344     IniFile *db;
 345
 346     SimObjectResolver &objNameResolver;
 347
 348   public:
 349     CheckpointIn(const std::string &cpt_dir, SimObjectResolver &resolver);
 350     ~CheckpointIn();
 351
 352     const std::string cptDir;
 353
 354     bool find(const std::string &section, const std::string &entry,
 355               std::string &value);
 356
 357     bool findObj(const std::string &section, const std::string &entry,
 358                  SimObject *&value);
 359
 360
 361     bool entryExists(const std::string &section, const std::string &entry);
 362     bool sectionExists(const std::string &section);
 363
 364     // The following static functions have to do with checkpoint
 365     // creation rather than restoration.  This class makes a handy
 366     // namespace for them though.  Currently no Checkpoint object is
 367     // created on serialization (only unserialization) so we track the
 368     // directory name as a global.  It would be nice to change this
 369     // someday
 370
 371   private:
 372     // current directory we're serializing into.
 373     static std::string currentDirectory;
 374
 375   public:
 376     // Set the current directory.  This function takes care of
 377     // inserting curTick() if there's a '%d' in the argument, and
 378     // appends a '/' if necessary.  The final name is returned.
 379     static std::string setDir(const std::string &base_name);
 380
 381     // Export current checkpoint directory name so other objects can
 382     // derive filenames from it (e.g., memory).  The return value is
 383     // guaranteed to end in '/' so filenames can be directly appended.
 384     // This function is only valid while a checkpoint is being created.
 385     static std::string dir();
 386
 387     // Filename for base checkpoint file within directory.
 388     static const char *baseFilename;
 389 };
 390
 391 #endif // __SERIALIZE_HH__