gem5
Public Member Functions | Protected Member Functions | Private Member Functions | Private Attributes | Friends | List of all members
Drainable Class Referenceabstract

Interface for objects that might require draining before checkpointing. More...

#include <drain.hh>

Inheritance diagram for Drainable:
ArchTimer BasePixelPump::PixelEvent BaseXBar::Layer< SrcType, DstType > CopyEngine::CopyEngineChannel DistIface DmaCallback DmaPort DmaReadFifo BaseXBar::Layer< MasterPort, SlavePort > BaseXBar::Layer< SlavePort, MasterPort > PacketQueue Queue< Entry > Queue< MSHR > Queue< WriteQueueEntry > SimObject

Public Member Functions

DrainState drainState () const
 Return the current drain state of an object. More...
 
virtual void notifyFork ()
 Notify a child process of a fork. More...
 

Protected Member Functions

 Drainable ()
 
virtual ~Drainable ()
 
virtual DrainState drain ()=0
 Notify an object that it needs to drain its state. More...
 
virtual void drainResume ()
 Resume execution after a successful drain. More...
 
void signalDrainDone () const
 Signal that an object is drained. More...
 

Private Member Functions

DrainState dmDrain ()
 DrainManager interface to request a drain operation. More...
 
void dmDrainResume ()
 DrainManager interface to request a resume operation. More...
 

Private Attributes

DrainManager_drainManager
 Convenience reference to the drain manager. More...
 
DrainState _drainState
 Current drain state of the object. More...
 

Friends

class DrainManager
 

Detailed Description

Interface for objects that might require draining before checkpointing.

An object's internal state needs to be drained when creating a checkpoint, switching between CPU models, or switching between timing models. Once the internal state has been drained from all objects in the simulator, the objects are serialized to disc or the configuration change takes place. The process works as follows (see simulate.py for details):

  1. DrainManager::tryDrain() calls Drainable::drain() for every object in the system. Draining has completed if all of them return true. Otherwise, the drain manager keeps track of the objects that requested draining and waits for them to signal that they are done draining using the signalDrainDone() method.

  2. Continue simulation. When an object has finished draining its internal state, it calls DrainManager::signalDrainDone() on the manager. The drain manager keeps track of the objects that haven't drained yet, simulation stops when the set of non-drained objects becomes empty.

  3. Check if any object still needs draining (DrainManager::tryDrain()), if so repeat the process above.

  4. Serialize objects, switch CPU model, or change timing model.

  5. Call DrainManager::resume(), which in turn calls Drainable::drainResume() for all objects, and then continue the simulation.

Definition at line 223 of file drain.hh.

Constructor & Destructor Documentation

◆ Drainable()

Drainable::Drainable ( )
protected

Definition at line 196 of file drain.cc.

References _drainManager, and DrainManager::registerDrainable().

◆ ~Drainable()

Drainable::~Drainable ( )
protectedvirtual

Definition at line 203 of file drain.cc.

References _drainManager, and DrainManager::unregisterDrainable().

Member Function Documentation

◆ dmDrain()

DrainState Drainable::dmDrain ( )
private

DrainManager interface to request a drain operation.

Definition at line 209 of file drain.cc.

References _drainState, drain(), Drained, and Draining.

◆ dmDrainResume()

void Drainable::dmDrainResume ( )
private

DrainManager interface to request a resume operation.

Definition at line 220 of file drain.cc.

References _drainState, Drained, drainResume(), panic_if, Resuming, and Running.

◆ drain()

virtual DrainState Drainable::drain ( )
protectedpure virtual

Notify an object that it needs to drain its state.

If the object does not need further simulation to drain internal buffers, it returns DrainState::Drained and automatically switches to the Drained state. If the object needs more simulation, it returns DrainState::Draining and automatically enters the Draining state. Other return values are invalid.

Note
An object that has entered the Drained state can be disturbed by other objects in the system and consequently stop being drained. These perturbations are not visible in the drain state. The simulator therefore repeats the draining process until all objects return DrainState::Drained on the first call to drain().
Returns
DrainState::Drained if the object is drained at this point in time, DrainState::Draining if it needs further simulation.

Implemented in DRAMCtrl, ArmISA::TableWalker, DistIface, IGbE, Pl390, DmaReadFifo, BasePixelPump::PixelEvent, Queue< Entry >, Queue< MSHR >, Queue< WriteQueueEntry >, TrafficGen, PacketQueue, DmaCallback, ArchTimer, DRAMSim2, SimpleMemory, SimObject, MuxingKvmGic, UFSHostDevice, RubyPort, DmaPort, BaseXBar::Layer< SrcType, DstType >, BaseXBar::Layer< SlavePort, MasterPort >, BaseXBar::Layer< MasterPort, SlavePort >, CopyEngine::CopyEngineChannel, Process, and FlashDevice.

Referenced by dmDrain().

◆ drainResume()

virtual void Drainable::drainResume ( )
inlineprotectedvirtual

◆ drainState()

DrainState Drainable::drainState ( ) const
inline

◆ notifyFork()

virtual void Drainable::notifyFork ( )
inlinevirtual

Notify a child process of a fork.

When calling fork in gem5, we need to ensure that resources shared between the parent and the child are consistent. This method is intended to be overloaded to handle that. For example, an object could use this method to re-open input files to get a separate file description with a private file offset.

This method is only called in the child of the fork. The call takes place in a drained system.

Reimplemented in KvmVM, CowDiskImage, and RawDiskImage.

Definition at line 296 of file drain.hh.

Referenced by init_drain().

◆ signalDrainDone()

void Drainable::signalDrainDone ( ) const
inlineprotected

Signal that an object is drained.

This method is designed to be called whenever an object enters into a state where it is ready to be drained. The method is safe to call multiple times and there is no need to check that draining has been requested before calling this method.

Definition at line 267 of file drain.hh.

References Drained, Draining, Resuming, and Running.

Referenced by FlashDevice::checkDrain(), IGbE::checkDrain(), UFSHostDevice::checkDrain(), DmaCallback::chunkComplete(), ArmISA::TableWalker::completeDrain(), Queue< WriteQueueEntry >::deallocate(), SimpleMemory::dequeue(), DmaReadFifo::handlePending(), DmaPort::handleResp(), CopyEngine::CopyEngineChannel::inDrain(), Pl390::postDelayedInt(), DRAMCtrl::processNextReqEvent(), DRAMCtrl::processRespondEvent(), TrafficGen::recvReqRetry(), PacketQueue::schedSendEvent(), DRAMSim2::sendResponse(), MinorCPU::signalDrainDone(), RubyPort::testDrainComplete(), and DRAMSim2::writeComplete().

Friends And Related Function Documentation

◆ DrainManager

friend class DrainManager
friend

Definition at line 225 of file drain.hh.

Member Data Documentation

◆ _drainManager

DrainManager& Drainable::_drainManager
private

Convenience reference to the drain manager.

Definition at line 305 of file drain.hh.

Referenced by Drainable(), and ~Drainable().

◆ _drainState

DrainState Drainable::_drainState
mutableprivate

Current drain state of the object.

Needs to be mutable since objects need to be able to signal that they have transitioned into a Drained state even if the calling method is const.

Definition at line 312 of file drain.hh.

Referenced by dmDrain(), and dmDrainResume().


The documentation for this class was generated from the following files:

Generated on Fri Apr 20 2018 09:05:06 for gem5 by doxygen 1.8.13