The Drain API.

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

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

Functions
bool	gem5::DrainManager::tryDrain ()
	Try to drain the system. More...
void	gem5::DrainManager::resume ()
	Resume normal simulation in a Drained system. More...
void	gem5::DrainManager::preCheckpointRestore ()
	Run state fixups before a checkpoint restore operation. More...
bool	gem5::DrainManager::isDrained () const
	Check if the system is drained. More...
DrainState	gem5::DrainManager::state () const
	Get the simulators global drain state. More...
void	gem5::DrainManager::signalDrainDone ()
	Notify the DrainManager that a Drainable object has finished draining. More...
virtual DrainState	gem5::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	gem5::Drainable::drainResume ()
	Resume execution after a successful drain. More...
void	gem5::Drainable::signalDrainDone () const
	Signal that an object is drained. More...
DrainState	gem5::Drainable::drainState () const
	Return the current drain state of an object. More...
virtual void	gem5::Drainable::notifyFork ()
	Notify a child process of a fork. More...

Detailed Description

These methods relate to the "Drainable" interface.

Enumeration Type Documentation

DrainState

enum gem5::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 74 of file drain.hh.

Function Documentation

drain()

virtual DrainState gem5::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 gem5::SimObject, gem5::Process, gem5::BaseXBar::Layer< SrcType, DstType >, gem5::BaseXBar::Layer< ResponsePort, RequestPort >, gem5::BaseXBar::Layer< RequestPort, ResponsePort >, gem5::memory::SimpleMemory, gem5::ruby::RubyPort, gem5::memory::qos::MemSinkCtrl, gem5::PacketQueue, gem5::memory::MemCtrl, gem5::memory::HeteroMemCtrl, gem5::memory::DRAMsim3, gem5::memory::DRAMSim2, gem5::memory::CfiMemory, gem5::Queue< Entry >, gem5::Queue< MSHR >, gem5::Queue< WriteQueueEntry >, gem5::BasePixelPump::PixelEvent, gem5::CopyEngine::CopyEngineChannel, gem5::IGbE, gem5::DistIface, gem5::DmaReadFifo, gem5::DmaCallback, gem5::DmaPort, gem5::UFSHostDevice, gem5::SMMUv3DeviceInterface, gem5::SMMUv3, gem5::Gicv3Its, gem5::GicV2, gem5::ArchTimer, gem5::FlashDevice, gem5::BaseTrafficGen, gem5::TimingSimpleCPU, gem5::AtomicSimpleCPU, gem5::o3::CPU, gem5::MinorCPU, gem5::BaseKvmCPU, and gem5::ArmISA::TableWalker.

Referenced by gem5::Drainable::dmDrain().

drainResume()

virtual void gem5::Drainable::drainResume ( )

inlineprotectedvirtual

Resume execution after a successful drain.

Reimplemented in gem5::ruby::RubySystem, gem5::memory::MemCtrl, gem5::memory::HeteroMemCtrl, gem5::memory::HBMCtrl, gem5::BasePixelPump::PixelEvent, gem5::CopyEngine::CopyEngineChannel, gem5::sinic::Device, gem5::NSGigE, gem5::IGbE, gem5::DistIface, gem5::HDLcd, gem5::GicV2, gem5::ArchTimer, gem5::TimingSimpleCPU, gem5::AtomicSimpleCPU, gem5::o3::CPU, gem5::MinorCPU, gem5::BaseKvmCPU, gem5::ArmISA::TableWalker, gem5::ArmISA::PMU, and gem5::ArmISA::MMU.

Definition at line 293 of file drain.hh.

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

drainState()

DrainState gem5::Drainable::drainState ( ) const

inline

Return the current drain state of an object.

Definition at line 324 of file drain.hh.

References gem5::Drainable::_drainState.

