src/sim/serialize.hh - public/gem5 - Git at Google

 /*
  * Copyright (c) 2015, 2018, 2020 ARM Limited
  * All rights reserved
  *
  * The license below extends only to copyright in the software and shall
  * not be construed as granting a license to any other intellectual
  * property including but not limited to intellectual property relating
  * to a hardware implementation of the functionality of the software
  * licensed hereunder.  You may use the software subject to the license
  * terms below provided that you ensure that this notice is replicated
  * unmodified and in its entirety in all distributions of the software,
  * modified or unmodified, in source code or in binary form.
  *
  * Copyright (c) 2002-2005 The Regents of The University of Michigan
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are
  * met: redistributions of source code must retain the above copyright
  * notice, this list of conditions and the following disclaimer;
  * redistributions in binary form must reproduce the above copyright
  * notice, this list of conditions and the following disclaimer in the
  * documentation and/or other materials provided with the distribution;
  * neither the name of the copyright holders nor the names of its
  * contributors may be used to endorse or promote products derived from
  * this software without specific prior written permission.
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */

 /* @file
  * Serialization Interface Declarations
  */

 #ifndef __SERIALIZE_HH__
 #define __SERIALIZE_HH__


 #include <algorithm>
 #include <fstream>
 #include <iostream>
 #include <iterator>
 #include <stack>
 #include <string>
 #include <type_traits>
 #include <unordered_map>
 #include <vector>

 #include "base/inifile.hh"
 #include "base/logging.hh"
 #include "sim/serialize_handlers.hh"

 namespace gem5
 {

 typedef std::ostream CheckpointOut;

 class CheckpointIn
 {
   private:
     IniFile db;

     const std::string _cptDir;

   public:
     CheckpointIn(const std::string &cpt_dir);
     ~CheckpointIn() = default;

     /**
      * @return Returns the current directory being used for creating
      * checkpoints or restoring checkpoints.
      * @ingroup api_serialize
      * @{
      */
     const std::string getCptDir() { return _cptDir; }

     bool find(const std::string &section, const std::string &entry,
               std::string &value);

     bool entryExists(const std::string &section, const std::string &entry);
     bool sectionExists(const std::string &section);
     void visitSection(const std::string &section,
         IniFile::VisitSectionCallback cb);
     /** @}*/ //end of api_checkout group

     // The following static functions have to do with checkpoint
     // creation rather than restoration.  This class makes a handy
     // namespace for them though.  Currently no Checkpoint object is
     // created on serialization (only unserialization) so we track the
     // directory name as a global.  It would be nice to change this
     // someday

   private:
     // current directory we're serializing into.
     static std::string currentDirectory;


   public:
     /**
      * Set the current directory
      *
      * This function takes care of inserting curTick() if there's a '%d' in the
      * argument, and appends a '/' if necessary. The final name is returned.
      *
      * @ingroup api_serialize
      */
     static std::string setDir(const std::string &base_name);

     /**
      * Get the current checkout directory name
      *
      * This function exports the current checkout point directory name so other
      * objects can derive filenames from it (e.g., memory). The return value is
      * guaranteed to end in '/' so filenames can be directly appended. This
      * function is only valid while a checkpoint is being created.
      *
      * @ingroup api_serialize
      */
     static std::string dir();

     // Filename for base checkpoint file within directory.
     static const char *baseFilename;
 };

 /**
  * Basic support for object serialization.
  *
  * The Serailizable interface is used to create checkpoints. Any
  * object that implements this interface can be included in
  * gem5's checkpointing system.
  *
  * Objects that support serialization should derive from this
  * class. Such objects can largely be divided into two categories: 1)
  * True SimObjects (deriving from SimObject), and 2) child objects
  * (non-SimObjects).
  *
  * SimObjects are serialized automatically into their own sections
  * automatically by the SimObject base class (see
  * SimObject::serializeAll().
  *
  * SimObjects can contain other serializable objects that are not
  * SimObjects. Much like normal serialized members are not serialized
  * automatically, these objects will not be serialized automatically
  * and it is expected that the objects owning such serializable
  * objects call the required serialization/unserialization methods on
  * child objects. The preferred method to serialize a child object is
  * to call serializeSection() on the child, which serializes the
  * object into a new subsection in the current section. Another option
  * is to call serialize() directly, which serializes the object into
  * the current section. The latter is not recommended as it can lead
  * to naming clashes between objects.
  *
  * @note Many objects that support serialization need to be put in a
  * consistent state when serialization takes place. We refer to the
  * action of forcing an object into a consistent state as
  * 'draining'. Objects that need draining inherit from Drainable. See
  * Drainable for more information.
  */
 class Serializable
 {
   public:
     class ScopedCheckpointSection
     {
       public:
         /**
          * This is the constructor for Scoped checkpoint section helper
          * class.
          *
          * Scoped checkpoint helper class creates a section within a
          * checkpoint without the need for a separate serializeable
          * object. It is mainly used within the Serializable class
          * when serializing or unserializing section (see
          * serializeSection() and unserializeSection()). It
          * can also be used to maintain backwards compatibility in
          * existing code that serializes structs that are not inheriting
          * from Serializable into subsections.
          *
          * When the class is instantiated, it appends a name to the active
          * path in a checkpoint. The old path is later restored when the
          * instance is destroyed. For example, serializeSection() could be
          * implemented by instantiating a ScopedCheckpointSection and then
          * calling serialize() on an object.
          *
          * @ingroup api_serialize
          * @{
          */
         template<class CP>
         ScopedCheckpointSection(CP &cp, const char *name) {
             pushName(name);
             nameOut(cp);
         }

         template<class CP>
         ScopedCheckpointSection(CP &cp, const std::string &name) {
             pushName(name.c_str());
             nameOut(cp);
         }
         /** @}*/ //end of api_serialize group

         ~ScopedCheckpointSection();

         ScopedCheckpointSection() = delete;
         ScopedCheckpointSection(const ScopedCheckpointSection &) = delete;
         ScopedCheckpointSection &operator=(
             const ScopedCheckpointSection &) = delete;
         ScopedCheckpointSection &operator=(
             ScopedCheckpointSection &&) = delete;

       private:
         void pushName(const char *name);
         void nameOut(CheckpointOut &cp);
         void nameOut(CheckpointIn &cp) {};
     };

     /**
      * @ingroup api_serialize
      */
     Serializable();
     virtual ~Serializable();

     /**
      * Serialize an object
      *
      * Output an object's state into the current checkpoint section.
      *
      * @param cp Checkpoint state
      *
      * @ingroup api_serialize
      */
     virtual void serialize(CheckpointOut &cp) const = 0;

     /**
      * Unserialize an object
      *
      * Read an object's state from the current checkpoint section.
      *
      * @param cp Checkpoint state
      *
      * @ingroup api_serialize
      */
     virtual void unserialize(CheckpointIn &cp) = 0;

     /**
      * Serialize an object into a new section
      *
      * This method creates a new section in a checkpoint and calls
      * serialize() to serialize the current object into that
      * section. The name of the section is appended to the current
      * checkpoint path.
      *
      * @param cp Checkpoint state
      * @param name Name to append to the active path
      *
      * @ingroup api_serialize
      */
     void serializeSection(CheckpointOut &cp, const char *name) const;

     /**
      * @ingroup api_serialize
      */
     void serializeSection(CheckpointOut &cp, const std::string &name) const {
         serializeSection(cp, name.c_str());
     }

     /**
      * Unserialize an a child object
      *
      * This method loads a child object from a checkpoint. The object
      * name is appended to the active path to form a fully qualified
      * section name and unserialize() is called.
      *
      * @param cp Checkpoint state
      * @param name Name to append to the active path
      *
      * @ingroup api_serialize
      */
     void unserializeSection(CheckpointIn &cp, const char *name);

     /**
      * @ingroup api_serialize
      */
     void unserializeSection(CheckpointIn &cp, const std::string &name) {
         unserializeSection(cp, name.c_str());
     }

     /**
      * Gets the fully-qualified name of the active section
      *
      * @ingroup api_serialize
      */
     static const std::string &currentSection();

     /**
      * Generate a checkpoint file so that the serialization can be routed to
      * it.
      *
      * @param cpt_dir The dir at which the cpt file will be created.
      * @param outstream The cpt file.
      * @ingroup api_serialize
      */
     static void generateCheckpointOut(const std::string &cpt_dir,
         std::ofstream &outstream);

   private:
     static std::stack<std::string> path;
 };

 /**
  * This function is used for writing parameters to a checkpoint.
  * @param os The checkpoint to be written to.
  * @param name Name of the parameter to be set.
  * @param param Value of the parameter to be written.
  * @ingroup api_serialize
  */
 template <class T>
 void
 paramOut(CheckpointOut &os, const std::string &name, const T &param)
 {
     os << name << "=";
     ShowParam<T>::show(os, param);
     os << "\n";
 }

 template <class T>
 bool
 paramInImpl(CheckpointIn &cp, const std::string &name, T &param)
 {
     const std::string &section(Serializable::currentSection());
     std::string str;
     return cp.find(section, name, str) && ParseParam<T>::parse(str, param);
 }

 /**
  * This function is used for restoring optional parameters from the
  * checkpoint.
  * @param cp The checkpoint to be read from.
  * @param name Name of the parameter to be read.
  * @param param Value of the parameter to be read.
  * @param do_warn If the warn is set to true then the function prints the
  * warning message.
  * @return Returns if the parameter existed in the checkpoint.
  *
  * @ingroup api_serialize
  */
 template <class T>
 bool
 optParamIn(CheckpointIn &cp, const std::string &name, T &param,
            bool do_warn=true)
 {
     if (paramInImpl(cp, name, param))
         return true;

     warn_if(do_warn, "optional parameter %s:%s not present",
             Serializable::currentSection(), name);
     return false;
 }

 /**
  * This function is used for restoring parameters from a checkpoint.
  * @param os The checkpoint to be restored from.
  * @param name Name of the parameter to be set.
  * @param param Value of the parameter to be restored.
  * @ingroup api_serialize
  */
 template <class T>
 void
 paramIn(CheckpointIn &cp, const std::string &name, T &param)
 {
     fatal_if(!paramInImpl(cp, name, param),
         "Can't unserialize '%s:%s'", Serializable::currentSection(), name);
 }

 /**
  * @ingroup api_serialize
  */
 template <class InputIterator>
 void
 arrayParamOut(CheckpointOut &os, const std::string &name,
               InputIterator start, InputIterator end)
 {
     os << name << "=";
     auto it = start;
     using Elem = std::remove_cv_t<std::remove_reference_t<decltype(*it)>>;
     if (it != end)
         ShowParam<Elem>::show(os, *it++);
     while (it != end) {
         os << " ";
         ShowParam<Elem>::show(os, *it++);
     }
     os << "\n";
 }

 /**
  * @ingroup api_serialize
  */
 template <class T>
 decltype(std::begin(std::declval<const T&>()),
          std::end(std::declval<const T&>()), void())
 arrayParamOut(CheckpointOut &os, const std::string &name,
               const T &param)
 {
     arrayParamOut(os, name, std::begin(param), std::end(param));
 }


 /**
  * @ingroup api_serialize
  */
 template <class T>
 void
 arrayParamOut(CheckpointOut &os, const std::string &name,
               const T *param, unsigned size)
 {
     arrayParamOut(os, name, param, param + size);
 }

 /**
  * Extract values stored in the checkpoint, and assign them to the provided
  * array container.
  *
  * @param cp The checkpoint to be parsed.
  * @param name Name of the container.
  * @param param The array container.
  * @param size The expected number of entries to be extracted.
  *
  * @ingroup api_serialize
  */

 template <class T, class InsertIterator>
 void
 arrayParamIn(CheckpointIn &cp, const std::string &name,
              InsertIterator inserter, ssize_t fixed_size=-1)
 {
     const std::string &section = Serializable::currentSection();
     std::string str;
     fatal_if(!cp.find(section, name, str),
         "Can't unserialize '%s:%s'.", section, name);

     std::vector<std::string> tokens;
     tokenize(tokens, str, ' ');

     fatal_if(fixed_size >= 0 && tokens.size() != fixed_size,
              "Array size mismatch on %s:%s (Got %u, expected %u)'\n",
              section, name, tokens.size(), fixed_size);

     for (const auto &token: tokens) {
         T value;
         fatal_if(!ParseParam<T>::parse(token, value),
                  "Could not parse \"%s\".", str);
         *inserter = value;
     }
 }

 /**
  * @ingroup api_serialize
  */
 template <class T>
 decltype(std::declval<T>().insert(std::declval<typename T::value_type>()),
          void())
 arrayParamIn(CheckpointIn &cp, const std::string &name, T &param)
 {
     param.clear();
     arrayParamIn<typename T::value_type>(
             cp, name, std::inserter(param, param.begin()));
 }

 /**
  * @ingroup api_serialize
  */
 template <class T>
 decltype(std::declval<T>().push_back(std::declval<typename T::value_type>()),
          void())
 arrayParamIn(CheckpointIn &cp, const std::string &name, T &param)
 {
     param.clear();
     arrayParamIn<typename T::value_type>(cp, name, std::back_inserter(param));
 }

 /**
  * @ingroup api_serialize
  */
 template <class T>
 void
 arrayParamIn(CheckpointIn &cp, const std::string &name,
              T *param, unsigned size)
 {
     struct ArrayInserter
     {
         T *data;
         T &operator *() { return *data++; }
     } insert_it{param};

     arrayParamIn<T>(cp, name, insert_it, size);
 }

 /**
  * Serialize a mapping represented as two arrays: one containing names
  * and the other containing values.
  *
  * @param names array of keys
  * @param param array of values
  * @param size size of the names and param arrays
  */
 template <class T>
 void
 mappingParamOut(CheckpointOut &os, const char* sectionName,
     const char* const names[], const T *param, unsigned size)
 {
     Serializable::ScopedCheckpointSection sec(os, sectionName);
     for (unsigned i = 0; i < size; ++i) {
         paramOut(os, names[i], param[i]);
     }
 }

 /**
  * Restore mappingParamOut. Keys missing from the checkpoint are ignored.
  */
 template <class T>
 void
 mappingParamIn(CheckpointIn &cp, const char* sectionName,
     const char* const names[], T *param, unsigned size)
 {
     Serializable::ScopedCheckpointSection sec(cp, sectionName);
     std::unordered_map<std::string, size_t> name_to_index;
     for (size_t i = 0; i < size; i++) {
         name_to_index[names[i]] = i;
     }
     for (size_t i = 0; i < size; i++) {
         auto& key = names[i];
         T value;
         if (optParamIn(cp, key, value)) {
             param[name_to_index[key]] = value;
         }
     }
     cp.visitSection(
         Serializable::currentSection(),
         [name_to_index](const std::string& key, const std::string& val)
         {
             if (!name_to_index.count(key)) {
                 warn("unknown entry found in checkpoint: %s %s %s\n",
                     Serializable::currentSection(), key, val);
             }
         }
     );
 }

 //
 // These macros are streamlined to use in serialize/unserialize
 // functions.  It's assumed that serialize() has a parameter 'os' for
 // the ostream, and unserialize() has parameters 'cp' and 'section'.


 /**
  * \def SERIALIZE_SCALER(scaler)
  *
  * @ingroup api_serialize
  */
 #define SERIALIZE_SCALAR(scalar)        paramOut(cp, #scalar, scalar)

 /**
  * \def UNSERIALIZE_SCALER(scalar)
  *
  * @ingroup api_serialize
  */
 #define UNSERIALIZE_SCALAR(scalar)      paramIn(cp, #scalar, scalar)

 /**
  * \def UNSERIALIZE_OPT_SCALAR(scalar)
  *
  * @ingroup api_serialize
  */
 #define UNSERIALIZE_OPT_SCALAR(scalar)      optParamIn(cp, #scalar, scalar)

 // ENUMs are like SCALARs, but we cast them to ints on the way out

 /**
  * \def SERIALIZE_ENUM(scalar)
  *
  * @ingroup api_serialize
  */
 #define SERIALIZE_ENUM(scalar)          paramOut(cp, #scalar, (int)scalar)

 /**
  * \def UNSERIALIZE_ENUM(scaler)
  *
  * @ingroup api_serialize
  */
 #define UNSERIALIZE_ENUM(scalar)                        \
     do {                                                \
         int tmp;                                        \
         paramIn(cp, #scalar, tmp);                      \
         scalar = static_cast<decltype(scalar)>(tmp);    \
     } while (0)

 /**
  * \def SERIALIZE_ARRAY(member, size)
  *
  * @ingroup api_serialize
  */
 #define SERIALIZE_ARRAY(member, size)           \
         arrayParamOut(cp, #member, member, size)

 /**
  * \def UNSERIALIZE_ARRAY(member, size)
  *
  * @ingroup api_serialize
  */
 #define UNSERIALIZE_ARRAY(member, size)         \
         arrayParamIn(cp, #member, member, size)

 /**
  * \def SERIALIZE_CONTAINER(member)
  *
  * @ingroup api_serialize
  */
 #define SERIALIZE_CONTAINER(member)             \
         arrayParamOut(cp, #member, member)

 /**
  * \def UNSERIALIZE_CONTAINER(member)
  *
  * @ingroup api_serialize
  */
 #define UNSERIALIZE_CONTAINER(member)           \
         arrayParamIn(cp, #member, member)

 /**
  * \def SERIALIZE_OBJ(obj)
  *
  * This macro serializes an object into its own section. The object must
  * inherit from Serializable, but NOT from SimObject (i.e, it is an object
  * in the strict sense of "object oriented programing"). Objects that
  * derive from SimObject are automatically serialized elsewhere
  * (@see Serializable, SimObject::serializeAll()).
  *
  * @ingroup api_serialize
  */
 #define SERIALIZE_OBJ(obj) obj.serializeSection(cp, #obj)

 /**
  * \def UNSERIALIZE_OBJ(obj)
  *
  * @ingroup api_serialize
  */
 #define UNSERIALIZE_OBJ(obj) obj.unserializeSection(cp, #obj)

 /**
  * \def SERIALIZE_MAPPING(member, names, size)
  */
 #define SERIALIZE_MAPPING(member, names, size) \
         mappingParamOut(cp, #member, names, member, size)

 /**
  * \def UNSERIALIZE_MAPPING(member, names, size)
  */
 #define UNSERIALIZE_MAPPING(member, names, size) \
         mappingParamIn(cp, #member, names, member, size)

 } // namespace gem5

 #endif // __SERIALIZE_HH__
	/*
	* Copyright (c) 2015, 2018, 2020 ARM Limited
	* All rights reserved
	*
	* The license below extends only to copyright in the software and shall
	* not be construed as granting a license to any other intellectual
	* property including but not limited to intellectual property relating
	* to a hardware implementation of the functionality of the software
	* licensed hereunder. You may use the software subject to the license
	* terms below provided that you ensure that this notice is replicated
	* unmodified and in its entirety in all distributions of the software,
	* modified or unmodified, in source code or in binary form.
	*
	* Copyright (c) 2002-2005 The Regents of The University of Michigan
	* All rights reserved.
	*
	* Redistribution and use in source and binary forms, with or without
	* modification, are permitted provided that the following conditions are
	* met: redistributions of source code must retain the above copyright
	* notice, this list of conditions and the following disclaimer;
	* redistributions in binary form must reproduce the above copyright
	* notice, this list of conditions and the following disclaimer in the
	* documentation and/or other materials provided with the distribution;
	* neither the name of the copyright holders nor the names of its
	* contributors may be used to endorse or promote products derived from
	* this software without specific prior written permission.
	*
	* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
	* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
	* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
	* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
	* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
	* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
	* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
	* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
	* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
	* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
	* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	*/

	/* @file
	* Serialization Interface Declarations
	*/

	#ifndef __SERIALIZE_HH__
	#define __SERIALIZE_HH__


	#include <algorithm>
	#include <fstream>
	#include <iostream>
	#include <iterator>
	#include <stack>
	#include <string>
	#include <type_traits>
	#include <unordered_map>
	#include <vector>

	#include "base/inifile.hh"
	#include "base/logging.hh"
	#include "sim/serialize_handlers.hh"

	namespace gem5
	{

	typedef std::ostream CheckpointOut;

	class CheckpointIn
	{
	private:
	IniFile db;

	const std::string _cptDir;

	public:
	CheckpointIn(const std::string &cpt_dir);
	~CheckpointIn() = default;

	/**
	* @return Returns the current directory being used for creating
	* checkpoints or restoring checkpoints.
	* @ingroup api_serialize
	* @{
	*/
	const std::string getCptDir() { return _cptDir; }

	bool find(const std::string &section, const std::string &entry,
	std::string &value);

	bool entryExists(const std::string &section, const std::string &entry);
	bool sectionExists(const std::string &section);
	void visitSection(const std::string &section,
	IniFile::VisitSectionCallback cb);
	/** @}*/ //end of api_checkout group

	// The following static functions have to do with checkpoint
	// creation rather than restoration. This class makes a handy
	// namespace for them though. Currently no Checkpoint object is
	// created on serialization (only unserialization) so we track the
	// directory name as a global. It would be nice to change this
	// someday

	private:
	// current directory we're serializing into.
	static std::string currentDirectory;


	public:
	/**
	* Set the current directory
	*
	* This function takes care of inserting curTick() if there's a '%d' in the
	* argument, and appends a '/' if necessary. The final name is returned.
	*
	* @ingroup api_serialize
	*/
	static std::string setDir(const std::string &base_name);

	/**
	* Get the current checkout directory name
	*
	* This function exports the current checkout point directory name so other
	* objects can derive filenames from it (e.g., memory). The return value is
	* guaranteed to end in '/' so filenames can be directly appended. This
	* function is only valid while a checkpoint is being created.
	*
	* @ingroup api_serialize
	*/
	static std::string dir();

	// Filename for base checkpoint file within directory.
	static const char *baseFilename;
	};

	/**
	* Basic support for object serialization.
	*
	* The Serailizable interface is used to create checkpoints. Any
	* object that implements this interface can be included in
	* gem5's checkpointing system.
	*
	* Objects that support serialization should derive from this
	* class. Such objects can largely be divided into two categories: 1)
	* True SimObjects (deriving from SimObject), and 2) child objects
	* (non-SimObjects).
	*
	* SimObjects are serialized automatically into their own sections
	* automatically by the SimObject base class (see
	* SimObject::serializeAll().
	*
	* SimObjects can contain other serializable objects that are not
	* SimObjects. Much like normal serialized members are not serialized
	* automatically, these objects will not be serialized automatically
	* and it is expected that the objects owning such serializable
	* objects call the required serialization/unserialization methods on
	* child objects. The preferred method to serialize a child object is
	* to call serializeSection() on the child, which serializes the
	* object into a new subsection in the current section. Another option
	* is to call serialize() directly, which serializes the object into
	* the current section. The latter is not recommended as it can lead
	* to naming clashes between objects.
	*
	* @note Many objects that support serialization need to be put in a
	* consistent state when serialization takes place. We refer to the
	* action of forcing an object into a consistent state as
	* 'draining'. Objects that need draining inherit from Drainable. See
	* Drainable for more information.
	*/
	class Serializable
	{
	public:
	class ScopedCheckpointSection
	{
	public:
	/**
	* This is the constructor for Scoped checkpoint section helper
	* class.
	*
	* Scoped checkpoint helper class creates a section within a
	* checkpoint without the need for a separate serializeable
	* object. It is mainly used within the Serializable class
	* when serializing or unserializing section (see
	* serializeSection() and unserializeSection()). It
	* can also be used to maintain backwards compatibility in
	* existing code that serializes structs that are not inheriting
	* from Serializable into subsections.
	*
	* When the class is instantiated, it appends a name to the active
	* path in a checkpoint. The old path is later restored when the
	* instance is destroyed. For example, serializeSection() could be
	* implemented by instantiating a ScopedCheckpointSection and then
	* calling serialize() on an object.
	*
	* @ingroup api_serialize
	* @{
	*/
	template<class CP>
	ScopedCheckpointSection(CP &cp, const char *name) {
	pushName(name);
	nameOut(cp);
	}

	template<class CP>
	ScopedCheckpointSection(CP &cp, const std::string &name) {
	pushName(name.c_str());
	nameOut(cp);
	}
	/** @}*/ //end of api_serialize group

	~ScopedCheckpointSection();

	ScopedCheckpointSection() = delete;
	ScopedCheckpointSection(const ScopedCheckpointSection &) = delete;
	ScopedCheckpointSection &operator=(
	const ScopedCheckpointSection &) = delete;
	ScopedCheckpointSection &operator=(
	ScopedCheckpointSection &&) = delete;

	private:
	void pushName(const char *name);
	void nameOut(CheckpointOut &cp);
	void nameOut(CheckpointIn &cp) {};
	};

	/**
	* @ingroup api_serialize
	*/
	Serializable();
	virtual ~Serializable();

	/**
	* Serialize an object
	*
	* Output an object's state into the current checkpoint section.
	*
	* @param cp Checkpoint state
	*
	* @ingroup api_serialize
	*/
	virtual void serialize(CheckpointOut &cp) const = 0;

	/**
	* Unserialize an object
	*
	* Read an object's state from the current checkpoint section.
	*
	* @param cp Checkpoint state
	*
	* @ingroup api_serialize
	*/
	virtual void unserialize(CheckpointIn &cp) = 0;

	/**
	* Serialize an object into a new section
	*
	* This method creates a new section in a checkpoint and calls
	* serialize() to serialize the current object into that
	* section. The name of the section is appended to the current
	* checkpoint path.
	*
	* @param cp Checkpoint state
	* @param name Name to append to the active path
	*
	* @ingroup api_serialize
	*/
	void serializeSection(CheckpointOut &cp, const char *name) const;

	/**
	* @ingroup api_serialize
	*/
	void serializeSection(CheckpointOut &cp, const std::string &name) const {
	serializeSection(cp, name.c_str());
	}

	/**
	* Unserialize an a child object
	*
	* This method loads a child object from a checkpoint. The object
	* name is appended to the active path to form a fully qualified
	* section name and unserialize() is called.
	*
	* @param cp Checkpoint state
	* @param name Name to append to the active path
	*
	* @ingroup api_serialize
	*/
	void unserializeSection(CheckpointIn &cp, const char *name);

	/**
	* @ingroup api_serialize
	*/
	void unserializeSection(CheckpointIn &cp, const std::string &name) {
	unserializeSection(cp, name.c_str());
	}

	/**
	* Gets the fully-qualified name of the active section
	*
	* @ingroup api_serialize
	*/
	static const std::string &currentSection();

	/**
	* Generate a checkpoint file so that the serialization can be routed to
	* it.
	*
	* @param cpt_dir The dir at which the cpt file will be created.
	* @param outstream The cpt file.
	* @ingroup api_serialize
	*/
	static void generateCheckpointOut(const std::string &cpt_dir,
	std::ofstream &outstream);

	private:
	static std::stack<std::string> path;
	};

	/**
	* This function is used for writing parameters to a checkpoint.
	* @param os The checkpoint to be written to.
	* @param name Name of the parameter to be set.
	* @param param Value of the parameter to be written.
	* @ingroup api_serialize
	*/
	template <class T>
	void
	paramOut(CheckpointOut &os, const std::string &name, const T &param)
	{
	os << name << "=";
	ShowParam<T>::show(os, param);
	os << "\n";
	}

	template <class T>
	bool
	paramInImpl(CheckpointIn &cp, const std::string &name, T &param)
	{
	const std::string &section(Serializable::currentSection());
	std::string str;
	return cp.find(section, name, str) && ParseParam<T>::parse(str, param);
	}

	/**
	* This function is used for restoring optional parameters from the
	* checkpoint.
	* @param cp The checkpoint to be read from.
	* @param name Name of the parameter to be read.
	* @param param Value of the parameter to be read.
	* @param do_warn If the warn is set to true then the function prints the
	* warning message.
	* @return Returns if the parameter existed in the checkpoint.
	*
	* @ingroup api_serialize
	*/
	template <class T>
	bool
	optParamIn(CheckpointIn &cp, const std::string &name, T &param,
	bool do_warn=true)
	{
	if (paramInImpl(cp, name, param))
	return true;

	warn_if(do_warn, "optional parameter %s:%s not present",
	Serializable::currentSection(), name);
	return false;
	}

	/**
	* This function is used for restoring parameters from a checkpoint.
	* @param os The checkpoint to be restored from.
	* @param name Name of the parameter to be set.
	* @param param Value of the parameter to be restored.
	* @ingroup api_serialize
	*/
	template <class T>
	void
	paramIn(CheckpointIn &cp, const std::string &name, T &param)
	{
	fatal_if(!paramInImpl(cp, name, param),
	"Can't unserialize '%s:%s'", Serializable::currentSection(), name);
	}

	/**
	* @ingroup api_serialize
	*/
	template <class InputIterator>
	void
	arrayParamOut(CheckpointOut &os, const std::string &name,
	InputIterator start, InputIterator end)
	{
	os << name << "=";
	auto it = start;
	using Elem = std::remove_cv_t<std::remove_reference_t<decltype(*it)>>;
	if (it != end)
	ShowParam<Elem>::show(os, *it++);
	while (it != end) {
	os << " ";
	ShowParam<Elem>::show(os, *it++);
	}
	os << "\n";
	}

	/**
	* @ingroup api_serialize
	*/
	template <class T>
	decltype(std::begin(std::declval<const T&>()),
	std::end(std::declval<const T&>()), void())
	arrayParamOut(CheckpointOut &os, const std::string &name,
	const T &param)
	{
	arrayParamOut(os, name, std::begin(param), std::end(param));
	}


	/**
	* @ingroup api_serialize
	*/
	template <class T>
	void
	arrayParamOut(CheckpointOut &os, const std::string &name,
	const T *param, unsigned size)
	{
	arrayParamOut(os, name, param, param + size);
	}

	/**
	* Extract values stored in the checkpoint, and assign them to the provided
	* array container.
	*
	* @param cp The checkpoint to be parsed.
	* @param name Name of the container.
	* @param param The array container.
	* @param size The expected number of entries to be extracted.
	*
	* @ingroup api_serialize
	*/

	template <class T, class InsertIterator>
	void
	arrayParamIn(CheckpointIn &cp, const std::string &name,
	InsertIterator inserter, ssize_t fixed_size=-1)
	{
	const std::string &section = Serializable::currentSection();
	std::string str;
	fatal_if(!cp.find(section, name, str),
	"Can't unserialize '%s:%s'.", section, name);

	std::vector<std::string> tokens;
	tokenize(tokens, str, ' ');

	fatal_if(fixed_size >= 0 && tokens.size() != fixed_size,
	"Array size mismatch on %s:%s (Got %u, expected %u)'\n",
	section, name, tokens.size(), fixed_size);

	for (const auto &token: tokens) {
	T value;
	fatal_if(!ParseParam<T>::parse(token, value),
	"Could not parse \"%s\".", str);
	*inserter = value;
	}
	}

	/**
	* @ingroup api_serialize
	*/
	template <class T>
	decltype(std::declval<T>().insert(std::declval<typename T::value_type>()),
	void())
	arrayParamIn(CheckpointIn &cp, const std::string &name, T &param)
	{
	param.clear();
	arrayParamIn<typename T::value_type>(
	cp, name, std::inserter(param, param.begin()));
	}

	/**
	* @ingroup api_serialize
	*/
	template <class T>
	decltype(std::declval<T>().push_back(std::declval<typename T::value_type>()),
	void())
	arrayParamIn(CheckpointIn &cp, const std::string &name, T &param)
	{
	param.clear();
	arrayParamIn<typename T::value_type>(cp, name, std::back_inserter(param));
	}

	/**
	* @ingroup api_serialize
	*/
	template <class T>
	void
	arrayParamIn(CheckpointIn &cp, const std::string &name,
	T *param, unsigned size)
	{
	struct ArrayInserter
	{
	T *data;
	T &operator () { return data++; }
	} insert_it{param};

	arrayParamIn<T>(cp, name, insert_it, size);
	}

	/**
	* Serialize a mapping represented as two arrays: one containing names
	* and the other containing values.
	*
	* @param names array of keys
	* @param param array of values
	* @param size size of the names and param arrays
	*/
	template <class T>
	void
	mappingParamOut(CheckpointOut &os, const char* sectionName,
	const char* const names[], const T *param, unsigned size)
	{
	Serializable::ScopedCheckpointSection sec(os, sectionName);
	for (unsigned i = 0; i < size; ++i) {
	paramOut(os, names[i], param[i]);
	}
	}

	/**
	* Restore mappingParamOut. Keys missing from the checkpoint are ignored.
	*/
	template <class T>
	void
	mappingParamIn(CheckpointIn &cp, const char* sectionName,
	const char* const names[], T *param, unsigned size)
	{
	Serializable::ScopedCheckpointSection sec(cp, sectionName);
	std::unordered_map<std::string, size_t> name_to_index;
	for (size_t i = 0; i < size; i++) {
	name_to_index[names[i]] = i;
	}
	for (size_t i = 0; i < size; i++) {
	auto& key = names[i];
	T value;
	if (optParamIn(cp, key, value)) {
	param[name_to_index[key]] = value;
	}
	}
	cp.visitSection(
	Serializable::currentSection(),
	[name_to_index](const std::string& key, const std::string& val)
	{
	if (!name_to_index.count(key)) {
	warn("unknown entry found in checkpoint: %s %s %s\n",
	Serializable::currentSection(), key, val);
	}
	}
	);
	}

	//
	// These macros are streamlined to use in serialize/unserialize
	// functions. It's assumed that serialize() has a parameter 'os' for
	// the ostream, and unserialize() has parameters 'cp' and 'section'.


	/**
	* \def SERIALIZE_SCALER(scaler)
	*
	* @ingroup api_serialize
	*/
	#define SERIALIZE_SCALAR(scalar) paramOut(cp, #scalar, scalar)

	/**
	* \def UNSERIALIZE_SCALER(scalar)
	*
	* @ingroup api_serialize
	*/
	#define UNSERIALIZE_SCALAR(scalar) paramIn(cp, #scalar, scalar)

	/**
	* \def UNSERIALIZE_OPT_SCALAR(scalar)
	*
	* @ingroup api_serialize
	*/
	#define UNSERIALIZE_OPT_SCALAR(scalar) optParamIn(cp, #scalar, scalar)

	// ENUMs are like SCALARs, but we cast them to ints on the way out

	/**
	* \def SERIALIZE_ENUM(scalar)
	*
	* @ingroup api_serialize
	*/
	#define SERIALIZE_ENUM(scalar) paramOut(cp, #scalar, (int)scalar)

	/**
	* \def UNSERIALIZE_ENUM(scaler)
	*
	* @ingroup api_serialize
	*/
	#define UNSERIALIZE_ENUM(scalar) \
	do { \
	int tmp; \
	paramIn(cp, #scalar, tmp); \
	scalar = static_cast<decltype(scalar)>(tmp); \
	} while (0)

	/**
	* \def SERIALIZE_ARRAY(member, size)
	*
	* @ingroup api_serialize
	*/
	#define SERIALIZE_ARRAY(member, size) \
	arrayParamOut(cp, #member, member, size)

	/**
	* \def UNSERIALIZE_ARRAY(member, size)
	*
	* @ingroup api_serialize
	*/
	#define UNSERIALIZE_ARRAY(member, size) \
	arrayParamIn(cp, #member, member, size)

	/**
	* \def SERIALIZE_CONTAINER(member)
	*
	* @ingroup api_serialize
	*/
	#define SERIALIZE_CONTAINER(member) \
	arrayParamOut(cp, #member, member)

	/**
	* \def UNSERIALIZE_CONTAINER(member)
	*
	* @ingroup api_serialize
	*/
	#define UNSERIALIZE_CONTAINER(member) \
	arrayParamIn(cp, #member, member)

	/**
	* \def SERIALIZE_OBJ(obj)
	*
	* This macro serializes an object into its own section. The object must
	* inherit from Serializable, but NOT from SimObject (i.e, it is an object
	* in the strict sense of "object oriented programing"). Objects that
	* derive from SimObject are automatically serialized elsewhere
	* (@see Serializable, SimObject::serializeAll()).
	*
	* @ingroup api_serialize
	*/
	#define SERIALIZE_OBJ(obj) obj.serializeSection(cp, #obj)

	/**
	* \def UNSERIALIZE_OBJ(obj)
	*
	* @ingroup api_serialize
	*/
	#define UNSERIALIZE_OBJ(obj) obj.unserializeSection(cp, #obj)

	/**
	* \def SERIALIZE_MAPPING(member, names, size)
	*/
	#define SERIALIZE_MAPPING(member, names, size) \
	mappingParamOut(cp, #member, names, member, size)

	/**
	* \def UNSERIALIZE_MAPPING(member, names, size)
	*/
	#define UNSERIALIZE_MAPPING(member, names, size) \
	mappingParamIn(cp, #member, names, member, size)

	} // namespace gem5

	#endif // __SERIALIZE_HH__