2 * Copyright (c) 2019 Arm Limited
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.
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.
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.
37 * Authors: Andreas Sandberg
40 #ifndef __BASE_STATS_GROUP_HH__
41 #define __BASE_STATS_GROUP_HH__
48 * Convenience macro to add a stat to a statistics group.
50 * This macro is used to add a stat to a Stats::Group in the
51 * initilization list in the Group's constructor. The macro
52 * automatically assigns the stat to the current group and gives it
53 * the same name as in the class. For example:
56 * struct MyStats : public Stats::Group
58 * Stats::Scalar scalar0;
59 * Stats::Scalar scalar1;
62 * : ADD_STAT(scalar0, "Description of scalar0"),
63 * scalar1(this, "scalar1", "Description of scalar1")
69 #define ADD_STAT(n, ...) n(this, # n, __VA_ARGS__)
76 * Statistics container.
78 * A stat group is a hierarchical structure that contain statistics
79 * and other groups. Groups are used by the stat system to reflect
80 * gem5's SimObject hierarchy and to expose internal hierarchy within
81 * an object. They can also be used to conveniently group stats into
82 * their own class/struct and then be merged into the parent group
83 * (typically a SimObject).
89 Group(const Group &) = delete;
90 Group &operator=(const Group &) = delete;
93 * Construct a new statistics group.
95 * The constructor takes two parameters, a parent and a name. The
96 * parent group should typically be specified. However, there are
97 * special cases where the parent group may be null. One such
98 * special case is SimObjects where the Python code performs late
99 * binding of the group parent.
101 * If the name parameter is NULL, the group gets merged into the
102 * parent group instead of creating a sub-group. Stats belonging
103 * to a merged group behave as if they have been added directly to
106 * @param parent Parent group to associate this object to.
107 * @param name Name of this group, can be NULL to merge this group
108 * with the parent group.
110 Group(Group *parent, const char *name = nullptr);
115 * Callback to set stat parameters.
117 * This callback is typically used for complex stats (e.g.,
118 * distributions) that need parameters in addition to a name and a
119 * description. Stat names and descriptions should typically be
120 * set from the constructor usingo from the constructor using the
123 virtual void regStats();
126 * Callback to reset stats.
128 virtual void resetStats();
131 * Register a stat with this group. This method is normally called
132 * automatically when a stat is instantiated.
134 void addStat(Stats::Info *info);
137 * Get all child groups associated with this object.
139 const std::map<std::string, Group *> &getStatGroups() const;
142 * Get all stats associated with this object.
144 const std::vector<Info *> &getStats() const;
147 * Add a stat block as a child of this block
149 * This method may only be called from a Group constructor or from
150 * regStats. It's typically only called explicitly from Python
151 * when setting up the SimObject hierarchy.
153 void addStatGroup(const char *name, Group *block);
157 * Merge the contents (stats & children) of a block to this block.
159 * This is called on a parent group by the child when it is being
160 * merged into the parent.
162 void mergeStatGroup(Group *block);
165 /** Parent pointer if merged into parent */
166 Group *const mergedParent;
168 std::map<std::string, Group *> statGroups;
169 std::vector<Group *> mergedStatGroups;
170 std::vector<Info *> stats;
175 #endif // __BASE_STATS_GROUP_HH__