From 65dbb3c69aff5bca9c4df0dee2a6b01af3eae5d2 Mon Sep 17 00:00:00 2001
From: "Bobby R. Bruce" <bbruce@ucdavis.edu>
Date: Thu, 30 Apr 2020 12:29:56 -0700
Subject: [PATCH] misc,sim: Tagged API methods in sim/simobject.hh

Change-Id: I1d4f5b67828e3bef64d781831cec4b25d6fcb6b9
Issue-on: https://gem5.atlassian.net/browse/GEM5-172
Reviewed-on: https://gem5-review.googlesource.com/c/public/gem5/+/28407
Tested-by: kokoro <noreply+kokoro@google.com>
Reviewed-by: Bobby R. Bruce <bbruce@ucdavis.edu>
Maintainer: Bobby R. Bruce <bbruce@ucdavis.edu>
---
 src/doxygen/group_definitions.hh |  6 +++++
 src/sim/sim_object.hh            | 42 ++++++++++++++++++++++++++++++--
 2 files changed, 46 insertions(+), 2 deletions(-)

diff --git a/src/doxygen/group_definitions.hh b/src/doxygen/group_definitions.hh
index e6e39b7cc..40069e0ac 100644
--- a/src/doxygen/group_definitions.hh
+++ b/src/doxygen/group_definitions.hh
@@ -21,3 +21,9 @@
  *
  * These methods relate to the statistics I/O interface.
  */
+
+/**
+ * @defgroup api_simobject The SimObject API.
+ *
+ * These methods relate to the SimObject interface.
+ */
diff --git a/src/sim/sim_object.hh b/src/sim/sim_object.hh
index 05c1b3e0a..de89fbff2 100644
--- a/src/sim/sim_object.hh
+++ b/src/sim/sim_object.hh
@@ -103,17 +103,29 @@ class SimObject : public EventManager, public Serializable, public Drainable,
     ProbeManager *probeManager;
 
   protected:
-    /** Cached copy of the object parameters. */
+    /**
+     * Cached copy of the object parameters.
+     *
+     * @ingroup api_simobject
+     */
     const SimObjectParams *_params;
 
   public:
     typedef SimObjectParams Params;
+    /**
+     * @ingroup api_simobject
+     * @{
+     */
     const Params *params() const { return _params; }
     SimObject(const Params *_params);
+    /** @}*/ //end of the api_simobject group
     virtual ~SimObject();
 
   public:
 
+    /**
+     * @ingroup api_simobject
+     */
     virtual const std::string name() const { return params()->name; }
 
     /**
@@ -121,6 +133,8 @@ class SimObject : public EventManager, public Serializable, public Drainable,
      * all ports are connected.  Initializations that are independent
      * of unserialization but rely on a fully instantiated and
      * connected SimObject graph should be done here.
+     *
+     * @ingroup api_simobject
      */
     virtual void init();
 
@@ -134,6 +148,8 @@ class SimObject : public EventManager, public Serializable, public Drainable,
      * found.
      *
      * @param cp Checkpoint to restore the state from.
+     *
+     * @ingroup api_serialize
      */
     virtual void loadState(CheckpointIn &cp);
 
@@ -141,21 +157,29 @@ class SimObject : public EventManager, public Serializable, public Drainable,
      * initState() is called on each SimObject when *not* restoring
      * from a checkpoint.  This provides a hook for state
      * initializations that are only required for a "cold start".
+     *
+     * @ingroup api_serialize
      */
     virtual void initState();
 
     /**
      * Register probe points for this object.
+     *
+     * @ingroup api_simobject
      */
     virtual void regProbePoints();
 
     /**
      * Register probe listeners for this object.
+     *
+     * @ingroup api_simobject
      */
     virtual void regProbeListeners();
 
     /**
      * Get the probe manager for this object.
+     *
+     * @ingroup api_simobject
      */
     ProbeManager *getProbeManager();
 
@@ -167,6 +191,8 @@ class SimObject : public EventManager, public Serializable, public Drainable,
      * @param idx Index in the case of a VectorPort
      *
      * @return A reference to the given port
+     *
+     * @ingroup api_simobject
      */
     virtual Port &getPort(const std::string &if_name,
                           PortID idx=InvalidPortID);
@@ -176,6 +202,8 @@ class SimObject : public EventManager, public Serializable, public Drainable,
      * All state is initialized (including unserialized state, if any,
      * such as the curTick() value), so this is the appropriate place to
      * schedule initial event(s) for objects that need them.
+     *
+     * @ingroup api_simobject
      */
     virtual void startup();
 
@@ -192,6 +220,8 @@ class SimObject : public EventManager, public Serializable, public Drainable,
      * written all its dirty data back to memory. This method is
      * typically used to prepare a system with caches for
      * checkpointing.
+     *
+     * @ingroup api_simobject
      */
     virtual void memWriteback() {};
 
@@ -205,6 +235,8 @@ class SimObject : public EventManager, public Serializable, public Drainable,
      *
      * @warn This does <i>not</i> cause any dirty state to be written
      * back to memory.
+     *
+     * @ingroup api_simobject
      */
     virtual void memInvalidate() {};
 
@@ -226,6 +258,8 @@ class SimObject : public EventManager, public Serializable, public Drainable,
      * Find the SimObject with the given name and return a pointer to
      * it.  Primarily used for interactive debugging.  Argument is
      * char* rather than std::string to make it callable from gdb.
+     *
+     * @ingroup api_simobject
      */
     static SimObject *find(const char *name);
 };
@@ -241,7 +275,11 @@ class SimObjectResolver
   public:
     virtual ~SimObjectResolver() { }
 
-    // Find a SimObject given a full path name
+    /**
+     * Find a SimObject given a full path name
+     *
+     * @ingroup api_serialize
+     */
     virtual SimObject *resolveSimObject(const std::string &name) = 0;
 };
 
-- 
2.30.2