src/base/stats/group.hh

   1 /*
   2  * Copyright (c) 2019, 2020 Arm Limited
   3  * All rights reserved
   4  *
   5  * The license below extends only to copyright in the software and shall
   6  * not be construed as granting a license to any other intellectual
   7  * property including but not limited to intellectual property relating
   8  * to a hardware implementation of the functionality of the software
   9  * licensed hereunder.  You may use the software subject to the license
  10  * terms below provided that you ensure that this notice is replicated
  11  * unmodified and in its entirety in all distributions of the software,
  12  * modified or unmodified, in source code or in binary form.
  13  *
  14  * Redistribution and use in source and binary forms, with or without
  15  * modification, are permitted provided that the following conditions are
  16  * met: redistributions of source code must retain the above copyright
  17  * notice, this list of conditions and the following disclaimer;
  18  * redistributions in binary form must reproduce the above copyright
  19  * notice, this list of conditions and the following disclaimer in the
  20  * documentation and/or other materials provided with the distribution;
  21  * neither the name of the copyright holders nor the names of its
  22  * contributors may be used to endorse or promote products derived from
  23  * this software without specific prior written permission.
  24  *
  25  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  26  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  27  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  28  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  29  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  30  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  31  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  32  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  33  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  34  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  35  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  36  */
  37
  38 #ifndef __BASE_STATS_GROUP_HH__
  39 #define __BASE_STATS_GROUP_HH__
  40
  41 #include <map>
  42 #include <vector>
  43 #include <string>
  44
  45 /**
  46  * Convenience macro to add a stat to a statistics group.
  47  *
  48  * This macro is used to add a stat to a Stats::Group in the
  49  * initilization list in the Group's constructor. The macro
  50  * automatically assigns the stat to the current group and gives it
  51  * the same name as in the class. For example:
  52  *
  53  * \code
  54  * struct MyStats : public Stats::Group
  55  * {
  56  *     Stats::Scalar scalar0;
  57  *     Stats::Scalar scalar1;
  58  *
  59  *     Group()
  60  *         : ADD_STAT(scalar0, "Description of scalar0"),
  61  *           scalar1(this, "scalar1", "Description of scalar1")
  62  *     {
  63  *     }
  64  * };
  65  * \endcode
  66  */
  67 #define ADD_STAT(n, ...) n(this, # n, __VA_ARGS__)
  68
  69 namespace Stats {
  70
  71 class Info;
  72
  73 /**
  74  * Statistics container.
  75  *
  76  * A stat group is a hierarchical structure that contain statistics
  77  * and other groups. Groups are used by the stat system to reflect
  78  * gem5's SimObject hierarchy and to expose internal hierarchy within
  79  * an object. They can also be used to conveniently group stats into
  80  * their own class/struct and then be merged into the parent group
  81  * (typically a SimObject).
  82  */
  83 class Group
  84 {
  85   public:
  86     Group() = delete;
  87     Group(const Group &) = delete;
  88     Group &operator=(const Group &) = delete;
  89
  90     /**
  91      * Construct a new statistics group.
  92      *
  93      * The constructor takes two parameters, a parent and a name. The
  94      * parent group should typically be specified. However, there are
  95      * special cases where the parent group may be null. One such
  96      * special case is SimObjects where the Python code performs late
  97      * binding of the group parent.
  98      *
  99      * If the name parameter is NULL, the group gets merged into the
 100      * parent group instead of creating a sub-group. Stats belonging
 101      * to a merged group behave as if they have been added directly to
 102      * the parent group.
 103      *
 104      * @param parent Parent group to associate this object to.
 105      * @param name Name of this group, can be NULL to merge this group
 106      * with the parent group.
 107      */
 108     Group(Group *parent, const char *name = nullptr);
 109
 110     virtual ~Group();
 111
 112     /**
 113      * Callback to set stat parameters.
 114      *
 115      * This callback is typically used for complex stats (e.g.,
 116      * distributions) that need parameters in addition to a name and a
 117      * description. Stat names and descriptions should typically be
 118      * set from the constructor usingo from the constructor using the
 119      * ADD_STAT macro.
 120      */
 121     virtual void regStats();
 122
 123     /**
 124      * Callback to reset stats.
 125      */
 126     virtual void resetStats();
 127
 128     /**
 129      * Callback before stats are dumped. This can be overridden by
 130      * objects that need to perform calculations in addition to the
 131      * capabiltiies implemented in the stat framework.
 132      */
 133     virtual void preDumpStats();
 134
 135     /**
 136      * Register a stat with this group. This method is normally called
 137      * automatically when a stat is instantiated.
 138      */
 139     void addStat(Stats::Info *info);
 140
 141     /**
 142      * Get all child groups associated with this object.
 143      */
 144     const std::map<std::string, Group *> &getStatGroups() const;
 145
 146     /**
 147      * Get all stats associated with this object.
 148      */
 149     const std::vector<Info *> &getStats() const;
 150
 151      /**
 152      * Add a stat block as a child of this block
 153      *
 154      * This method may only be called from a Group constructor or from
 155      * regStats. It's typically only called explicitly from Python
 156      * when setting up the SimObject hierarchy.
 157      */
 158     void addStatGroup(const char *name, Group *block);
 159
 160     /**
 161      * Resolve a stat by its name within this group.
 162      *
 163      * This method goes through the stats in this group and sub-groups
 164      * and returns a pointer to the the stat that matches the provided
 165      * name. The input name has to be relative to the name of this
 166      * group. For example, if this group is the SimObject
 167      * system.bigCluster.cpus and we want the stat
 168      * system.bigCluster.cpus.ipc, the input param should be the
 169      * string "ipc".
 170      *
 171      * @param name Name of the desired stat
 172      * @return Pointer to the stat with the provided name
 173      */
 174     const Info * resolveStat(std::string name) const;
 175
 176   private:
 177     /**
 178      * Merge the contents (stats & children) of a block to this block.
 179      *
 180      * This is called on a parent group by the child when it is being
 181      * merged into the parent.
 182      */
 183     void mergeStatGroup(Group *block);
 184
 185   private:
 186     /** Parent pointer if merged into parent */
 187     Group *const mergedParent;
 188
 189     std::map<std::string, Group *> statGroups;
 190     std::vector<Group *> mergedStatGroups;
 191     std::vector<Info *> stats;
 192 };
 193
 194 } // namespace Stats
 195
 196 #endif // __BASE_STATS_GROUP_HH__