1/*
2 * Copyright (c) 2019 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 * Authors: Andreas Sandberg
38 */
39
40#ifndef __BASE_STATS_GROUP_HH__
41#define __BASE_STATS_GROUP_HH__
42
43#include <map>
44#include <vector>
45#include <string>
46
47/**
48 * Convenience macro to add a stat to a statistics group.
49 *
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:
54 *
55 * \code
56 * struct MyStats : public Stats::Group
57 * {
58 *     Stats::Scalar scalar0;
59 *     Stats::Scalar scalar1;
60 *
61 *     Group()
62 *         : ADD_STAT(scalar0, "Description of scalar0"),
63 *           scalar1(this, "scalar1", "Description of scalar1")
64 *     {
65 *     }
66 * };
67 * \endcode
68 */
69#define ADD_STAT(n, ...) n(this, # n, __VA_ARGS__)
70
71namespace Stats {
72
73class Info;
74
75/**
76 * Statistics container.
77 *
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).
84 */
85class Group
86{
87  public:
88    Group() = delete;
89    Group(const Group &) = delete;
90    Group &operator=(const Group &) = delete;
91
92    /**
93     * Construct a new statistics group.
94     *
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.
100     *
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
104     * the parent group.
105     *
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.
109     */
110    Group(Group *parent, const char *name = nullptr);
111
112    virtual ~Group();
113
114    /**
115     * Callback to set stat parameters.
116     *
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
121     * ADD_STAT macro.
122     */
123    virtual void regStats();
124
125    /**
126     * Callback to reset stats.
127     */
128    virtual void resetStats();
129
130    /**
131     * Register a stat with this group. This method is normally called
132     * automatically when a stat is instantiated.
133     */
134    void addStat(Stats::Info *info);
135
136    /**
137     * Get all child groups associated with this object.
138     */
139    const std::map<std::string, Group *> &getStatGroups() const;
140
141    /**
142     * Get all stats associated with this object.
143     */
144    const std::vector<Info *> &getStats() const;
145
146     /**
147     * Add a stat block as a child of this block
148     *
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.
152     */
153    void addStatGroup(const char *name, Group *block);
154
155  private:
156    /**
157     * Merge the contents (stats & children) of a block to this block.
158     *
159     * This is called on a parent group by the child when it is being
160     * merged into the parent.
161     */
162    void mergeStatGroup(Group *block);
163
164  private:
165    /** Parent pointer if merged into parent */
166    Group *const mergedParent;
167
168    std::map<std::string, Group *> statGroups;
169    std::vector<Group *> mergedStatGroups;
170    std::vector<Info *> stats;
171};
172
173} // namespace Stats
174
175#endif // __BASE_STATS_GROUP_HH__
176