From b2847f43c91e27f43bd4ac08abd528efcf00f2fd Mon Sep 17 00:00:00 2001 From: Muhammad Sarmad Saeed Date: Fri, 24 Jul 2020 22:08:27 +0000 Subject: [PATCH] misc: Update documentation of SimObject related APIs Updated documentation of Drain, Serialize, Evnet queue and Simobject APIs. Made some corrections to where the documentation was available in the code but did not appear in the documentation. Change-Id: I5254e87eb5663232e824bcd5592da0a04eba673b Reviewed-on: https://gem5-review.googlesource.com/c/public/gem5/+/31814 Reviewed-by: Ayaz Akram Reviewed-by: Bobby R. Bruce Maintainer: Jason Lowe-Power Tested-by: kokoro --- src/sim/drain.hh | 62 +++++++++++++++++++++++++++---------------- src/sim/eventq.hh | 57 ++++++++++++++++++++++++--------------- src/sim/serialize.cc | 32 +++++++++++++++++++--- src/sim/serialize.hh | 61 ++++++++++++++++++++++++++++++------------ src/sim/sim_object.hh | 26 ++++++++++++++++-- 5 files changed, 171 insertions(+), 67 deletions(-) diff --git a/src/sim/drain.hh b/src/sim/drain.hh index 0d7492371..9c246086a 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 ddba8bd23..aa5472203 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 4bb2ab5ff..5aa933d2e 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 1f31dd203..bbc91d7b5 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 27f675c64..2b94ca4cf 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 * -- 2.30.2