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

#include <drain.hh>

Inheritance diagram for Drainable:

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):

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.
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.
Check if any object still needs draining (DrainManager::tryDrain()), if so repeat the process above.
Serialize objects, switch CPU model, or change timing model.
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 ( )

protected

Definition at line 196 of file drain.cc.

References _drainManager, and DrainManager::registerDrainable().

Drainable::~Drainable ( )

protectedvirtual

Definition at line 203 of file drain.cc.

References _drainManager, and DrainManager::unregisterDrainable().

Member Function Documentation

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.

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.

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, 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().

virtual void Drainable::drainResume ( )

inlineprotectedvirtual

Resume execution after a successful drain.

Reimplemented in DRAMCtrl, ArmISA::TableWalker, DistIface, IGbE, System, NSGigE, ArmISA::TLB, Sinic::Device, BasePixelPump::PixelEvent, MuxingKvmGic, CopyEngine::CopyEngineChannel, HDLcd, ArmISA::PMU, and RubySystem.

Definition at line 257 of file drain.hh.

Referenced by dmDrainResume(), HDLcd::drainResume(), MuxingKvmGic::drainResume(), Sinic::Device::drainResume(), NSGigE::drainResume(), and IGbE::drainResume().

DrainState Drainable::drainState ( ) const

inline

Return the current drain state of an object.

Definition at line 282 of file drain.hh.

References _drainState.

Referenced by FlashDevice::checkDrain(), UFSHostDevice::checkDrain(), IGbE::checkDrain(), ArmISA::TableWalker::completeDrain(), Queue< WriteQueueEntry >::deallocate(), SimpleMemory::dequeue(), IdeDisk::doDmaRead(), IdeDisk::doDmaTransfer(), IdeDisk::doDmaWrite(), NSGigE::doRxDmaRead(), NSGigE::doRxDmaWrite(), NSGigE::doTxDmaRead(), NSGigE::doTxDmaWrite(), IGbE::ethRxPkt(), IGbE::ethTxDone(), IGbE::RxDescCache::fetchAfterWb(), IGbE::TxDescCache::fetchAfterWb(), CopyEngine::CopyEngineChannel::inDrain(), init_drain(), Sequencer::insertRequest(), DRAMCtrl::processNextReqEvent(), DRAMCtrl::processRespondEvent(), TrafficGen::recvReqRetry(), BaseXBar::Layer< SrcType, DstType >::releaseLayer(), IGbE::restartClock(), DmaReadFifo::resumeFill(), Sinic::Device::rxKick(), PacketQueue::schedSendEvent(), System::setMemoryMode(), RubyPort::testDrainComplete(), Sinic::Device::txKick(), IGbE::txStateMachine(), Sequencer::wakeup(), and IGbE::write().

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().

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 _drainManager, _drainState, Drained, Draining, Resuming, Running, and DrainManager::signalDrainDone().

Referenced by FlashDevice::checkDrain(), UFSHostDevice::checkDrain(), IGbE::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(), BaseXBar::Layer< SrcType, DstType >::releaseLayer(), PacketQueue::schedSendEvent(), DRAMSim2::sendResponse(), MinorCPU::signalDrainDone(), RubyPort::testDrainComplete(), and DRAMSim2::writeComplete().