* @ingroup api_drain
*/
enum class DrainState {
- Running, /** Running normally */
- Draining, /** Draining buffers pending serialization/handover */
- Drained, /** Buffers drained, ready for serialization/handover */
- Resuming, /** Transient state while the simulator is resuming */
+ Running, /**< Running normally */
+ Draining, /**< Draining buffers pending serialization/handover */
+ Drained, /**< Buffers drained, ready for serialization/handover */
+ Resuming, /**< Transient state while the simulator is resuming */
};
-/**
- * This class coordinates draining of a System.
- *
- * When draining the simulator, we need to make sure that all
- * Drainable objects within the system have ended up in the drained
- * state before declaring the operation to be successful. This class
- * keeps track of how many objects are still in the process of
- * draining. Once it determines that all objects have drained their
- * state, it exits the simulation loop.
- *
- * @note A System might not be completely drained even though the
- * DrainManager has caused the simulation loop to exit. Draining needs
- * to be restarted until all Drainable objects declare that they don't
- * need further simulation to be completely drained. See Drainable for
- * more information.
- */
class DrainManager
{
private:
void resume();
/**
- * Run state fixups before a checkpoint restore operation
+ * 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
*/
class Drainable
{
+ /**
+ * This class coordinates draining of a System.
+ *
+ * When draining the simulator, we need to make sure that all
+ * Drainable objects within the system have ended up in the drained
+ * state before declaring the operation to be successful. This class
+ * keeps track of how many objects are still in the process of
+ * draining. Once it determines that all objects have drained their
+ * state, it exits the simulation loop.
+ *
+ * @note A System might not be completely drained even though the
+ * DrainManager has caused the simulation loop to exit. Draining needs
+ * to be restarted until all Drainable objects declare that they don't
+ * need further simulation to be completely drained. See Drainable for
+ * more information.
+ */
friend class DrainManager;
protected:
virtual ~Drainable();
/**
- * Notify an object that it needs to drain its state.
+ * 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
DrainState drainState() const { return _drainState; }
/**
- * Notify a child process of a fork.
+ * 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
bool isManaged() const { return flags.isSet(Managed); }
/**
+ * The function returns true if the object is automatically
+ * deleted after the event is processed.
+ *
* @ingroup api_eventq
*/
bool isAutoDelete() const { return isManaged(); }
EventQueue(const EventQueue &);
public:
- /**
- * Temporarily migrate execution to a different event queue.
- *
- * An instance of this class temporarily migrates execution to a
- * different event queue by releasing the current queue, locking
- * the new queue, and updating curEventQueue(). This can, for
- * example, be useful when performing IO across thread event
- * queues when timing is not crucial (e.g., during fast
- * forwarding).
- *
- * ScopedMigration does nothing if both eqs are the same
- */
class ScopedMigration
{
public:
- /**
+ /**
+ * Temporarily migrate execution to a different event queue.
+ *
+ * An instance of this class temporarily migrates execution to
+ * different event queue by releasing the current queue, locking
+ * the new queue, and updating curEventQueue(). This can, for
+ * example, be useful when performing IO across thread event
+ * queues when timing is not crucial (e.g., during fast
+ * forwarding).
+ *
+ * ScopedMigration does nothing if both eqs are the same
+ *
* @ingroup api_eventq
*/
ScopedMigration(EventQueue *_new_eq, bool _doMigrate = true)
bool doMigrate;
};
- /**
- * Temporarily release the event queue service lock.
- *
- * There are cases where it is desirable to temporarily release
- * the event queue lock to prevent deadlocks. For example, when
- * waiting on the global barrier, we need to release the lock to
- * prevent deadlocks from happening when another thread tries to
- * temporarily take over the event queue waiting on the barrier.
- */
+
class ScopedRelease
{
public:
/**
+ * Temporarily release the event queue service lock.
+ *
+ * There are cases where it is desirable to temporarily release
+ * the event queue lock to prevent deadlocks. For example, when
+ * waiting on the global barrier, we need to release the lock to
+ * prevent deadlocks from happening when another thread tries to
+ * temporarily take over the event queue waiting on the barrier.
+ *
* @group api_eventq
*/
ScopedRelease(EventQueue *_eq)
* object) need to access the current tick of this event queue, this
* function is used.
*
+ * Tick is the unit of time used in gem5.
+ *
* @return Tick The current tick of this event queue.
* @ingroup api_eventq
*/
public:
/**
+ * Event manger manages events in the event queue. Where
+ * you can schedule and deschedule different events.
+ *
* @ingroup api_eventq
* @{
*/
}
/**
+ * This function is not needed by the usual gem5 event loop
+ * but may be necessary in derived EventQueues which host gem5
+ * on other schedulers.
* @ingroup api_eventq
*/
void wakeupEventQueue(Tick when = (Tick)-1)
public:
/**
+ * This function wraps a function into an event, to be
+ * executed later.
+ *
* @ingroup api_eventq
*/
EventFunctionWrapper(const std::function<void(void)> &callback,
{
delete db;
}
-
+/**
+ * @param section Here we mention the section we are looking for
+ * (example: currentsection).
+ * @param entry Mention the entry we are looking for (example: interrupt
+ * time) in the section.
+ *
+ * @return Returns true if the entry exists in the named section
+ * we are looking in.
+ */
bool
CheckpointIn::entryExists(const string §ion, const string &entry)
{
return db->entryExists(section, entry);
}
-
+/**
+ * @param section Here we mention the section we are looking for
+ * (example: currentsection).
+ * @param entry Mention the entry we are looking for (example: Cache
+ * line size etc) in the section.
+ * @param value Give the value at the said entry.
+ *
+ * @return Returns true if the searched parameter exists with
+ * the value, given the section .
+ */
bool
CheckpointIn::find(const string §ion, const string &entry, string &value)
{
return db->find(section, entry, value);
}
-
+/**
+ * @param section Here we mention the section we are looking for
+ * (example: currentsection).
+ * @param entry Mention the SimObject we are looking for (example:
+ * interruput time) in the section.
+ * @param value Give the value at the said entry.
+ *
+ * @return Returns true if a SimObject exists in the section.
+ *
+ */
bool
CheckpointIn::findObj(const string §ion, const string &entry,
SimObject *&value)
~CheckpointIn();
/**
+ * @return Returns the current directory being used for creating
+ * checkpoints or restoring checkpoints.
* @ingroup api_serialize
* @{
*/
/**
* Basic support for object serialization.
*
+ * The Serailizable interface is used to create checkpoints. Any
+ * object that implements this interface can be included in
+ * gem5's checkpointing system.
+ *
* Objects that support serialization should derive from this
* class. Such objects can largely be divided into two categories: 1)
* True SimObjects (deriving from SimObject), and 2) child objects
class Serializable
{
protected:
- /**
- * Scoped checkpoint section helper class
- *
- * This helper class creates a section within a checkpoint without
- * the need for a separate serializeable object. It is mainly used
- * within the Serializable class when serializing or unserializing
- * section (see serializeSection() and unserializeSection()). It
- * can also be used to maintain backwards compatibility in
- * existing code that serializes structs that are not inheriting
- * from Serializable into subsections.
- *
- * When the class is instantiated, it appends a name to the active
- * path in a checkpoint. The old path is later restored when the
- * instance is destroyed. For example, serializeSection() could be
- * implemented by instantiating a ScopedCheckpointSection and then
- * calling serialize() on an object.
- */
class ScopedCheckpointSection {
public:
/**
+ * This is the constructor for Scoped checkpoint section helper
+ * class.
+ *
+ * Scoped checkpoint helper class creates a section within a
+ * checkpoint without the need for a separate serializeable
+ * object. It is mainly used within the Serializable class
+ * when serializing or unserializing section (see
+ * serializeSection() and unserializeSection()). It
+ * can also be used to maintain backwards compatibility in
+ * existing code that serializes structs that are not inheriting
+ * from Serializable into subsections.
+ *
+ * When the class is instantiated, it appends a name to the active
+ * path in a checkpoint. The old path is later restored when the
+ * instance is destroyed. For example, serializeSection() could be
+ * implemented by instantiating a ScopedCheckpointSection and then
+ * calling serialize() on an object.
+ *
* @ingroup api_serialize
* @{
*/
static const std::string ¤tSection();
/**
+ * Serializes all the SimObjects.
+ *
* @ingroup api_serialize
*/
static void serializeAll(const std::string &cpt_dir);
}
/**
+ * This function is used for writing parameters to a checkpoint.
+ * @param os The checkpoint to be written to.
+ * @param name Name of the parameter to be set.
+ * @param param Value of the parameter to be written.
* @ingroup api_serialize
*/
template <class T>
}
/**
+ * This function is used for restoring parameters from a checkpoint.
+ * @param os The checkpoint to be restored from.
+ * @param name Name of the parameter to be set.
+ * @param param Value of the parameter to be restored.
* @ingroup api_serialize
*/
template <class T>
}
/**
+ * This function is used for restoring optional parameters from the
+ * checkpoint.
+ * @param cp The checkpoint to be written to.
+ * @param name Name of the parameter to be written.
+ * @param param Value of the parameter to be written.
+ * @param warn If the warn is set to true then the function prints the warning
+ * message.
+ * @return If the parameter we are searching for does not exist
+ * the function returns false else it returns true.
+ *
* @ingroup api_serialize
*/
template <class T>
public:
typedef SimObjectParams Params;
/**
+ * @return This function returns the cached copy of the object parameters.
+ *
* @ingroup api_simobject
- * @{
*/
const Params *params() const { return _params; }
+
+ /**
+ * @ingroup api_simobject
+ */
SimObject(const Params *_params);
- /** @}*/ //end of the api_simobject group
+
virtual ~SimObject();
public:
/**
* Get the probe manager for this object.
*
+ * Probes generate traces. A trace is a file that
+ * keeps a log of events. For example, we can have a probe
+ * listener for an address and the trace will be a file that
+ * has time stamps for all the reads and writes to that address.
+ *
* @ingroup api_simobject
*/
ProbeManager *getProbeManager();
* Get a port with a given name and index. This is used at binding time
* and returns a reference to a protocol-agnostic port.
*
+ * gem5 has a request and response port interface. All memory objects
+ * are connected together via ports. These ports provide a rigid
+ * interface between these memory objects. These ports implement
+ * three different memory system modes: timing, atomic, and
+ * functional. The most important mode is the timing mode and here
+ * timing mode is used for conducting cycle-level timing
+ * experiments. The other modes are only used in special
+ * circumstances and should *not* be used to conduct cycle-level
+ * timing experiments. The other modes are only used in special
+ * circumstances. These ports allow SimObjects to communicate with
+ * each other.
+ *
* @param if_name Port name
* @param idx Index in the case of a VectorPort
*
projects / gem5.git / commitdiff