The Drain API.

These methods relate to the "Drainable" interface. More...

Enumerations
enum	DrainState { DrainState::Running, DrainState::Draining, DrainState::Drained, DrainState::Resuming }
	Object drain/handover states. More...

Functions
bool	DrainManager::tryDrain ()
	Try to drain the system. More...
void	DrainManager::resume ()
	Resume normal simulation in a Drained system. More...
void	DrainManager::preCheckpointRestore ()
	Run state fixups before a checkpoint restore operation. More...
bool	DrainManager::isDrained () const
	Check if the system is drained. More...
DrainState	DrainManager::state () const
	Get the simulators global drain state. More...
void	DrainManager::signalDrainDone ()
	Notify the DrainManager that a Drainable object has finished draining. More...
virtual DrainState	Drainable::drain ()=0
	Draining is the process of clearing out the states of SimObjects.These are the SimObjects that are partially executed or are partially in flight. More...
virtual void	Drainable::drainResume ()
	Resume execution after a successful drain. More...
void	Drainable::signalDrainDone () const
	Signal that an object is drained. More...
DrainState	Drainable::drainState () const
	Return the current drain state of an object. More...
virtual void	Drainable::notifyFork ()
	Notify a child process of a fork. More...

Detailed Description

These methods relate to the "Drainable" interface.

Enumeration Type Documentation

DrainState

enum DrainState

strong

Object drain/handover states.

An object starts out in the Running state. When the simulator prepares to take a snapshot or prepares a CPU for handover, it calls the drain() method to transfer the object into the Draining or Drained state. If any object enters the Draining state (Drainable::drain() returning >0), simulation continues until it all objects have entered the Drained state.

Before resuming simulation, the simulator calls resume() to transfer the object to the Running state. This in turn results in a call to drainResume() for all Drainable objects in the simulator. New Drainable objects may be created while resuming. In such cases, the new objects will be created in the Resuming state and later resumed.

Note

Even though the state of an object (visible to the rest of the world through Drainable::getState()) could be used to determine if all objects have entered the Drained state, the protocol is actually a bit more elaborate. See Drainable::drain() for details.

Enumerator
Running	Running normally.
Draining	Draining buffers pending serialization/handover.
Drained	Buffers drained, ready for serialization/handover.
Resuming	Transient state while the simulator is resuming.

Definition at line 71 of file drain.hh.

Function Documentation

drain()

virtual DrainState Drainable::drain ( )

protectedpure virtual

Draining is the process of clearing out the states of SimObjects.These are the SimObjects that are partially executed or are partially in flight.

Draining is mostly used before forking and creating a check point.

This function notifies 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 ArmISA::TableWalker, MemCtrl, DistIface, IGbE, GicV2, DmaReadFifo, BasePixelPump::PixelEvent, Queue< Entry >, Queue< MSHR >, Queue< WriteQueueEntry >, BaseTrafficGen, ArchTimer, SimObject, DmaCallback, PacketQueue, DRAMsim3, DRAMSim2, SMMUv3, SimpleMemory, MuxingKvmGic, UFSHostDevice, RubyPort, DmaPort, Gicv3Its, SMMUv3DeviceInterface, QoS::MemSinkCtrl, BaseXBar::Layer< SrcType, DstType >, BaseXBar::Layer< ResponsePort, RequestPort >, BaseXBar::Layer< RequestPort, ResponsePort >, CopyEngine::CopyEngineChannel, Process, and FlashDevice.

Referenced by Drainable::dmDrain().

drainResume()

virtual void Drainable::drainResume ( )

inlineprotectedvirtual

Resume execution after a successful drain.

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

Definition at line 289 of file drain.hh.

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

drainState()

DrainState Drainable::drainState ( ) const

inline

Return the current drain state of an object.

Definition at line 320 of file drain.hh.

References Drainable::_drainState.

Referenced by FlashDevice::checkDrain(), IGbE::checkDrain(), UFSHostDevice::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(), MemCtrl::processNextReqEvent(), MemCtrl::processRespondEvent(), IGbE::restartClock(), DmaReadFifo::resumeFill(), BaseTrafficGen::retryReq(), Sinic::Device::rxKick(), PacketQueue::schedSendEvent(), System::setMemoryMode(), RubyPort::testDrainComplete(), Sinic::Device::txKick(), IGbE::txStateMachine(), Sequencer::wakeup(), and IGbE::write().

