drain.hh (11937:e6621fafa62d) | drain.hh (11990:5fad911cc326) |
---|---|
1/* 2 * Copyright (c) 2012, 2015, 2017 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 <vector> 46 47class Drainable; 48 | 1/* 2 * Copyright (c) 2012, 2015, 2017 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 <vector> 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. This in turn results in a 62 * call to drainResume() for all Drainable objects in the 63 * simulator. New Drainable objects may be created while resuming. In 64 * such cases, the new objects will be created in the Resuming state 65 * and later resumed. 66 * 67 * \note Even though the state of an object (visible to the rest of 68 * the world through Drainable::getState()) could be used to determine 69 * if all objects have entered the Drained state, the protocol is 70 * actually a bit more elaborate. See Drainable::drain() for details. 71 */ 72enum class DrainState { 73 Running, /** Running normally */ 74 Draining, /** Draining buffers pending serialization/handover */ 75 Drained, /** Buffers drained, ready for serialization/handover */ 76 Resuming, /** Transient state while the simulator is resuming */ 77}; | 49/** 50 * Object drain/handover states 51 * 52 * An object starts out in the Running state. When the simulator 53 * prepares to take a snapshot or prepares a CPU for handover, it 54 * calls the drain() method to transfer the object into the Draining 55 * or Drained state. If any object enters the Draining state 56 * (Drainable::drain() returning >0), simulation continues until it 57 * all objects have entered the Drained state. 58 * 59 * Before resuming simulation, the simulator calls resume() to 60 * transfer the object to the Running state. This in turn results in a 61 * call to drainResume() for all Drainable objects in the 62 * simulator. New Drainable objects may be created while resuming. In 63 * such cases, the new objects will be created in the Resuming state 64 * and later resumed. 65 * 66 * \note Even though the state of an object (visible to the rest of 67 * the world through Drainable::getState()) could be used to determine 68 * if all objects have entered the Drained state, the protocol is 69 * actually a bit more elaborate. See Drainable::drain() for details. 70 */ 71enum class DrainState { 72 Running, /** Running normally */ 73 Draining, /** Draining buffers pending serialization/handover */ 74 Drained, /** Buffers drained, ready for serialization/handover */ 75 Resuming, /** Transient state while the simulator is resuming */ 76}; |
78#endif | |
79 80/** 81 * This class coordinates draining of a System. 82 * 83 * When draining the simulator, we need to make sure that all 84 * Drainable objects within the system have ended up in the drained 85 * state before declaring the operation to be successful. This class 86 * keeps track of how many objects are still in the process of 87 * draining. Once it determines that all objects have drained their 88 * state, it exits the simulation loop. 89 * 90 * @note A System might not be completely drained even though the 91 * DrainManager has caused the simulation loop to exit. Draining needs 92 * to be restarted until all Drainable objects declare that they don't 93 * need further simulation to be completely drained. See Drainable for 94 * more information. 95 */ 96class DrainManager 97{ 98 private: 99 DrainManager(); | 77 78/** 79 * This class coordinates draining of a System. 80 * 81 * When draining the simulator, we need to make sure that all 82 * Drainable objects within the system have ended up in the drained 83 * state before declaring the operation to be successful. This class 84 * keeps track of how many objects are still in the process of 85 * draining. Once it determines that all objects have drained their 86 * state, it exits the simulation loop. 87 * 88 * @note A System might not be completely drained even though the 89 * DrainManager has caused the simulation loop to exit. Draining needs 90 * to be restarted until all Drainable objects declare that they don't 91 * need further simulation to be completely drained. See Drainable for 92 * more information. 93 */ 94class DrainManager 95{ 96 private: 97 DrainManager(); |
100#ifndef SWIG | |
101 DrainManager(DrainManager &) = delete; | 98 DrainManager(DrainManager &) = delete; |
102#endif | |
103 ~DrainManager(); 104 105 public: 106 /** Get the singleton DrainManager instance */ 107 static DrainManager &instance() { return _instance; } 108 109 /** 110 * Try to drain the system. 111 * 112 * Try to drain the system and return true if all objects are in a 113 * the Drained state at which point the whole simulator is in a 114 * consistent state and ready for checkpointing or CPU 115 * handover. The simulation script must continue simulating until 116 * the simulation loop returns "Finished drain", at which point 117 * this method should be called again. This cycle should continue 118 * until this method returns true. 119 * 120 * @return true if all objects were drained successfully, false if 121 * more simulation is needed. 122 */ 123 bool tryDrain(); 124 125 /** 126 * Resume normal simulation in a Drained system. 127 */ 128 void resume(); 129 130 /** 131 * Run state fixups before a checkpoint restore operation 132 * 133 * The drain state of an object isn't stored in a checkpoint since 134 * the whole system is always going to be in the Drained state 135 * when the checkpoint is created. When the checkpoint is restored 136 * at a later stage, recreated objects will be in the Running 137 * state since the state isn't stored in checkpoints. This method 138 * performs state fixups on all Drainable objects and the 139 * DrainManager itself. 140 */ 141 void preCheckpointRestore(); 142 143 /** Check if the system is drained */ 144 bool isDrained() const { return _state == DrainState::Drained; } 145 146 /** Get the simulators global drain state */ 147 DrainState state() const { return _state; } 148 149 /** 150 * Notify the DrainManager that a Drainable object has finished 151 * draining. 152 */ 153 void signalDrainDone(); 154 155 public: 156 void registerDrainable(Drainable *obj); 157 void unregisterDrainable(Drainable *obj); 158 159 private: 160 /** 161 * Helper function to check if all Drainable objects are in a 162 * specific state. 163 */ 164 bool allInState(DrainState state) const; 165 166 /** 167 * Thread-safe helper function to get the number of Drainable 168 * objects in a system. 169 */ 170 size_t drainableCount() const; 171 172 /** Lock protecting the set of drainable objects */ 173 mutable std::mutex globalLock; 174 175 /** Set of all drainable objects */ 176 std::vector<Drainable *> _allDrainable; 177 178 /** 179 * Number of objects still draining. This is flagged atomic since 180 * it can be manipulated by SimObjects living in different 181 * threads. 182 */ 183 std::atomic_uint _count; 184 185 /** Global simulator drain state */ 186 DrainState _state; 187 188 /** Singleton instance of the drain manager */ 189 static DrainManager _instance; 190}; 191 192/** 193 * Interface for objects that might require draining before 194 * checkpointing. 195 * 196 * An object's internal state needs to be drained when creating a 197 * checkpoint, switching between CPU models, or switching between 198 * timing models. Once the internal state has been drained from 199 * <i>all</i> objects in the simulator, the objects are serialized to 200 * disc or the configuration change takes place. The process works as 201 * follows (see simulate.py for details): 202 * 203 * <ol> 204 * <li>DrainManager::tryDrain() calls Drainable::drain() for every 205 * object in the system. Draining has completed if all of them 206 * return true. Otherwise, the drain manager keeps track of the 207 * objects that requested draining and waits for them to signal 208 * that they are done draining using the signalDrainDone() method. 209 * 210 * <li>Continue simulation. When an object has finished draining its 211 * internal state, it calls DrainManager::signalDrainDone() on the 212 * manager. The drain manager keeps track of the objects that 213 * haven't drained yet, simulation stops when the set of 214 * non-drained objects becomes empty. 215 * 216 * <li>Check if any object still needs draining 217 * (DrainManager::tryDrain()), if so repeat the process above. 218 * 219 * <li>Serialize objects, switch CPU model, or change timing model. 220 * 221 * <li>Call DrainManager::resume(), which in turn calls 222 * Drainable::drainResume() for all objects, and then continue the 223 * simulation. 224 * </ol> 225 * 226 */ 227class Drainable 228{ 229 friend class DrainManager; 230 231 protected: 232 Drainable(); 233 virtual ~Drainable(); 234 235 /** 236 * Notify an object that it needs to drain its state. 237 * 238 * If the object does not need further simulation to drain 239 * internal buffers, it returns DrainState::Drained and 240 * automatically switches to the Drained state. If the object 241 * needs more simulation, it returns DrainState::Draining and 242 * automatically enters the Draining state. Other return values 243 * are invalid. 244 * 245 * @note An object that has entered the Drained state can be 246 * disturbed by other objects in the system and consequently stop 247 * being drained. These perturbations are not visible in the drain 248 * state. The simulator therefore repeats the draining process 249 * until all objects return DrainState::Drained on the first call 250 * to drain(). 251 * 252 * @return DrainState::Drained if the object is drained at this 253 * point in time, DrainState::Draining if it needs further 254 * simulation. 255 */ 256 virtual DrainState drain() = 0; 257 258 /** 259 * Resume execution after a successful drain. 260 */ 261 virtual void drainResume() {}; 262 263 /** 264 * Signal that an object is drained 265 * 266 * This method is designed to be called whenever an object enters 267 * into a state where it is ready to be drained. The method is 268 * safe to call multiple times and there is no need to check that 269 * draining has been requested before calling this method. 270 */ 271 void signalDrainDone() const { 272 switch (_drainState) { 273 case DrainState::Running: 274 case DrainState::Drained: 275 case DrainState::Resuming: 276 return; 277 case DrainState::Draining: 278 _drainState = DrainState::Drained; 279 _drainManager.signalDrainDone(); 280 return; 281 } 282 } 283 284 public: 285 /** Return the current drain state of an object. */ 286 DrainState drainState() const { return _drainState; } 287 288 /** 289 * Notify a child process of a fork. 290 * 291 * When calling fork in gem5, we need to ensure that resources 292 * shared between the parent and the child are consistent. This 293 * method is intended to be overloaded to handle that. For 294 * example, an object could use this method to re-open input files 295 * to get a separate file description with a private file offset. 296 * 297 * This method is only called in the child of the fork. The call 298 * takes place in a drained system. 299 */ 300 virtual void notifyFork() {}; 301 302 private: 303 /** DrainManager interface to request a drain operation */ 304 DrainState dmDrain(); 305 /** DrainManager interface to request a resume operation */ 306 void dmDrainResume(); 307 308 /** Convenience reference to the drain manager */ 309 DrainManager &_drainManager; 310 311 /** 312 * Current drain state of the object. Needs to be mutable since 313 * objects need to be able to signal that they have transitioned 314 * into a Drained state even if the calling method is const. 315 */ 316 mutable DrainState _drainState; 317}; 318 319#endif | 99 ~DrainManager(); 100 101 public: 102 /** Get the singleton DrainManager instance */ 103 static DrainManager &instance() { return _instance; } 104 105 /** 106 * Try to drain the system. 107 * 108 * Try to drain the system and return true if all objects are in a 109 * the Drained state at which point the whole simulator is in a 110 * consistent state and ready for checkpointing or CPU 111 * handover. The simulation script must continue simulating until 112 * the simulation loop returns "Finished drain", at which point 113 * this method should be called again. This cycle should continue 114 * until this method returns true. 115 * 116 * @return true if all objects were drained successfully, false if 117 * more simulation is needed. 118 */ 119 bool tryDrain(); 120 121 /** 122 * Resume normal simulation in a Drained system. 123 */ 124 void resume(); 125 126 /** 127 * Run state fixups before a checkpoint restore operation 128 * 129 * The drain state of an object isn't stored in a checkpoint since 130 * the whole system is always going to be in the Drained state 131 * when the checkpoint is created. When the checkpoint is restored 132 * at a later stage, recreated objects will be in the Running 133 * state since the state isn't stored in checkpoints. This method 134 * performs state fixups on all Drainable objects and the 135 * DrainManager itself. 136 */ 137 void preCheckpointRestore(); 138 139 /** Check if the system is drained */ 140 bool isDrained() const { return _state == DrainState::Drained; } 141 142 /** Get the simulators global drain state */ 143 DrainState state() const { return _state; } 144 145 /** 146 * Notify the DrainManager that a Drainable object has finished 147 * draining. 148 */ 149 void signalDrainDone(); 150 151 public: 152 void registerDrainable(Drainable *obj); 153 void unregisterDrainable(Drainable *obj); 154 155 private: 156 /** 157 * Helper function to check if all Drainable objects are in a 158 * specific state. 159 */ 160 bool allInState(DrainState state) const; 161 162 /** 163 * Thread-safe helper function to get the number of Drainable 164 * objects in a system. 165 */ 166 size_t drainableCount() const; 167 168 /** Lock protecting the set of drainable objects */ 169 mutable std::mutex globalLock; 170 171 /** Set of all drainable objects */ 172 std::vector<Drainable *> _allDrainable; 173 174 /** 175 * Number of objects still draining. This is flagged atomic since 176 * it can be manipulated by SimObjects living in different 177 * threads. 178 */ 179 std::atomic_uint _count; 180 181 /** Global simulator drain state */ 182 DrainState _state; 183 184 /** Singleton instance of the drain manager */ 185 static DrainManager _instance; 186}; 187 188/** 189 * Interface for objects that might require draining before 190 * checkpointing. 191 * 192 * An object's internal state needs to be drained when creating a 193 * checkpoint, switching between CPU models, or switching between 194 * timing models. Once the internal state has been drained from 195 * <i>all</i> objects in the simulator, the objects are serialized to 196 * disc or the configuration change takes place. The process works as 197 * follows (see simulate.py for details): 198 * 199 * <ol> 200 * <li>DrainManager::tryDrain() calls Drainable::drain() for every 201 * object in the system. Draining has completed if all of them 202 * return true. Otherwise, the drain manager keeps track of the 203 * objects that requested draining and waits for them to signal 204 * that they are done draining using the signalDrainDone() method. 205 * 206 * <li>Continue simulation. When an object has finished draining its 207 * internal state, it calls DrainManager::signalDrainDone() on the 208 * manager. The drain manager keeps track of the objects that 209 * haven't drained yet, simulation stops when the set of 210 * non-drained objects becomes empty. 211 * 212 * <li>Check if any object still needs draining 213 * (DrainManager::tryDrain()), if so repeat the process above. 214 * 215 * <li>Serialize objects, switch CPU model, or change timing model. 216 * 217 * <li>Call DrainManager::resume(), which in turn calls 218 * Drainable::drainResume() for all objects, and then continue the 219 * simulation. 220 * </ol> 221 * 222 */ 223class Drainable 224{ 225 friend class DrainManager; 226 227 protected: 228 Drainable(); 229 virtual ~Drainable(); 230 231 /** 232 * Notify an object that it needs to drain its state. 233 * 234 * If the object does not need further simulation to drain 235 * internal buffers, it returns DrainState::Drained and 236 * automatically switches to the Drained state. If the object 237 * needs more simulation, it returns DrainState::Draining and 238 * automatically enters the Draining state. Other return values 239 * are invalid. 240 * 241 * @note An object that has entered the Drained state can be 242 * disturbed by other objects in the system and consequently stop 243 * being drained. These perturbations are not visible in the drain 244 * state. The simulator therefore repeats the draining process 245 * until all objects return DrainState::Drained on the first call 246 * to drain(). 247 * 248 * @return DrainState::Drained if the object is drained at this 249 * point in time, DrainState::Draining if it needs further 250 * simulation. 251 */ 252 virtual DrainState drain() = 0; 253 254 /** 255 * Resume execution after a successful drain. 256 */ 257 virtual void drainResume() {}; 258 259 /** 260 * Signal that an object is drained 261 * 262 * This method is designed to be called whenever an object enters 263 * into a state where it is ready to be drained. The method is 264 * safe to call multiple times and there is no need to check that 265 * draining has been requested before calling this method. 266 */ 267 void signalDrainDone() const { 268 switch (_drainState) { 269 case DrainState::Running: 270 case DrainState::Drained: 271 case DrainState::Resuming: 272 return; 273 case DrainState::Draining: 274 _drainState = DrainState::Drained; 275 _drainManager.signalDrainDone(); 276 return; 277 } 278 } 279 280 public: 281 /** Return the current drain state of an object. */ 282 DrainState drainState() const { return _drainState; } 283 284 /** 285 * Notify a child process of a fork. 286 * 287 * When calling fork in gem5, we need to ensure that resources 288 * shared between the parent and the child are consistent. This 289 * method is intended to be overloaded to handle that. For 290 * example, an object could use this method to re-open input files 291 * to get a separate file description with a private file offset. 292 * 293 * This method is only called in the child of the fork. The call 294 * takes place in a drained system. 295 */ 296 virtual void notifyFork() {}; 297 298 private: 299 /** DrainManager interface to request a drain operation */ 300 DrainState dmDrain(); 301 /** DrainManager interface to request a resume operation */ 302 void dmDrainResume(); 303 304 /** Convenience reference to the drain manager */ 305 DrainManager &_drainManager; 306 307 /** 308 * Current drain state of the object. Needs to be mutable since 309 * objects need to be able to signal that they have transitioned 310 * into a Drained state even if the calling method is const. 311 */ 312 mutable DrainState _drainState; 313}; 314 315#endif |