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>
diff --git a/src/doxygen/group_definitions.hh b/src/doxygen/group_definitions.hh
new file mode 100644
index 0000000..8b3e14c
--- /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 a775c06..0d74923 100644
--- a/src/sim/drain.hh
+++ b/src/sim/drain.hh
@@ -65,6 +65,8 @@
* 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 @@
*
* @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 @@
* 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 @@
* @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 @@
* 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 @@
}
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 @@
*
* 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() {};