src/sim/serialize.hh

   1 /*
   2  * Copyright (c) 2015, 2018, 2020 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
  41 /* @file
  42  * Serialization Interface Declarations
  43  */
  44
  45 #ifndef __SERIALIZE_HH__
  46 #define __SERIALIZE_HH__
  47
  48
  49 #include <algorithm>
  50 #include <iostream>
  51 #include <iterator>
  52 #include <stack>
  53 #include <set>
  54 #include <type_traits>
  55 #include <unordered_map>
  56 #include <vector>
  57
  58 #include "base/inifile.hh"
  59 #include "base/logging.hh"
  60 #include "sim/serialize_handlers.hh"
  61
  62 class IniFile;
  63 class SimObject;
  64 class SimObjectResolver;
  65
  66 typedef std::ostream CheckpointOut;
  67
  68 class CheckpointIn
  69 {
  70   private:
  71
  72     IniFile *db;
  73
  74     SimObjectResolver &objNameResolver;
  75
  76     const std::string _cptDir;
  77
  78   public:
  79     CheckpointIn(const std::string &cpt_dir, SimObjectResolver &resolver);
  80     ~CheckpointIn();
  81
  82     /**
  83      * @return Returns the current directory being used for creating
  84      * checkpoints or restoring checkpoints.
  85      * @ingroup api_serialize
  86      * @{
  87      */
  88     const std::string getCptDir() { return _cptDir; }
  89
  90     bool find(const std::string &section, const std::string &entry,
  91               std::string &value);
  92
  93     bool findObj(const std::string &section, const std::string &entry,
  94                  SimObject *&value);
  95
  96     bool entryExists(const std::string &section, const std::string &entry);
  97     bool sectionExists(const std::string &section);
  98     void visitSection(const std::string &section,
  99         IniFile::VisitSectionCallback cb);
 100     /** @}*/ //end of api_checkout group
 101
 102     // The following static functions have to do with checkpoint
 103     // creation rather than restoration.  This class makes a handy
 104     // namespace for them though.  Currently no Checkpoint object is
 105     // created on serialization (only unserialization) so we track the
 106     // directory name as a global.  It would be nice to change this
 107     // someday
 108
 109   private:
 110     // current directory we're serializing into.
 111     static std::string currentDirectory;
 112
 113
 114   public:
 115     /**
 116      * Set the current directory
 117      *
 118      * This function takes care of inserting curTick() if there's a '%d' in the
 119      * argument, and appends a '/' if necessary. The final name is returned.
 120      *
 121      * @ingroup api_serialize
 122      */
 123     static std::string setDir(const std::string &base_name);
 124
 125     /**
 126      * Get the current checkout directory name
 127      *
 128      * This function exports the current checkout point directory name so other
 129      * objects can derive filenames from it (e.g., memory). The return value is
 130      * guaranteed to end in '/' so filenames can be directly appended. This
 131      * function is only valid while a checkpoint is being created.
 132      *
 133      * @ingroup api_serialize
 134      */
 135     static std::string dir();
 136
 137     // Filename for base checkpoint file within directory.
 138     static const char *baseFilename;
 139 };
 140
 141 /**
 142  * Basic support for object serialization.
 143  *
 144  * The Serailizable interface is used to create checkpoints. Any
 145  * object that implements this interface can be included in
 146  * gem5's checkpointing system.
 147  *
 148  * Objects that support serialization should derive from this
 149  * class. Such objects can largely be divided into two categories: 1)
 150  * True SimObjects (deriving from SimObject), and 2) child objects
 151  * (non-SimObjects).
 152  *
 153  * SimObjects are serialized automatically into their own sections
 154  * automatically by the SimObject base class (see
 155  * SimObject::serializeAll().
 156  *
 157  * SimObjects can contain other serializable objects that are not
 158  * SimObjects. Much like normal serialized members are not serialized
 159  * automatically, these objects will not be serialized automatically
 160  * and it is expected that the objects owning such serializable
 161  * objects call the required serialization/unserialization methods on
 162  * child objects. The preferred method to serialize a child object is
 163  * to call serializeSection() on the child, which serializes the
 164  * object into a new subsection in the current section. Another option
 165  * is to call serialize() directly, which serializes the object into
 166  * the current section. The latter is not recommended as it can lead
 167  * to naming clashes between objects.
 168  *
 169  * @note Many objects that support serialization need to be put in a
 170  * consistent state when serialization takes place. We refer to the
 171  * action of forcing an object into a consistent state as
 172  * 'draining'. Objects that need draining inherit from Drainable. See
 173  * Drainable for more information.
 174  */
 175 class Serializable
 176 {
 177   public:
 178     class ScopedCheckpointSection {
 179       public:
 180         /**
 181          * This is the constructor for Scoped checkpoint section helper
 182          * class.
 183          *
 184          * Scoped checkpoint helper class creates a section within a
 185          * checkpoint without the need for a separate serializeable
 186          * object. It is mainly used within the Serializable class
 187          * when serializing or unserializing section (see
 188          * serializeSection() and unserializeSection()). It
 189          * can also be used to maintain backwards compatibility in
 190          * existing code that serializes structs that are not inheriting
 191          * from Serializable into subsections.
 192          *
 193          * When the class is instantiated, it appends a name to the active
 194          * path in a checkpoint. The old path is later restored when the
 195          * instance is destroyed. For example, serializeSection() could be
 196          * implemented by instantiating a ScopedCheckpointSection and then
 197          * calling serialize() on an object.
 198          *
 199          * @ingroup api_serialize
 200          * @{
 201          */
 202         template<class CP>
 203         ScopedCheckpointSection(CP &cp, const char *name) {
 204             pushName(name);
 205             nameOut(cp);
 206         }
 207
 208         template<class CP>
 209         ScopedCheckpointSection(CP &cp, const std::string &name) {
 210             pushName(name.c_str());
 211             nameOut(cp);
 212         }
 213         /** @}*/ //end of api_serialize group
 214
 215         ~ScopedCheckpointSection();
 216
 217         ScopedCheckpointSection() = delete;
 218         ScopedCheckpointSection(const ScopedCheckpointSection &) = delete;
 219         ScopedCheckpointSection &operator=(
 220             const ScopedCheckpointSection &) = delete;
 221         ScopedCheckpointSection &operator=(
 222             ScopedCheckpointSection &&) = delete;
 223
 224       private:
 225         void pushName(const char *name);
 226         void nameOut(CheckpointOut &cp);
 227         void nameOut(CheckpointIn &cp) {};
 228     };
 229
 230     /**
 231      * @ingroup api_serialize
 232      */
 233     Serializable();
 234     virtual ~Serializable();
 235
 236     /**
 237      * Serialize an object
 238      *
 239      * Output an object's state into the current checkpoint section.
 240      *
 241      * @param cp Checkpoint state
 242      *
 243      * @ingroup api_serialize
 244      */
 245     virtual void serialize(CheckpointOut &cp) const = 0;
 246
 247     /**
 248      * Unserialize an object
 249      *
 250      * Read an object's state from the current checkpoint section.
 251      *
 252      * @param cp Checkpoint state
 253      *
 254      * @ingroup api_serialize
 255      */
 256     virtual void unserialize(CheckpointIn &cp) = 0;
 257
 258     /**
 259      * Serialize an object into a new section
 260      *
 261      * This method creates a new section in a checkpoint and calls
 262      * serialize() to serialize the current object into that
 263      * section. The name of the section is appended to the current
 264      * checkpoint path.
 265      *
 266      * @param cp Checkpoint state
 267      * @param name Name to append to the active path
 268      *
 269      * @ingroup api_serialize
 270      */
 271     void serializeSection(CheckpointOut &cp, const char *name) const;
 272
 273     /**
 274      * @ingroup api_serialize
 275      */
 276     void serializeSection(CheckpointOut &cp, const std::string &name) const {
 277         serializeSection(cp, name.c_str());
 278     }
 279
 280     /**
 281      * Unserialize an a child object
 282      *
 283      * This method loads a child object from a checkpoint. The object
 284      * name is appended to the active path to form a fully qualified
 285      * section name and unserialize() is called.
 286      *
 287      * @param cp Checkpoint state
 288      * @param name Name to append to the active path
 289      *
 290      * @ingroup api_serialize
 291      */
 292     void unserializeSection(CheckpointIn &cp, const char *name);
 293
 294     /**
 295      * @ingroup api_serialize
 296      */
 297     void unserializeSection(CheckpointIn &cp, const std::string &name) {
 298         unserializeSection(cp, name.c_str());
 299     }
 300
 301     /**
 302      * Gets the fully-qualified name of the active section
 303      *
 304      * @ingroup api_serialize
 305      */
 306     static const std::string &currentSection();
 307
 308     /**
 309      * Serializes all the SimObjects.
 310      *
 311      * @ingroup api_serialize
 312      */
 313     static void serializeAll(const std::string &cpt_dir);
 314
 315     /**
 316      * @ingroup api_serialize
 317      */
 318     static void unserializeGlobals(CheckpointIn &cp);
 319
 320   private:
 321     static std::stack<std::string> path;
 322 };
 323
 324 /**
 325  * This function is used for writing parameters to a checkpoint.
 326  * @param os The checkpoint to be written to.
 327  * @param name Name of the parameter to be set.
 328  * @param param Value of the parameter to be written.
 329  * @ingroup api_serialize
 330  */
 331 template <class T>
 332 void
 333 paramOut(CheckpointOut &os, const std::string &name, const T &param)
 334 {
 335     os << name << "=";
 336     ShowParam<T>::show(os, param);
 337     os << "\n";
 338 }
 339
 340 template <class T>
 341 bool
 342 paramInImpl(CheckpointIn &cp, const std::string &name, T &param)
 343 {
 344     const std::string &section(Serializable::currentSection());
 345     std::string str;
 346     return cp.find(section, name, str) && ParseParam<T>::parse(str, param);
 347 }
 348
 349 /**
 350  * This function is used for restoring optional parameters from the
 351  * checkpoint.
 352  * @param cp The checkpoint to be read from.
 353  * @param name Name of the parameter to be read.
 354  * @param param Value of the parameter to be read.
 355  * @param do_warn If the warn is set to true then the function prints the
 356  * warning message.
 357  * @return Returns if the parameter existed in the checkpoint.
 358  *
 359  * @ingroup api_serialize
 360  */
 361 template <class T>
 362 bool
 363 optParamIn(CheckpointIn &cp, const std::string &name, T &param,
 364            bool do_warn=true)
 365 {
 366     if (paramInImpl(cp, name, param))
 367         return true;
 368
 369     warn_if(do_warn, "optional parameter %s:%s not present",
 370             Serializable::currentSection(), name);
 371     return false;
 372 }
 373
 374 /**
 375  * This function is used for restoring parameters from a checkpoint.
 376  * @param os The checkpoint to be restored from.
 377  * @param name Name of the parameter to be set.
 378  * @param param Value of the parameter to be restored.
 379  * @ingroup api_serialize
 380  */
 381 template <class T>
 382 void
 383 paramIn(CheckpointIn &cp, const std::string &name, T &param)
 384 {
 385     fatal_if(!paramInImpl(cp, name, param),
 386         "Can't unserialize '%s:%s'", Serializable::currentSection(), name);
 387 }
 388
 389 /**
 390  * @ingroup api_serialize
 391  */
 392 template <class InputIterator>
 393 void
 394 arrayParamOut(CheckpointOut &os, const std::string &name,
 395               InputIterator start, InputIterator end)
 396 {
 397     os << name << "=";
 398     auto it = start;
 399     using Elem = std::remove_cv_t<std::remove_reference_t<decltype(*it)>>;
 400     if (it != end)
 401         ShowParam<Elem>::show(os, *it++);
 402     while (it != end) {
 403         os << " ";
 404         ShowParam<Elem>::show(os, *it++);
 405     }
 406     os << "\n";
 407 }
 408
 409 /**
 410  * @ingroup api_serialize
 411  */
 412 template <class T>
 413 decltype(std::begin(std::declval<const T&>()),
 414          std::end(std::declval<const T&>()), void())
 415 arrayParamOut(CheckpointOut &os, const std::string &name,
 416               const T &param)
 417 {
 418     arrayParamOut(os, name, std::begin(param), std::end(param));
 419 }
 420
 421
 422 /**
 423  * @ingroup api_serialize
 424  */
 425 template <class T>
 426 void
 427 arrayParamOut(CheckpointOut &os, const std::string &name,
 428               const T *param, unsigned size)
 429 {
 430     arrayParamOut(os, name, param, param + size);
 431 }
 432
 433 /**
 434  * Extract values stored in the checkpoint, and assign them to the provided
 435  * array container.
 436  *
 437  * @param cp The checkpoint to be parsed.
 438  * @param name Name of the container.
 439  * @param param The array container.
 440  * @param size The expected number of entries to be extracted.
 441  *
 442  * @ingroup api_serialize
 443  */
 444
 445 template <class T, class InsertIterator>
 446 void
 447 arrayParamIn(CheckpointIn &cp, const std::string &name,
 448              InsertIterator inserter, ssize_t fixed_size=-1)
 449 {
 450     const std::string &section = Serializable::currentSection();
 451     std::string str;
 452     fatal_if(!cp.find(section, name, str),
 453         "Can't unserialize '%s:%s'.", section, name);
 454
 455     std::vector<std::string> tokens;
 456     tokenize(tokens, str, ' ');
 457
 458     fatal_if(fixed_size >= 0 && tokens.size() != fixed_size,
 459              "Array size mismatch on %s:%s (Got %u, expected %u)'\n",
 460              section, name, tokens.size(), fixed_size);
 461
 462     for (const auto &token: tokens) {
 463         T value;
 464         fatal_if(!ParseParam<T>::parse(token, value),
 465                  "Could not parse \"%s\".", str);
 466         *inserter = value;
 467     }
 468 }
 469
 470 /**
 471  * @ingroup api_serialize
 472  */
 473 template <class T>
 474 decltype(std::declval<T>().insert(std::declval<typename T::value_type>()),
 475          void())
 476 arrayParamIn(CheckpointIn &cp, const std::string &name, T &param)
 477 {
 478     param.clear();
 479     arrayParamIn<typename T::value_type>(
 480             cp, name, std::inserter(param, param.begin()));
 481 }
 482
 483 /**
 484  * @ingroup api_serialize
 485  */
 486 template <class T>
 487 decltype(std::declval<T>().push_back(std::declval<typename T::value_type>()),
 488          void())
 489 arrayParamIn(CheckpointIn &cp, const std::string &name, T &param)
 490 {
 491     param.clear();
 492     arrayParamIn<typename T::value_type>(cp, name, std::back_inserter(param));
 493 }
 494
 495 /**
 496  * @ingroup api_serialize
 497  */
 498 template <class T>
 499 void
 500 arrayParamIn(CheckpointIn &cp, const std::string &name,
 501              T *param, unsigned size)
 502 {
 503     struct ArrayInserter
 504     {
 505         T *data;
 506         T &operator *() { return *data++; }
 507     } insert_it{param};
 508
 509     arrayParamIn<T>(cp, name, insert_it, size);
 510 }
 511
 512 void
 513 debug_serialize(const std::string &cpt_dir);
 514
 515
 516 /**
 517  * @ingroup api_serialize
 518  */
 519 void
 520 objParamIn(CheckpointIn &cp, const std::string &name, SimObject * &param);
 521
 522 /**
 523  * Serialize a mapping represented as two arrays: one containing names
 524  * and the other containing values.
 525  *
 526  * @param names array of keys
 527  * @param param array of values
 528  * @param size size of the names and param arrays
 529  */
 530 template <class T>
 531 void
 532 mappingParamOut(CheckpointOut &os, const char* sectionName,
 533     const char* const names[], const T *param, unsigned size)
 534 {
 535     Serializable::ScopedCheckpointSection sec(os, sectionName);
 536     for (unsigned i = 0; i < size; ++i) {
 537         paramOut(os, names[i], param[i]);
 538     }
 539 }
 540
 541 /**
 542  * Restore mappingParamOut. Keys missing from the checkpoint are ignored.
 543  */
 544 template <class T>
 545 void
 546 mappingParamIn(CheckpointIn &cp, const char* sectionName,
 547     const char* const names[], T *param, unsigned size)
 548 {
 549     Serializable::ScopedCheckpointSection sec(cp, sectionName);
 550     std::unordered_map<std::string, size_t> name_to_index;
 551     for (size_t i = 0; i < size; i++) {
 552         name_to_index[names[i]] = i;
 553     }
 554     for (size_t i = 0; i < size; i++) {
 555         auto& key = names[i];
 556         T value;
 557         if (optParamIn(cp, key, value)) {
 558             param[name_to_index[key]] = value;
 559         }
 560     }
 561     cp.visitSection(
 562         Serializable::currentSection(),
 563         [name_to_index](const std::string& key, const std::string& val)
 564         {
 565             if (!name_to_index.count(key)) {
 566                 warn("unknown entry found in checkpoint: %s %s %s\n",
 567                     Serializable::currentSection(), key, val);
 568             }
 569         }
 570     );
 571 }
 572
 573 //
 574 // These macros are streamlined to use in serialize/unserialize
 575 // functions.  It's assumed that serialize() has a parameter 'os' for
 576 // the ostream, and unserialize() has parameters 'cp' and 'section'.
 577
 578
 579 /**
 580  * \def SERIALIZE_SCALER(scaler)
 581  *
 582  * @ingroup api_serialize
 583  */
 584 #define SERIALIZE_SCALAR(scalar)        paramOut(cp, #scalar, scalar)
 585
 586 /**
 587  * \def UNSERIALIZE_SCALER(scalar)
 588  *
 589  * @ingroup api_serialize
 590  */
 591 #define UNSERIALIZE_SCALAR(scalar)      paramIn(cp, #scalar, scalar)
 592
 593 /**
 594  * \def UNSERIALIZE_OPT_SCALAR(scalar)
 595  *
 596  * @ingroup api_serialize
 597  */
 598 #define UNSERIALIZE_OPT_SCALAR(scalar)      optParamIn(cp, #scalar, scalar)
 599
 600 // ENUMs are like SCALARs, but we cast them to ints on the way out
 601
 602 /**
 603  * \def SERIALIZE_ENUM(scalar)
 604  *
 605  * @ingroup api_serialize
 606  */
 607 #define SERIALIZE_ENUM(scalar)          paramOut(cp, #scalar, (int)scalar)
 608
 609 /**
 610  * \def UNSERIALIZE_ENUM(scaler)
 611  *
 612  * @ingroup api_serialize
 613  */
 614 #define UNSERIALIZE_ENUM(scalar)                        \
 615     do {                                                \
 616         int tmp;                                        \
 617         paramIn(cp, #scalar, tmp);                      \
 618         scalar = static_cast<decltype(scalar)>(tmp);    \
 619     } while (0)
 620
 621 /**
 622  * \def SERIALIZE_ARRAY(member, size)
 623  *
 624  * @ingroup api_serialize
 625  */
 626 #define SERIALIZE_ARRAY(member, size)           \
 627         arrayParamOut(cp, #member, member, size)
 628
 629 /**
 630  * \def UNSERIALIZE_ARRAY(member, size)
 631  *
 632  * @ingroup api_serialize
 633  */
 634 #define UNSERIALIZE_ARRAY(member, size)         \
 635         arrayParamIn(cp, #member, member, size)
 636
 637 /**
 638  * \def SERIALIZE_CONTAINER(member)
 639  *
 640  * @ingroup api_serialize
 641  */
 642 #define SERIALIZE_CONTAINER(member)             \
 643         arrayParamOut(cp, #member, member)
 644
 645 /**
 646  * \def UNSERIALIZE_CONTAINER(member)
 647  *
 648  * @ingroup api_serialize
 649  */
 650 #define UNSERIALIZE_CONTAINER(member)           \
 651         arrayParamIn(cp, #member, member)
 652
 653 /**
 654  * \def SERIALIZE_EVENT(event)
 655  *
 656  * @ingroup api_serialize
 657  */
 658 #define SERIALIZE_EVENT(event) event.serializeSection(cp, #event);
 659
 660 /**
 661  * \def UNSERIALIZE_EVENT(event)
 662  *
 663  * @ingroup api_serialize
 664  */
 665 #define UNSERIALIZE_EVENT(event)                        \
 666     do {                                                \
 667         event.unserializeSection(cp, #event);           \
 668         eventQueue()->checkpointReschedule(&event);     \
 669     } while (0)
 670
 671 /**
 672  * \def SERIALIZE_OBJ(obj)
 673  *
 674  * @ingroup api_serialize
 675  */
 676 #define SERIALIZE_OBJ(obj) obj.serializeSection(cp, #obj)
 677
 678 /**
 679  * \def UNSERIALIZE_OBJ(obj)
 680  *
 681  * @ingroup api_serialize
 682  */
 683 #define UNSERIALIZE_OBJ(obj) obj.unserializeSection(cp, #obj)
 684
 685 /**
 686  * \def SERIALIZE_OBJPTR(objptr)
 687  *
 688  * @ingroup api_serialize
 689  */
 690 #define SERIALIZE_OBJPTR(objptr)        paramOut(cp, #objptr, (objptr)->name())
 691
 692 /**
 693  * \def UNSERIALIZE_OBJPTR(objptr)
 694  *
 695  * @ingroup api_serialize
 696  */
 697 #define UNSERIALIZE_OBJPTR(objptr)                      \
 698     do {                                                \
 699         SimObject *sptr;                                \
 700         objParamIn(cp, #objptr, sptr);                  \
 701         objptr = dynamic_cast<decltype(objptr)>(sptr);  \
 702     } while (0)
 703
 704 /**
 705  * \def SERIALIZE_MAPPING(member, names, size)
 706  */
 707 #define SERIALIZE_MAPPING(member, names, size) \
 708         mappingParamOut(cp, #member, names, member, size)
 709
 710 /**
 711  * \def UNSERIALIZE_MAPPING(member, names, size)
 712  */
 713 #define UNSERIALIZE_MAPPING(member, names, size) \
 714         mappingParamIn(cp, #member, names, member, size)
 715
 716 #endif // __SERIALIZE_HH__