diff --git a/src/sim/drain.hh b/src/sim/drain.hh index 0d74923713..9c246086aa 100644 --- a/src/sim/drain.hh +++ b/src/sim/drain.hh @@ -69,28 +69,12 @@ class Drainable; * @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: @@ -128,7 +112,14 @@ class DrainManager 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 @@ -238,6 +229,22 @@ class DrainManager */ 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: @@ -245,7 +252,12 @@ class Drainable 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 @@ -308,7 +320,11 @@ class Drainable 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 diff --git a/src/sim/eventq.hh b/src/sim/eventq.hh index ddba8bd23d..aa54722031 100644 --- a/src/sim/eventq.hh +++ b/src/sim/eventq.hh @@ -488,6 +488,9 @@ class Event : public EventBase, public Serializable 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(); } @@ -659,22 +662,21 @@ class EventQueue 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) @@ -703,19 +705,19 @@ class EventQueue 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) @@ -840,6 +842,8 @@ class EventQueue * 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 */ @@ -974,6 +978,9 @@ class EventManager public: /** + * Event manger manages events in the event queue. Where + * you can schedule and deschedule different events. + * * @ingroup api_eventq * @{ */ @@ -1046,6 +1053,9 @@ class EventManager } /** + * 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) @@ -1096,6 +1106,9 @@ class EventFunctionWrapper : public Event public: /** + * This function wraps a function into an event, to be + * executed later. + * * @ingroup api_eventq */ EventFunctionWrapper(const std::function &callback, diff --git a/src/sim/serialize.cc b/src/sim/serialize.cc index 4bb2ab5ff2..5aa933d2e3 100644 --- a/src/sim/serialize.cc +++ b/src/sim/serialize.cc @@ -278,19 +278,45 @@ CheckpointIn::~CheckpointIn() { 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) diff --git a/src/sim/serialize.hh b/src/sim/serialize.hh index 1f31dd2033..bbc91d7b5d 100644 --- a/src/sim/serialize.hh +++ b/src/sim/serialize.hh @@ -79,6 +79,8 @@ class CheckpointIn ~CheckpointIn(); /** + * @return Returns the current directory being used for creating + * checkpoints or restoring checkpoints. * @ingroup api_serialize * @{ */ @@ -136,6 +138,10 @@ class CheckpointIn /** * 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 @@ -166,26 +172,27 @@ class CheckpointIn 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 * @{ */ @@ -297,6 +304,8 @@ class Serializable static const std::string ¤tSection(); /** + * Serializes all the SimObjects. + * * @ingroup api_serialize */ static void serializeAll(const std::string &cpt_dir); @@ -447,6 +456,10 @@ parseParam(const std::string &s, std::string &value) } /** + * 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 @@ -459,6 +472,10 @@ paramOut(CheckpointOut &os, const std::string &name, const T ¶m) } /** + * 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 @@ -473,6 +490,16 @@ paramIn(CheckpointIn &cp, const std::string &name, T ¶m) } /** + * 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 diff --git a/src/sim/sim_object.hh b/src/sim/sim_object.hh index 27f675c64a..2b94ca4cf7 100644 --- a/src/sim/sim_object.hh +++ b/src/sim/sim_object.hh @@ -112,12 +112,17 @@ class SimObject : public EventManager, public Serializable, public Drainable, 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: @@ -178,6 +183,11 @@ class SimObject : public EventManager, public Serializable, public Drainable, /** * 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(); @@ -186,6 +196,18 @@ class SimObject : public EventManager, public Serializable, public Drainable, * 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 *