isDrained()

bool DrainManager::isDrained ( ) const

inline

Check if the system is drained.

Definition at line 141 of file drain.hh.

References DrainManager::_state, and Drained.

Referenced by init_drain().

notifyFork()

virtual void Drainable::notifyFork ( )

inlinevirtual

Notify a child process of a fork.

SimObjects are told that the process is going to be forked.

Forking is a process of splitting a process in to two processes, which is then used for multiprocessing.

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 CowDiskImage, RawDiskImage, and KvmVM.

Definition at line 340 of file drain.hh.

Referenced by init_drain().

preCheckpointRestore()

void DrainManager::preCheckpointRestore

(

)

Run state fixups before a checkpoint restore operation.

This is called before restoring the checkpoint and to make sure that everything has been set to drained.

When restoring from a checkpoint, this function should be called first before calling the resume() function. And also before calling loadstate() on any object.

The drain state of an object isn't stored in a checkpoint since the whole system is always going to be in the Drained state when the checkpoint is created. When the checkpoint is restored at a later stage, recreated objects will be in the Running state since the state isn't stored in checkpoints. This method performs state fixups on all Drainable objects and the DrainManager itself.

Definition at line 132 of file drain.cc.

References DrainManager::_allDrainable, DrainManager::_state, DPRINTF, DrainManager::drainableCount(), Drained, panic_if, and Running.

Referenced by init_drain().

resume()

void DrainManager::resume

(

)

Resume normal simulation in a Drained system.

Definition at line 93 of file drain.cc.

References DrainManager::_allDrainable, DrainManager::_count, DrainManager::_state, DrainManager::allInState(), DPRINTF, DrainManager::drainableCount(), Drained, Draining, panic_if, Resuming, Running, and warn_if.

Referenced by CxxConfigManager::drainResume(), and init_drain().

signalDrainDone() [1/2]

void DrainManager::signalDrainDone

(

)

Notify the DrainManager that a Drainable object has finished draining.

Definition at line 146 of file drain.cc.

References DrainManager::_count, DPRINTF, DrainManager::drainableCount(), and exitSimLoop().

Referenced by init_drain(), and Drainable::signalDrainDone().

signalDrainDone() [2/2]

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 301 of file drain.hh.

References Drainable::_drainManager, Drainable::_drainState, Drained, Draining, Resuming, Running, and DrainManager::signalDrainDone().

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(), SMMUCommandExecProcess::main(), GicV2::postDelayedFiq(), GicV2::postDelayedInt(), MemCtrl::processNextReqEvent(), MemCtrl::processRespondEvent(), BaseTrafficGen::retryReq(), PacketQueue::schedSendEvent(), DRAMSim2::sendResponse(), DRAMsim3::sendResponse(), MinorCPU::signalDrainDone(), RubyPort::testDrainComplete(), DRAMSim2::writeComplete(), DRAMsim3::writeComplete(), and SMMUTranslationProcess::~SMMUTranslationProcess().

state()

DrainState DrainManager::state ( ) const

inline

Get the simulators global drain state.

Definition at line 148 of file drain.hh.

References DrainManager::_state.

Referenced by DrainManager::allInState(), and init_drain().

tryDrain()

bool DrainManager::tryDrain

(

)

Try to drain the system.

Try to drain the system and return true if all objects are in a the Drained state at which point the whole simulator is in a consistent state and ready for checkpointing or CPU handover. The simulation script must continue simulating until the simulation loop returns "Finished drain", at which point this method should be called again. This cycle should continue until this method returns true.

Returns

true if all objects were drained successfully, false if more simulation is needed.

Definition at line 61 of file drain.cc.

References DrainManager::_allDrainable, DrainManager::_count, DrainManager::_state, DPRINTF, DrainManager::drainableCount(), Drained, Draining, DTRACE, SimObject::name(), panic_if, and ArmISA::status.

Referenced by CxxConfigManager::drain(), and init_drain().