gem5  v20.1.0.0
Enumerations | Functions
The Drain API.

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


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


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

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.

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.

Running normally.


Draining buffers pending serialization/handover.


Buffers drained, ready for serialization/handover.


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.

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

◆ drainState()

DrainState Drainable::drainState ( ) const

◆ isDrained()

bool DrainManager::isDrained ( ) const

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

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

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

Referenced by init_drain().

◆ resume()

void DrainManager::resume ( )

◆ signalDrainDone() [1/2]

void DrainManager::signalDrainDone ( )

Notify the DrainManager that a Drainable object has finished draining.

Definition at line 146 of file

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

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

◆ signalDrainDone() [2/2]

void Drainable::signalDrainDone ( ) const

◆ state()

DrainState DrainManager::state ( ) const

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.

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

Definition at line 61 of file

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

Generated on Wed Sep 30 2020 14:02:20 for gem5 by doxygen 1.8.17