drain.hh revision 11800:54436a1784dc
1/* 2 * Copyright (c) 2012, 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 * Redistribution and use in source and binary forms, with or without 15 * modification, are permitted provided that the following conditions are 16 * met: redistributions of source code must retain the above copyright 17 * notice, this list of conditions and the following disclaimer; 18 * redistributions in binary form must reproduce the above copyright 19 * notice, this list of conditions and the following disclaimer in the 20 * documentation and/or other materials provided with the distribution; 21 * neither the name of the copyright holders nor the names of its 22 * contributors may be used to endorse or promote products derived from 23 * this software without specific prior written permission. 24 * 25 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 26 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 27 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 28 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 29 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 30 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 31 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 32 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 33 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 34 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 35 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 36 * 37 * Authors: Andreas Sandberg 38 */ 39 40#ifndef __SIM_DRAIN_HH__ 41#define __SIM_DRAIN_HH__ 42 43#include <atomic> 44#include <mutex> 45#include <unordered_set> 46 47class Drainable; 48 49#ifndef SWIG // SWIG doesn't support strongly typed enums 50/** 51 * Object drain/handover states 52 * 53 * An object starts out in the Running state. When the simulator 54 * prepares to take a snapshot or prepares a CPU for handover, it 55 * calls the drain() method to transfer the object into the Draining 56 * or Drained state. If any object enters the Draining state 57 * (Drainable::drain() returning >0), simulation continues until it 58 * all objects have entered the Drained state. 59 * 60 * Before resuming simulation, the simulator calls resume() to 61 * transfer the object to the Running state. 62 * 63 * \note Even though the state of an object (visible to the rest of 64 * the world through Drainable::getState()) could be used to determine 65 * if all objects have entered the Drained state, the protocol is 66 * actually a bit more elaborate. See Drainable::drain() for details. 67 */ 68enum class DrainState { 69 Running, /** Running normally */ 70 Draining, /** Draining buffers pending serialization/handover */ 71 Drained /** Buffers drained, ready for serialization/handover */ 72}; 73#endif 74 75/** 76 * This class coordinates draining of a System. 77 * 78 * When draining the simulator, we need to make sure that all 79 * Drainable objects within the system have ended up in the drained 80 * state before declaring the operation to be successful. This class 81 * keeps track of how many objects are still in the process of 82 * draining. Once it determines that all objects have drained their 83 * state, it exits the simulation loop. 84 * 85 * @note A System might not be completely drained even though the 86 * DrainManager has caused the simulation loop to exit. Draining needs 87 * to be restarted until all Drainable objects declare that they don't 88 * need further simulation to be completely drained. See Drainable for 89 * more information. 90 */ 91class DrainManager 92{ 93 private: 94 DrainManager(); 95#ifndef SWIG 96 DrainManager(DrainManager &) = delete; 97#endif 98 ~DrainManager(); 99 100 public: 101 /** Get the singleton DrainManager instance */ 102 static DrainManager &instance() { return _instance; } 103 104 /** 105 * Try to drain the system. 106 * 107 * Try to drain the system and return true if all objects are in a 108 * the Drained state at which point the whole simulator is in a 109 * consistent state and ready for checkpointing or CPU 110 * handover. The simulation script must continue simulating until 111 * the simulation loop returns "Finished drain", at which point 112 * this method should be called again. This cycle should continue 113 * until this method returns true. 114 * 115 * @return true if all objects were drained successfully, false if 116 * more simulation is needed. 117 */ 118 bool tryDrain(); 119 120 /** 121 * Resume normal simulation in a Drained system. 122 */ 123 void resume(); 124 125 /** 126 * Run state fixups before a checkpoint restore operation 127 * 128 * The drain state of an object isn't stored in a checkpoint since 129 * the whole system is always going to be in the Drained state 130 * when the checkpoint is created. When the checkpoint is restored 131 * at a later stage, recreated objects will be in the Running 132 * state since the state isn't stored in checkpoints. This method 133 * performs state fixups on all Drainable objects and the 134 * DrainManager itself. 135 */ 136 void preCheckpointRestore(); 137 138 /** Check if the system is drained */ 139 bool isDrained() const { return _state == DrainState::Drained; } 140 141 /** Get the simulators global drain state */ 142 DrainState state() const { return _state; } 143 144 /** 145 * Notify the DrainManager that a Drainable object has finished 146 * draining. 147 */ 148 void signalDrainDone(); 149 150 public: 151 void registerDrainable(Drainable *obj); 152 void unregisterDrainable(Drainable *obj); 153 154 private: 155 /** 156 * Thread-safe helper function to get the number of Drainable 157 * objects in a system. 158 */ 159 size_t drainableCount() const; 160 161 /** Lock protecting the set of drainable objects */ 162 mutable std::mutex globalLock; 163 164 /** Set of all drainable objects */ 165 std::unordered_set<Drainable *> _allDrainable; 166 167 /** 168 * Number of objects still draining. This is flagged atomic since 169 * it can be manipulated by SimObjects living in different 170 * threads. 171 */ 172 std::atomic_uint _count; 173 174 /** Global simulator drain state */ 175 DrainState _state; 176 177 /** Singleton instance of the drain manager */ 178 static DrainManager _instance; 179}; 180 181/** 182 * Interface for objects that might require draining before 183 * checkpointing. 184 * 185 * An object's internal state needs to be drained when creating a 186 * checkpoint, switching between CPU models, or switching between 187 * timing models. Once the internal state has been drained from 188 * <i>all</i> objects in the simulator, the objects are serialized to 189 * disc or the configuration change takes place. The process works as 190 * follows (see simulate.py for details): 191 * 192 * <ol> 193 * <li>DrainManager::tryDrain() calls Drainable::drain() for every 194 * object in the system. Draining has completed if all of them 195 * return true. Otherwise, the drain manager keeps track of the 196 * objects that requested draining and waits for them to signal 197 * that they are done draining using the signalDrainDone() method. 198 * 199 * <li>Continue simulation. When an object has finished draining its 200 * internal state, it calls DrainManager::signalDrainDone() on the 201 * manager. The drain manager keeps track of the objects that 202 * haven't drained yet, simulation stops when the set of 203 * non-drained objects becomes empty. 204 * 205 * <li>Check if any object still needs draining 206 * (DrainManager::tryDrain()), if so repeat the process above. 207 * 208 * <li>Serialize objects, switch CPU model, or change timing model. 209 * 210 * <li>Call DrainManager::resume(), which in turn calls 211 * Drainable::drainResume() for all objects, and then continue the 212 * simulation. 213 * </ol> 214 * 215 */ 216class Drainable 217{ 218 friend class DrainManager; 219 220 protected: 221 Drainable(); 222 virtual ~Drainable(); 223 224 /** 225 * Notify an object that it needs to drain its state. 226 * 227 * If the object does not need further simulation to drain 228 * internal buffers, it returns DrainState::Drained and 229 * automatically switches to the Drained state. If the object 230 * needs more simulation, it returns DrainState::Draining and 231 * automatically enters the Draining state. Other return values 232 * are invalid. 233 * 234 * @note An object that has entered the Drained state can be 235 * disturbed by other objects in the system and consequently stop 236 * being drained. These perturbations are not visible in the drain 237 * state. The simulator therefore repeats the draining process 238 * until all objects return DrainState::Drained on the first call 239 * to drain(). 240 * 241 * @return DrainState::Drained if the object is drained at this 242 * point in time, DrainState::Draining if it needs further 243 * simulation. 244 */ 245 virtual DrainState drain() = 0; 246 247 /** 248 * Resume execution after a successful drain. 249 */ 250 virtual void drainResume() {}; 251 252 /** 253 * Signal that an object is drained 254 * 255 * This method is designed to be called whenever an object enters 256 * into a state where it is ready to be drained. The method is 257 * safe to call multiple times and there is no need to check that 258 * draining has been requested before calling this method. 259 */ 260 void signalDrainDone() const { 261 switch (_drainState) { 262 case DrainState::Running: 263 case DrainState::Drained: 264 return; 265 case DrainState::Draining: 266 _drainState = DrainState::Drained; 267 _drainManager.signalDrainDone(); 268 return; 269 } 270 } 271 272 public: 273 /** Return the current drain state of an object. */ 274 DrainState drainState() const { return _drainState; } 275 276 /** 277 * Notify a child process of a fork. 278 * 279 * When calling fork in gem5, we need to ensure that resources 280 * shared between the parent and the child are consistent. This 281 * method is intended to be overloaded to handle that. For 282 * example, an object could use this method to re-open input files 283 * to get a separate file description with a private file offset. 284 * 285 * This method is only called in the child of the fork. The call 286 * takes place in a drained system. 287 */ 288 virtual void notifyFork() {}; 289 290 private: 291 /** DrainManager interface to request a drain operation */ 292 DrainState dmDrain(); 293 /** DrainManager interface to request a resume operation */ 294 void dmDrainResume(); 295 296 /** Convenience reference to the drain manager */ 297 DrainManager &_drainManager; 298 299 /** 300 * Current drain state of the object. Needs to be mutable since 301 * objects need to be able to signal that they have transitioned 302 * into a Drained state even if the calling method is const. 303 */ 304 mutable DrainState _drainState; 305}; 306 307#endif 308