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

--- 178 unchanged lines hidden (view full) ---

187 * An object's internal state needs to be drained when creating a
188 * checkpoint, switching between CPU models, or switching between
189 * timing models. Once the internal state has been drained from
190 * <i>all</i> objects in the simulator, the objects are serialized to
191 * disc or the configuration change takes place. The process works as
192 * follows (see simulate.py for details):
193 *
194 * <ol>
195 * <li>Call Drainable::drain() for every object in the
196 * system. Draining has completed if all of them return
197 * zero. Otherwise, the sum of the return values is loaded into
198 * the counter of the DrainManager. A pointer to the drain
199 * manager is passed as an argument to the drain() method.
200 *
201 * <li>Continue simulation. When an object has finished draining its
202 * internal state, it calls DrainManager::signalDrainDone() on the
203 * manager. When the counter in the manager reaches zero, the
204 * simulation stops.
205 *
206 * <li>Check if any object still needs draining, if so repeat the
207 * process above.
208 *
209 * <li>Serialize objects, switch CPU model, or change timing model.
210 *
211 * <li>Call Drainable::drainResume() and continue the simulation.
212 * </ol>
213 *
214 */
215class Drainable
216{
217 friend class DrainManager;
218
219 public:
220 Drainable();
221 virtual ~Drainable();
222
223 /**
224 * Determine if an object needs draining and register a
225 * DrainManager.
226 *
227 * When draining the state of an object, the simulator calls drain
228 * with a pointer to a drain manager. If the object does not need
229 * further simulation to drain internal buffers, it switched to
230 * the Drained state and returns 0, otherwise it switches to the
231 * Draining state and returns the number of times that it will
232 * call Event::process() on the drain event. Most objects are
233 * expected to return either 0 or 1.
234 *
235 * @note An object that has entered the Drained state can be
236 * disturbed by other objects in the system and consequently be
237 * forced to enter the Draining state again. The simulator
238 * therefore repeats the draining process until all objects return
239 * 0 on the first call to drain().
240 *
241 * @param drainManager DrainManager to use to inform the simulator
242 * when draining has completed.
243 *
244 * @return 0 if the object is ready for serialization now, >0 if
245 * it needs further simulation.
246 */
247 virtual unsigned int drain(DrainManager *drainManager) = 0;
248
249 /**
250 * Resume execution after a successful drain.
251 *
252 * @note This method is normally only called from the simulation
253 * scripts.
254 */
255 virtual void drainResume();
256
257 DrainState getDrainState() const { return _drainState; }
258
259 protected:
260 void setDrainState(DrainState new_state) { _drainState = new_state; }
261
262 private:
263 DrainManager &_drainManager;
264 DrainState _drainState;
265};
266
267#endif