serialize.hh revision 12450:b5a0300fc327 
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
63class CheckpointIn;
64class IniFile;
65class Serializable;
66class SimObject;
67class SimObjectResolver;
68
69typedef std::ostream CheckpointOut;
70
71
72template <class T>
73void paramOut(CheckpointOut &cp, const std::string &name, const T &param);
74
75template <typename BitUnion>
76void paramOut(CheckpointOut &cp, const std::string &name,
77              const BitfieldBackend::BitUnionOperators<BitUnion> &p)
78{
79    paramOut(cp, name, p.__storage);
80}
81
82template <class T>
83void paramIn(CheckpointIn &cp, const std::string &name, T &param);
84
85template <typename BitUnion>
86void paramIn(CheckpointIn &cp, const std::string &name,
87             BitfieldBackend::BitUnionOperators<BitUnion> &p)
88{
89    paramIn(cp, name, p.__storage);
90}
91
92template <class T>
93bool optParamIn(CheckpointIn &cp, const std::string &name, T &param,
94                bool warn = true);
95
96template <typename BitUnion>
97bool optParamIn(CheckpointIn &cp, const std::string &name,
98                BitfieldBackend::BitUnionOperators<BitUnion> &p,
99                bool warn = true)
100{
101    return optParamIn(cp, name, p.__storage, warn);
102}
103
104template <class T>
105void arrayParamOut(CheckpointOut &cp, const std::string &name,
106                   const T *param, unsigned size);
107
108template <class T>
109void arrayParamOut(CheckpointOut &cp, const std::string &name,
110                   const std::vector<T> &param);
111
112template <class T>
113void arrayParamOut(CheckpointOut &cp, const std::string &name,
114                   const std::list<T> &param);
115
116template <class T>
117void arrayParamOut(CheckpointOut &cp, const std::string &name,
118                   const std::set<T> &param);
119
120template <class T>
121void arrayParamIn(CheckpointIn &cp, const std::string &name,
122                  T *param, unsigned size);
123
124template <class T>
125void arrayParamIn(CheckpointIn &cp, const std::string &name,
126                  std::vector<T> &param);
127
128template <class T>
129void arrayParamIn(CheckpointIn &cp, const std::string &name,
130                  std::list<T> &param);
131
132template <class T>
133void arrayParamIn(CheckpointIn &cp, const std::string &name,
134                  std::set<T> &param);
135
136void
137objParamIn(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 */
220class 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
337void debug_serialize(const std::string &cpt_dir);
338
339
340class 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__
392