gem5  v21.1.0.2
serialize.hh
Go to the documentation of this file.
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 <fstream>
51 #include <iostream>
52 #include <iterator>
53 #include <stack>
54 #include <string>
55 #include <type_traits>
56 #include <unordered_map>
57 #include <vector>
58 
59 #include "base/inifile.hh"
60 #include "base/logging.hh"
62 
63 namespace gem5
64 {
65 
66 typedef std::ostream CheckpointOut;
67 
69 {
70  private:
72 
73  const std::string _cptDir;
74 
75  public:
76  CheckpointIn(const std::string &cpt_dir);
77  ~CheckpointIn() = default;
78 
85  const std::string getCptDir() { return _cptDir; }
86 
87  bool find(const std::string &section, const std::string &entry,
88  std::string &value);
89 
90  bool entryExists(const std::string &section, const std::string &entry);
91  bool sectionExists(const std::string &section);
92  void visitSection(const std::string &section,
93  IniFile::VisitSectionCallback cb); //end of api_checkout group
95 
96  // The following static functions have to do with checkpoint
97  // creation rather than restoration. This class makes a handy
98  // namespace for them though. Currently no Checkpoint object is
99  // created on serialization (only unserialization) so we track the
100  // directory name as a global. It would be nice to change this
101  // someday
102 
103  private:
104  // current directory we're serializing into.
105  static std::string currentDirectory;
106 
107 
108  public:
117  static std::string setDir(const std::string &base_name);
118 
129  static std::string dir();
130 
131  // Filename for base checkpoint file within directory.
132  static const char *baseFilename;
133 };
134 
170 {
171  public:
173  {
174  public:
197  template<class CP>
198  ScopedCheckpointSection(CP &cp, const char *name) {
199  pushName(name);
200  nameOut(cp);
201  }
202 
203  template<class CP>
204  ScopedCheckpointSection(CP &cp, const std::string &name) {
205  pushName(name.c_str());
206  nameOut(cp);
207  } //end of api_serialize group
209 
211 
212  ScopedCheckpointSection() = delete;
215  const ScopedCheckpointSection &) = delete;
217  ScopedCheckpointSection &&) = delete;
218 
219  private:
220  void pushName(const char *name);
221  void nameOut(CheckpointOut &cp);
222  void nameOut(CheckpointIn &cp) {};
223  };
224 
228  Serializable();
229  virtual ~Serializable();
230 
240  virtual void serialize(CheckpointOut &cp) const = 0;
241 
251  virtual void unserialize(CheckpointIn &cp) = 0;
252 
266  void serializeSection(CheckpointOut &cp, const char *name) const;
267 
271  void serializeSection(CheckpointOut &cp, const std::string &name) const {
272  serializeSection(cp, name.c_str());
273  }
274 
287  void unserializeSection(CheckpointIn &cp, const char *name);
288 
292  void unserializeSection(CheckpointIn &cp, const std::string &name) {
293  unserializeSection(cp, name.c_str());
294  }
295 
301  static const std::string &currentSection();
302 
311  static void generateCheckpointOut(const std::string &cpt_dir,
312  std::ofstream &outstream);
313 
314  private:
315  static std::stack<std::string> path;
316 };
317 
325 template <class T>
326 void
327 paramOut(CheckpointOut &os, const std::string &name, const T &param)
328 {
329  os << name << "=";
330  ShowParam<T>::show(os, param);
331  os << "\n";
332 }
333 
334 template <class T>
335 bool
336 paramInImpl(CheckpointIn &cp, const std::string &name, T &param)
337 {
338  const std::string &section(Serializable::currentSection());
339  std::string str;
340  return cp.find(section, name, str) && ParseParam<T>::parse(str, param);
341 }
342 
355 template <class T>
356 bool
357 optParamIn(CheckpointIn &cp, const std::string &name, T &param,
358  bool do_warn=true)
359 {
360  if (paramInImpl(cp, name, param))
361  return true;
362 
363  warn_if(do_warn, "optional parameter %s:%s not present",
365  return false;
366 }
367 
375 template <class T>
376 void
377 paramIn(CheckpointIn &cp, const std::string &name, T &param)
378 {
379  fatal_if(!paramInImpl(cp, name, param),
380  "Can't unserialize '%s:%s'", Serializable::currentSection(), name);
381 }
382 
386 template <class InputIterator>
387 void
388 arrayParamOut(CheckpointOut &os, const std::string &name,
389  InputIterator start, InputIterator end)
390 {
391  os << name << "=";
392  auto it = start;
393  using Elem = std::remove_cv_t<std::remove_reference_t<decltype(*it)>>;
394  if (it != end)
395  ShowParam<Elem>::show(os, *it++);
396  while (it != end) {
397  os << " ";
398  ShowParam<Elem>::show(os, *it++);
399  }
400  os << "\n";
401 }
402 
406 template <class T>
407 decltype(std::begin(std::declval<const T&>()),
408  std::end(std::declval<const T&>()), void())
410  const T &param)
411 {
412  arrayParamOut(os, name, std::begin(param), std::end(param));
413 }
414 
415 
419 template <class T>
420 void
421 arrayParamOut(CheckpointOut &os, const std::string &name,
422  const T *param, unsigned size)
423 {
424  arrayParamOut(os, name, param, param + size);
425 }
426 
439 template <class T, class InsertIterator>
440 void
441 arrayParamIn(CheckpointIn &cp, const std::string &name,
442  InsertIterator inserter, ssize_t fixed_size=-1)
443 {
444  const std::string &section = Serializable::currentSection();
445  std::string str;
446  fatal_if(!cp.find(section, name, str),
447  "Can't unserialize '%s:%s'.", section, name);
448 
450  tokenize(tokens, str, ' ');
451 
452  fatal_if(fixed_size >= 0 && tokens.size() != fixed_size,
453  "Array size mismatch on %s:%s (Got %u, expected %u)'\n",
454  section, name, tokens.size(), fixed_size);
455 
456  for (const auto &token: tokens) {
457  T value;
459  "Could not parse \"%s\".", str);
460  *inserter = value;
461  }
462 }
463 
467 template <class T>
468 decltype(std::declval<T>().insert(std::declval<typename T::value_type>()),
469  void())
470 arrayParamIn(CheckpointIn &cp, const std::string &name, T &param)
471 {
472  param.clear();
473  arrayParamIn<typename T::value_type>(
474  cp, name, std::inserter(param, param.begin()));
475 }
476 
480 template <class T>
481 decltype(std::declval<T>().push_back(std::declval<typename T::value_type>()),
482  void())
483 arrayParamIn(CheckpointIn &cp, const std::string &name, T &param)
484 {
485  param.clear();
486  arrayParamIn<typename T::value_type>(cp, name, std::back_inserter(param));
487 }
488 
492 template <class T>
493 void
494 arrayParamIn(CheckpointIn &cp, const std::string &name,
495  T *param, unsigned size)
496 {
497  struct ArrayInserter
498  {
499  T *data;
500  T &operator *() { return *data++; }
501  } insert_it{param};
502 
503  arrayParamIn<T>(cp, name, insert_it, size);
504 }
505 
514 template <class T>
515 void
516 mappingParamOut(CheckpointOut &os, const char* sectionName,
517  const char* const names[], const T *param, unsigned size)
518 {
519  Serializable::ScopedCheckpointSection sec(os, sectionName);
520  for (unsigned i = 0; i < size; ++i) {
521  paramOut(os, names[i], param[i]);
522  }
523 }
524 
528 template <class T>
529 void
530 mappingParamIn(CheckpointIn &cp, const char* sectionName,
531  const char* const names[], T *param, unsigned size)
532 {
533  Serializable::ScopedCheckpointSection sec(cp, sectionName);
534  std::unordered_map<std::string, size_t> name_to_index;
535  for (size_t i = 0; i < size; i++) {
536  name_to_index[names[i]] = i;
537  }
538  for (size_t i = 0; i < size; i++) {
539  auto& key = names[i];
540  T value;
541  if (optParamIn(cp, key, value)) {
542  param[name_to_index[key]] = value;
543  }
544  }
545  cp.visitSection(
547  [name_to_index](const std::string& key, const std::string& val)
548  {
549  if (!name_to_index.count(key)) {
550  warn("unknown entry found in checkpoint: %s %s %s\n",
551  Serializable::currentSection(), key, val);
552  }
553  }
554  );
555 }
556 
557 //
558 // These macros are streamlined to use in serialize/unserialize
559 // functions. It's assumed that serialize() has a parameter 'os' for
560 // the ostream, and unserialize() has parameters 'cp' and 'section'.
561 
562 
568 #define SERIALIZE_SCALAR(scalar) paramOut(cp, #scalar, scalar)
569 
575 #define UNSERIALIZE_SCALAR(scalar) paramIn(cp, #scalar, scalar)
576 
582 #define UNSERIALIZE_OPT_SCALAR(scalar) optParamIn(cp, #scalar, scalar)
583 
584 // ENUMs are like SCALARs, but we cast them to ints on the way out
585 
591 #define SERIALIZE_ENUM(scalar) paramOut(cp, #scalar, (int)scalar)
592 
598 #define UNSERIALIZE_ENUM(scalar) \
599  do { \
600  int tmp; \
601  paramIn(cp, #scalar, tmp); \
602  scalar = static_cast<decltype(scalar)>(tmp); \
603  } while (0)
604 
610 #define SERIALIZE_ARRAY(member, size) \
611  arrayParamOut(cp, #member, member, size)
612 
618 #define UNSERIALIZE_ARRAY(member, size) \
619  arrayParamIn(cp, #member, member, size)
620 
626 #define SERIALIZE_CONTAINER(member) \
627  arrayParamOut(cp, #member, member)
628 
634 #define UNSERIALIZE_CONTAINER(member) \
635  arrayParamIn(cp, #member, member)
636 
648 #define SERIALIZE_OBJ(obj) obj.serializeSection(cp, #obj)
649 
655 #define UNSERIALIZE_OBJ(obj) obj.unserializeSection(cp, #obj)
656 
660 #define SERIALIZE_MAPPING(member, names, size) \
661  mappingParamOut(cp, #member, names, member, size)
662 
666 #define UNSERIALIZE_MAPPING(member, names, size) \
667  mappingParamIn(cp, #member, names, member, size)
668 
669 } // namespace gem5
670 
671 #endif // __SERIALIZE_HH__
gem5::Serializable::ScopedCheckpointSection::ScopedCheckpointSection
ScopedCheckpointSection(CP &cp, const std::string &name)
Definition: serialize.hh:204
gem5::operator*
constexpr Temperature operator*(const Temperature &lhs, const double &rhs)
Definition: temperature.hh:161
gem5::Serializable::ScopedCheckpointSection::nameOut
void nameOut(CheckpointOut &cp)
Definition: serialize.cc:122
data
const char data[]
Definition: circlebuf.test.cc:48
gem5::CheckpointIn::dir
static std::string dir()
Get the current checkout directory name.
Definition: serialize.cc:154
gem5::Serializable::serialize
virtual void serialize(CheckpointOut &cp) const =0
Serialize an object.
gem5::Serializable::ScopedCheckpointSection::pushName
void pushName(const char *name)
Definition: serialize.cc:111
gem5::Serializable::path
static std::stack< std::string > path
Definition: serialize.hh:315
gem5::CheckpointIn
Definition: serialize.hh:68
gem5::Serializable::serializeSection
void serializeSection(CheckpointOut &cp, const char *name) const
Serialize an object into a new section.
Definition: serialize.cc:74
gem5::IniFile
This class represents the contents of a ".ini" file.
Definition: inifile.hh:55
gem5::X86ISA::val
Bitfield< 63 > val
Definition: misc.hh:775
gem5::ShowParam::show
static void show(std::ostream &os, const T &value)
Definition: serialize_handlers.hh:127
gem5::Serializable::ScopedCheckpointSection::ScopedCheckpointSection
ScopedCheckpointSection(CP &cp, const char *name)
This is the constructor for Scoped checkpoint section helper class.
Definition: serialize.hh:198
gem5::Serializable::ScopedCheckpointSection::operator=
ScopedCheckpointSection & operator=(const ScopedCheckpointSection &)=delete
std::vector< std::string >
gem5::Serializable::Serializable
Serializable()
Definition: serialize.cc:65
gem5::ArmISA::i
Bitfield< 7 > i
Definition: misc_types.hh:66
gem5::scmi::token
token
Definition: scmi_platform.hh:80
gem5::Serializable::unserializeSection
void unserializeSection(CheckpointIn &cp, const std::string &name)
Definition: serialize.hh:292
gem5::IniFile::VisitSectionCallback
std::function< void(const std::string &, const std::string &)> VisitSectionCallback
Visitor callback that receives key/value pairs.
Definition: inifile.hh:216
gem5::Serializable::~Serializable
virtual ~Serializable()
Definition: serialize.cc:69
gem5::Serializable::ScopedCheckpointSection::~ScopedCheckpointSection
~ScopedCheckpointSection()
Definition: serialize.cc:103
gem5::CheckpointIn::setDir
static std::string setDir(const std::string &base_name)
Set the current directory.
Definition: serialize.cc:142
gem5::CheckpointIn::_cptDir
const std::string _cptDir
Definition: serialize.hh:73
gem5::paramInImpl
bool paramInImpl(CheckpointIn &cp, const std::string &name, T &param)
Definition: serialize.hh:336
gem5::CheckpointIn::~CheckpointIn
~CheckpointIn()=default
gem5::Serializable
Basic support for object serialization.
Definition: serialize.hh:169
gem5::CheckpointIn::visitSection
void visitSection(const std::string &section, IniFile::VisitSectionCallback cb)
Definition: serialize.cc:206
gem5::Serializable::unserializeSection
void unserializeSection(CheckpointIn &cp, const char *name)
Unserialize an a child object.
Definition: serialize.cc:81
gem5::Serializable::unserialize
virtual void unserialize(CheckpointIn &cp)=0
Unserialize an object.
gem5::Serializable::generateCheckpointOut
static void generateCheckpointOut(const std::string &cpt_dir, std::ofstream &outstream)
Generate a checkpoint file so that the serialization can be routed to it.
Definition: serialize.cc:88
gem5::Serializable::ScopedCheckpointSection::nameOut
void nameOut(CheckpointIn &cp)
Definition: serialize.hh:222
gem5::Serializable::serializeSection
void serializeSection(CheckpointOut &cp, const std::string &name) const
Definition: serialize.hh:271
inifile.hh
gem5::X86ISA::delivery_mode::names
static const char *const names[NumModes]
Definition: intmessage.hh:70
gem5::mappingParamIn
void mappingParamIn(CheckpointIn &cp, const char *sectionName, const char *const names[], T *param, unsigned size)
Restore mappingParamOut.
Definition: serialize.hh:530
gem5::tokenize
void tokenize(std::vector< std::string > &v, const std::string &s, char token, bool ignore)
Definition: str.cc:68
name
const std::string & name()
Definition: trace.cc:49
gem5::CheckpointIn::db
IniFile db
Definition: serialize.hh:71
gem5::arrayParamOut
decltype(std::begin(std::declval< const T & >()), std::end(std::declval< const T & >()), void()) arrayParamOut(CheckpointOut &os, const std::string &name, const T &param)
Definition: serialize.hh:409
gem5::Serializable::currentSection
static const std::string & currentSection()
Gets the fully-qualified name of the active section.
Definition: serialize.cc:130
gem5::CheckpointIn::getCptDir
const std::string getCptDir()
Definition: serialize.hh:85
warn_if
#define warn_if(cond,...)
Conditional warning macro that checks the supplied condition and only prints a warning if the conditi...
Definition: logging.hh:272
gem5::CheckpointIn::CheckpointIn
CheckpointIn(const std::string &cpt_dir)
Definition: serialize.cc:159
gem5::optParamIn
bool optParamIn(CheckpointIn &cp, const std::string &name, T &param, bool do_warn=true)
This function is used for restoring optional parameters from the checkpoint.
Definition: serialize.hh:357
gem5::CheckpointIn::sectionExists
bool sectionExists(const std::string &section)
Definition: serialize.cc:200
gem5::CheckpointIn::find
bool find(const std::string &section, const std::string &entry, std::string &value)
Definition: serialize.cc:193
gem5::paramOut
void paramOut(CheckpointOut &cp, const std::string &name, ExtMachInst const &machInst)
Definition: types.cc:40
serialize_handlers.hh
std
Overload hash function for BasicBlockRange type.
Definition: types.hh:111
gem5::X86ISA::os
Bitfield< 17 > os
Definition: misc.hh:809
gem5::paramIn
void paramIn(CheckpointIn &cp, const std::string &name, ExtMachInst &machInst)
Definition: types.cc:72
logging.hh
gem5::Serializable::ScopedCheckpointSection::ScopedCheckpointSection
ScopedCheckpointSection()=delete
gem5::CheckpointOut
std::ostream CheckpointOut
Definition: serialize.hh:66
gem5::CheckpointIn::entryExists
bool entryExists(const std::string &section, const std::string &entry)
Definition: serialize.cc:178
gem5::mappingParamOut
void mappingParamOut(CheckpointOut &os, const char *sectionName, const char *const names[], const T *param, unsigned size)
Serialize a mapping represented as two arrays: one containing names and the other containing values.
Definition: serialize.hh:516
gem5::arrayParamIn
void arrayParamIn(CheckpointIn &cp, const std::string &name, CircleBuf< T > &param)
Definition: circlebuf.hh:257
gem5::ParseParam
Definition: serialize_handlers.hh:78
fatal_if
#define fatal_if(cond,...)
Conditional fatal macro that checks the supplied condition and only causes a fatal error if the condi...
Definition: logging.hh:225
gem5
Reference material can be found at the JEDEC website: UFS standard http://www.jedec....
Definition: decoder.cc:40
gem5::CheckpointIn::baseFilename
static const char * baseFilename
Definition: serialize.hh:132
gem5::Serializable::ScopedCheckpointSection
Definition: serialize.hh:172
gem5::CheckpointIn::currentDirectory
static std::string currentDirectory
Definition: serialize.hh:105

Generated on Tue Sep 21 2021 12:25:48 for gem5 by doxygen 1.8.17