From 2a7c1decf17169b2b5aeaf1d528fb27737cf2f44 Mon Sep 17 00:00:00 2001
From: "Bobby R. Bruce" <bbruce@ucdavis.edu>
Date: Mon, 20 Apr 2020 16:58:34 -0700
Subject: [PATCH] misc: Tagged API methods in sim/drain.hh

Change-Id: Id584d0be027048064d5f650ae0f2ea5a7f075a47
Issue-on: https://gem5.atlassian.net/browse/GEM5-172
Reviewed-on: https://gem5-review.googlesource.com/c/public/gem5/+/27988
Reviewed-by: Bobby R. Bruce <bbruce@ucdavis.edu>
Maintainer: Bobby R. Bruce <bbruce@ucdavis.edu>
Tested-by: kokoro <noreply+kokoro@google.com>
---
 src/doxygen/group_definitions.hh |  5 +++++
 src/sim/drain.hh                 | 36 +++++++++++++++++++++++++++++---
 2 files changed, 38 insertions(+), 3 deletions(-)
 create mode 100644 src/doxygen/group_definitions.hh

diff --git a/src/doxygen/group_definitions.hh b/src/doxygen/group_definitions.hh
new file mode 100644
index 000000000..8b3e14cd5
--- /dev/null
+++ b/src/doxygen/group_definitions.hh
@@ -0,0 +1,5 @@
+/**
+ * @defgroup api_drain The Drain API.
+ *
+ * These methods relate to the "Drainable" interface.
+ */
diff --git a/src/sim/drain.hh b/src/sim/drain.hh
index a775c068e..0d7492371 100644
--- a/src/sim/drain.hh
+++ b/src/sim/drain.hh
@@ -65,6 +65,8 @@ class Drainable;
  * 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.
+ *
+ * @ingroup api_drain
  */
 enum class DrainState {
     Running,  /** Running normally */
@@ -113,11 +115,15 @@ class DrainManager
      *
      * @return true if all objects were drained successfully, false if
      * more simulation is needed.
+     *
+     * @ingroup api_drain
      */
     bool tryDrain();
 
     /**
      * Resume normal simulation in a Drained system.
+     *
+     * @ingroup api_drain
      */
     void resume();
 
@@ -131,18 +137,30 @@ class DrainManager
      * state since the state isn't stored in checkpoints. This method
      * performs state fixups on all Drainable objects and the
      * DrainManager itself.
+     *
+     * @ingroup api_drain
      */
     void preCheckpointRestore();
 
-    /** Check if the system is drained */
+    /**
+     * Check if the system is drained
+     *
+     * @ingroup api_drain
+     */
     bool isDrained() const { return _state == DrainState::Drained; }
 
-    /** Get the simulators global drain state */
+    /**
+     * Get the simulators global drain state
+     *
+     * @ingroup api_drain
+     */
     DrainState state() const { return _state; }
 
     /**
      * Notify the DrainManager that a Drainable object has finished
      * draining.
+     *
+     * @ingroup api_drain
      */
     void signalDrainDone();
 
@@ -246,11 +264,15 @@ class Drainable
      * @return DrainState::Drained if the object is drained at this
      * point in time, DrainState::Draining if it needs further
      * simulation.
+     *
+     * @ingroup api_drain
      */
     virtual DrainState drain() = 0;
 
     /**
      * Resume execution after a successful drain.
+     *
+     * @ingroup api_drain
      */
     virtual void drainResume() {};
 
@@ -261,6 +283,8 @@ class Drainable
      * into a state where it is ready to be drained. The method is
      * safe to call multiple times and there is no need to check that
      * draining has been requested before calling this method.
+     *
+     * @ingroup api_drain
      */
     void signalDrainDone() const {
         switch (_drainState) {
@@ -276,7 +300,11 @@ class Drainable
     }
 
   public:
-    /** Return the current drain state of an object. */
+    /**
+     * Return the current drain state of an object.
+     *
+     * @ingroup api_drain
+     */
     DrainState drainState() const { return _drainState; }
 
     /**
@@ -290,6 +318,8 @@ class Drainable
      *
      * This method is only called in the child of the fork. The call
      * takes place in a drained system.
+     *
+     * @ingroup api_drain
      */
     virtual void notifyFork() {};
 
-- 
2.30.2