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 <yazakram@ucdavis.edu>
Reviewed-by: Bobby R. Bruce <bbruce@ucdavis.edu>
Maintainer: Jason Lowe-Power <power.jg@gmail.com>
Tested-by: kokoro <noreply+kokoro@google.com>

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