src/sim/sim_object.hh

   1 /*
   2  * Copyright (c) 2015 ARM Limited
   3  * All rights reserved
   4  *
   5  * The license below extends only to copyright in the software and shall
   6  * not be construed as granting a license to any other intellectual
   7  * property including but not limited to intellectual property relating
   8  * to a hardware implementation of the functionality of the software
   9  * licensed hereunder.  You may use the software subject to the license
  10  * terms below provided that you ensure that this notice is replicated
  11  * unmodified and in its entirety in all distributions of the software,
  12  * modified or unmodified, in source code or in binary form.
  13  *
  14  * Copyright (c) 2001-2005 The Regents of The University of Michigan
  15  * Copyright (c) 2010 Advanced Micro Devices, Inc.
  16  * All rights reserved.
  17  *
  18  * Redistribution and use in source and binary forms, with or without
  19  * modification, are permitted provided that the following conditions are
  20  * met: redistributions of source code must retain the above copyright
  21  * notice, this list of conditions and the following disclaimer;
  22  * redistributions in binary form must reproduce the above copyright
  23  * notice, this list of conditions and the following disclaimer in the
  24  * documentation and/or other materials provided with the distribution;
  25  * neither the name of the copyright holders nor the names of its
  26  * contributors may be used to endorse or promote products derived from
  27  * this software without specific prior written permission.
  28  *
  29  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  30  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  31  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  32  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  33  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  34  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  35  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  36  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  37  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  38  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  39  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  40  */
  41
  42 /* @file
  43  * User Console Definitions
  44  */
  45
  46 #ifndef __SIM_OBJECT_HH__
  47 #define __SIM_OBJECT_HH__
  48
  49 #include <string>
  50 #include <vector>
  51
  52 #include "base/stats/group.hh"
  53 #include "params/SimObject.hh"
  54 #include "sim/drain.hh"
  55 #include "sim/eventq.hh"
  56 #include "sim/port.hh"
  57 #include "sim/serialize.hh"
  58
  59 class EventManager;
  60 class ProbeManager;
  61
  62 /**
  63  * Abstract superclass for simulation objects.  Represents things that
  64  * correspond to physical components and can be specified via the
  65  * config file (CPUs, caches, etc.).
  66  *
  67  * SimObject initialization is controlled by the instantiate method in
  68  * src/python/m5/simulate.py. There are slightly different
  69  * initialization paths when starting the simulation afresh and when
  70  * loading from a checkpoint.  After instantiation and connecting
  71  * ports, simulate.py initializes the object using the following call
  72  * sequence:
  73  *
  74  * <ol>
  75  * <li>SimObject::init()
  76  * <li>SimObject::regStats()
  77  * <li><ul>
  78  *     <li>SimObject::initState() if starting afresh.
  79  *     <li>SimObject::loadState() if restoring from a checkpoint.
  80  *     </ul>
  81  * <li>SimObject::resetStats()
  82  * <li>SimObject::startup()
  83  * <li>Drainable::drainResume() if resuming from a checkpoint.
  84  * </ol>
  85  *
  86  * @note Whenever a method is called on all objects in the simulator's
  87  * object tree (e.g., init(), startup(), or loadState()), a pre-order
  88  * depth-first traversal is performed (see descendants() in
  89  * SimObject.py). This has the effect of calling the method on the
  90  * parent node <i>before</i> its children.
  91  *
  92  * The python version of a SimObject class actually represents its Params
  93  * structure which holds all its parameter settings and its name. When python
  94  * needs to create a C++ instance of one of those classes, it uses the Params
  95  * struct's create() method which returns one instance, set up with the
  96  * parameters in the struct.
  97  *
  98  * When writing a SimObject class, there are three different cases as far as
  99  * what you need to do to support the create() method, for hypothetical class
 100  * Foo.
 101  *
 102  * If you have a constructor with a signature like this:
 103  *
 104  * Foo(const FooParams &)
 105  *
 106  * you don't have to do anything, a create method will be automatically
 107  * defined which will call your constructor and return that instance. You
 108  * should use this option most of the time.
 109  *
 110  * If you have a constructor with that signature but still want to define
 111  * your own create method for some reason, you can do that by providing an
 112  * alternative implementation which will override the default. It should have
 113  * this signature:
 114  *
 115  * Foo *FooParams::create() const;
 116  *
 117  * If you don't have a constructor with that signature at all, then you must
 118  * implement the create method with that signature which will build your
 119  * object in some other way.
 120  */
 121 class SimObject : public EventManager, public Serializable, public Drainable,
 122                   public Stats::Group
 123 {
 124   private:
 125     typedef std::vector<SimObject *> SimObjectList;
 126
 127     /** List of all instantiated simulation objects. */
 128     static SimObjectList simObjectList;
 129
 130     /** Manager coordinates hooking up probe points with listeners. */
 131     ProbeManager *probeManager;
 132
 133   protected:
 134     /**
 135      * Cached copy of the object parameters.
 136      *
 137      * @ingroup api_simobject
 138      */
 139     const SimObjectParams &_params;
 140
 141   public:
 142     typedef SimObjectParams Params;
 143     /**
 144      * @return This function returns the cached copy of the object parameters.
 145      *
 146      * @ingroup api_simobject
 147      */
 148     const Params &params() const { return _params; }
 149
 150     /**
 151      * @ingroup api_simobject
 152      */
 153     SimObject(const Params &_params);
 154
 155     virtual ~SimObject();
 156
 157   public:
 158
 159     /**
 160      * @ingroup api_simobject
 161      */
 162     virtual const std::string name() const { return params().name; }
 163
 164     /**
 165      * init() is called after all C++ SimObjects have been created and
 166      * all ports are connected.  Initializations that are independent
 167      * of unserialization but rely on a fully instantiated and
 168      * connected SimObject graph should be done here.
 169      *
 170      * @ingroup api_simobject
 171      */
 172     virtual void init();
 173
 174     /**
 175      * loadState() is called on each SimObject when restoring from a
 176      * checkpoint.  The default implementation simply calls
 177      * unserialize() if there is a corresponding section in the
 178      * checkpoint.  However, objects can override loadState() to get
 179      * other behaviors, e.g., doing other programmed initializations
 180      * after unserialize(), or complaining if no checkpoint section is
 181      * found.
 182      *
 183      * @param cp Checkpoint to restore the state from.
 184      *
 185      * @ingroup api_serialize
 186      */
 187     virtual void loadState(CheckpointIn &cp);
 188
 189     /**
 190      * initState() is called on each SimObject when *not* restoring
 191      * from a checkpoint.  This provides a hook for state
 192      * initializations that are only required for a "cold start".
 193      *
 194      * @ingroup api_serialize
 195      */
 196     virtual void initState();
 197
 198     /**
 199      * Register probe points for this object.
 200      *
 201      * @ingroup api_simobject
 202      */
 203     virtual void regProbePoints();
 204
 205     /**
 206      * Register probe listeners for this object.
 207      *
 208      * @ingroup api_simobject
 209      */
 210     virtual void regProbeListeners();
 211
 212     /**
 213      * Get the probe manager for this object.
 214      *
 215      * Probes generate traces. A trace is a file that
 216      * keeps a log of events. For example, we can have a probe
 217      * listener for an address and the trace will be a file that
 218      * has time stamps for all the reads and writes to that address.
 219      *
 220      * @ingroup api_simobject
 221      */
 222     ProbeManager *getProbeManager();
 223
 224     /**
 225      * Get a port with a given name and index. This is used at binding time
 226      * and returns a reference to a protocol-agnostic port.
 227      *
 228      * gem5 has a request and response port interface. All memory objects
 229      * are connected together via ports. These ports provide a rigid
 230      * interface between these memory objects. These ports implement
 231      * three different memory system modes: timing, atomic, and
 232      * functional. The most important mode is the timing mode and here
 233      * timing mode is used for conducting cycle-level timing
 234      * experiments. The other modes are only used in special
 235      * circumstances and should *not* be used to conduct cycle-level
 236      * timing experiments. The other modes are only used in special
 237      * circumstances. These ports allow SimObjects to communicate with
 238      * each other.
 239      *
 240      * @param if_name Port name
 241      * @param idx Index in the case of a VectorPort
 242      *
 243      * @return A reference to the given port
 244      *
 245      * @ingroup api_simobject
 246      */
 247     virtual Port &getPort(const std::string &if_name,
 248                           PortID idx=InvalidPortID);
 249
 250     /**
 251      * startup() is the final initialization call before simulation.
 252      * All state is initialized (including unserialized state, if any,
 253      * such as the curTick() value), so this is the appropriate place to
 254      * schedule initial event(s) for objects that need them.
 255      *
 256      * @ingroup api_simobject
 257      */
 258     virtual void startup();
 259
 260     /**
 261      * Provide a default implementation of the drain interface for
 262      * objects that don't need draining.
 263      */
 264     DrainState drain() override { return DrainState::Drained; }
 265
 266     /**
 267      * Write back dirty buffers to memory using functional writes.
 268      *
 269      * After returning, an object implementing this method should have
 270      * written all its dirty data back to memory. This method is
 271      * typically used to prepare a system with caches for
 272      * checkpointing.
 273      *
 274      * @ingroup api_simobject
 275      */
 276     virtual void memWriteback() {};
 277
 278     /**
 279      * Invalidate the contents of memory buffers.
 280      *
 281      * When the switching to hardware virtualized CPU models, we need
 282      * to make sure that we don't have any cached state in the system
 283      * that might become stale when we return. This method is used to
 284      * flush all such state back to main memory.
 285      *
 286      * @warn This does <i>not</i> cause any dirty state to be written
 287      * back to memory.
 288      *
 289      * @ingroup api_simobject
 290      */
 291     virtual void memInvalidate() {};
 292
 293     void serialize(CheckpointOut &cp) const override {};
 294     void unserialize(CheckpointIn &cp) override {};
 295
 296     /**
 297      * Serialize all SimObjects in the system.
 298      */
 299     static void serializeAll(CheckpointOut &cp);
 300
 301 #ifdef DEBUG
 302   public:
 303     bool doDebugBreak;
 304     static void debugObjectBreak(const std::string &objs);
 305 #endif
 306
 307     /**
 308      * Find the SimObject with the given name and return a pointer to
 309      * it.  Primarily used for interactive debugging.  Argument is
 310      * char* rather than std::string to make it callable from gdb.
 311      *
 312      * @ingroup api_simobject
 313      */
 314     static SimObject *find(const char *name);
 315 };
 316
 317 /**
 318  * Base class to wrap object resolving functionality.
 319  *
 320  * This can be provided to the serialization framework to allow it to
 321  * map object names onto C++ objects.
 322  */
 323 class SimObjectResolver
 324 {
 325   public:
 326     virtual ~SimObjectResolver() { }
 327
 328     /**
 329      * Find a SimObject given a full path name
 330      *
 331      * @ingroup api_serialize
 332      */
 333     virtual SimObject *resolveSimObject(const std::string &name) = 0;
 334 };
 335
 336 #ifdef DEBUG
 337 void debugObjectBreak(const char *objs);
 338 #endif
 339
 340 #endif // __SIM_OBJECT_HH__