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.
38 #ifndef __BASE_STATS_GROUP_HH__
39 #define __BASE_STATS_GROUP_HH__
46 * Convenience macro to add a stat to a statistics group.
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:
54 * struct MyStats : public Stats::Group
56 * Stats::Scalar scalar0;
57 * Stats::Scalar scalar1;
60 * : ADD_STAT(scalar0, "Description of scalar0"),
61 * scalar1(this, "scalar1", "Description of scalar1")
67 #define ADD_STAT(n, ...) n(this, # n, __VA_ARGS__)
74 * Statistics container.
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).
87 Group(const Group &) = delete;
88 Group &operator=(const Group &) = delete;
91 * Construct a new statistics group.
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.
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
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.
108 Group(Group *parent, const char *name = nullptr);
113 * Callback to set stat parameters.
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
121 virtual void regStats();
124 * Callback to reset stats.
126 virtual void resetStats();
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.
133 virtual void preDumpStats();
136 * Register a stat with this group. This method is normally called
137 * automatically when a stat is instantiated.
139 void addStat(Stats::Info *info);
142 * Get all child groups associated with this object.
144 const std::map<std::string, Group *> &getStatGroups() const;
147 * Get all stats associated with this object.
149 const std::vector<Info *> &getStats() const;
152 * Add a stat block as a child of this block
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.
158 void addStatGroup(const char *name, Group *block);
162 * Merge the contents (stats & children) of a block to this block.
164 * This is called on a parent group by the child when it is being
165 * merged into the parent.
167 void mergeStatGroup(Group *block);
170 /** Parent pointer if merged into parent */
171 Group *const mergedParent;
173 std::map<std::string, Group *> statGroups;
174 std::vector<Group *> mergedStatGroups;
175 std::vector<Info *> stats;
180 #endif // __BASE_STATS_GROUP_HH__