Referenced by gem5::o3::CPU::activateContext(), gem5::FlashDevice::checkDrain(), gem5::UFSHostDevice::checkDrain(), gem5::IGbE::checkDrain(), gem5::ArmISA::TableWalker::completeDrain(), gem5::Queue< Entry >::deallocate(), gem5::memory::CfiMemory::dequeue(), gem5::memory::SimpleMemory::dequeue(), gem5::IdeDisk::doDmaRead(), gem5::IdeDisk::doDmaTransfer(), gem5::IdeDisk::doDmaWrite(), gem5::NSGigE::doRxDmaRead(), gem5::NSGigE::doRxDmaWrite(), gem5::NSGigE::doTxDmaRead(), gem5::NSGigE::doTxDmaWrite(), gem5::IGbE::ethRxPkt(), gem5::IGbE::ethTxDone(), gem5::IGbE::RxDescCache::fetchAfterWb(), gem5::IGbE::TxDescCache::fetchAfterWb(), gem5::CopyEngine::CopyEngineChannel::inDrain(), gem5::init_drain(), gem5::ruby::Sequencer::insertRequest(), gem5::o3::CPU::isDraining(), gem5::memory::MemCtrl::processNextReqEvent(), gem5::memory::MemCtrl::processRespondEvent(), gem5::BaseXBar::Layer< SrcType, DstType >::releaseLayer(), gem5::IGbE::restartClock(), gem5::DmaReadFifo::resumeFill(), gem5::BaseTrafficGen::retryReq(), gem5::sinic::Device::rxKick(), gem5::PacketQueue::schedSendEvent(), gem5::System::setMemoryMode(), gem5::ruby::RubyPort::testDrainComplete(), gem5::BaseKvmCPU::tick(), gem5::o3::CPU::tick(), gem5::AtomicSimpleCPU::tryCompleteDrain(), gem5::TimingSimpleCPU::tryCompleteDrain(), gem5::BaseKvmCPU::tryDrain(), gem5::o3::CPU::tryDrain(), gem5::sinic::Device::txKick(), gem5::IGbE::txStateMachine(), gem5::ruby::Sequencer::wakeup(), and gem5::IGbE::write().

isDrained()

bool gem5::DrainManager::isDrained ( ) const

inline

Check if the system is drained.

Definition at line 145 of file drain.hh.

References gem5::DrainManager::_state, and gem5::Drained.

Referenced by gem5::init_drain().

notifyFork()

virtual void gem5::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 gem5::CowDiskImage, gem5::RawDiskImage, gem5::BaseKvmCPU, and gem5::KvmVM.

Definition at line 344 of file drain.hh.

Referenced by gem5::init_drain().

preCheckpointRestore()

void gem5::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 135 of file drain.cc.

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

Referenced by gem5::init_drain().

resume()

void gem5::DrainManager::resume

(

)

Resume normal simulation in a Drained system.

Definition at line 96 of file drain.cc.

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

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

signalDrainDone() [1/2]

void gem5::DrainManager::signalDrainDone

(

)

Notify the DrainManager that a Drainable object has finished draining.

Definition at line 149 of file drain.cc.

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

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

signalDrainDone() [2/2]

void gem5::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 305 of file drain.hh.

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

Referenced by gem5::FlashDevice::checkDrain(), gem5::UFSHostDevice::checkDrain(), gem5::IGbE::checkDrain(), gem5::DmaCallback::chunkComplete(), gem5::ArmISA::TableWalker::completeDrain(), gem5::Queue< Entry >::deallocate(), gem5::memory::CfiMemory::dequeue(), gem5::memory::SimpleMemory::dequeue(), gem5::DmaReadFifo::handlePending(), gem5::DmaPort::handleResp(), gem5::CopyEngine::CopyEngineChannel::inDrain(), gem5::SMMUCommandExecProcess::main(), gem5::GicV2::postDelayedFiq(), gem5::GicV2::postDelayedInt(), gem5::memory::MemCtrl::processNextReqEvent(), gem5::memory::MemCtrl::processRespondEvent(), gem5::BaseXBar::Layer< SrcType, DstType >::releaseLayer(), gem5::BaseTrafficGen::retryReq(), gem5::PacketQueue::schedSendEvent(), gem5::memory::DRAMSim2::sendResponse(), gem5::memory::DRAMsim3::sendResponse(), gem5::MinorCPU::signalDrainDone(), gem5::ruby::RubyPort::testDrainComplete(), gem5::AtomicSimpleCPU::tryCompleteDrain(), gem5::TimingSimpleCPU::tryCompleteDrain(), gem5::BaseKvmCPU::tryDrain(), gem5::o3::CPU::tryDrain(), gem5::memory::DRAMsim3::writeComplete(), gem5::memory::DRAMSim2::writeComplete(), and gem5::SMMUTranslationProcess::~SMMUTranslationProcess().

state()

DrainState gem5::DrainManager::state ( ) const

inline

Get the simulators global drain state.

Definition at line 152 of file drain.hh.

References gem5::DrainManager::_state.

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

tryDrain()

bool gem5::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 64 of file drain.cc.

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

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