__init__.py revision 14206:9cd30cd80145 
1# Copyright (c) 2017, 2019 Arm Limited
2# All rights reserved.
3#
4# The license below extends only to copyright in the software and shall
5# not be construed as granting a license to any other intellectual
6# property including but not limited to intellectual property relating
7# to a hardware implementation of the functionality of the software
8# licensed hereunder.  You may use the software subject to the license
9# terms below provided that you ensure that this notice is replicated
10# unmodified and in its entirety in all distributions of the software,
11# modified or unmodified, in source code or in binary form.
12#
13# Copyright (c) 2007 The Regents of The University of Michigan
14# Copyright (c) 2010 The Hewlett-Packard Development Company
15# All rights reserved.
16#
17# Redistribution and use in source and binary forms, with or without
18# modification, are permitted provided that the following conditions are
19# met: redistributions of source code must retain the above copyright
20# notice, this list of conditions and the following disclaimer;
21# redistributions in binary form must reproduce the above copyright
22# notice, this list of conditions and the following disclaimer in the
23# documentation and/or other materials provided with the distribution;
24# neither the name of the copyright holders nor the names of its
25# contributors may be used to endorse or promote products derived from
26# this software without specific prior written permission.
27#
28# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
29# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
30# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
31# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
32# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
33# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
34# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
35# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
36# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
37# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
38# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39#
40# Authors: Nathan Binkert
41#          Andreas Sandberg
42
43import m5
44
45import _m5.stats
46from m5.objects import Root
47from m5.util import attrdict, fatal
48
49# Stat exports
50from _m5.stats import schedStatEvent as schedEvent
51from _m5.stats import periodicStatDump
52
53outputList = []
54
55def _url_factory(func):
56    """Wrap a plain Python function with URL parsing helpers
57
58    Wrap a plain Python function f(fn, **kwargs) to expect a URL that
59    has been split using urlparse.urlsplit. First positional argument
60    is assumed to be a filename, this is created as the concatenation
61    of the netloc (~hostname) and path in the parsed URL. Keyword
62    arguments are derived from the query values in the URL.
63
64    For example:
65        wrapped_f(urlparse.urlsplit("text://stats.txt?desc=False")) ->
66        f("stats.txt", desc=False)
67
68    """
69
70    from functools import wraps
71
72    @wraps(func)
73    def wrapper(url):
74        try:
75            from urllib.parse import parse_qs
76        except ImportError:
77            # Python 2 fallback
78            from urlparse import parse_qs
79        from ast import literal_eval
80
81        qs = parse_qs(url.query, keep_blank_values=True)
82
83        # parse_qs returns a list of values for each parameter. Only
84        # use the last value since kwargs don't allow multiple values
85        # per parameter. Use literal_eval to transform string param
86        # values into proper Python types.
87        def parse_value(key, values):
88            if len(values) == 0 or (len(values) == 1 and not values[0]):
89                fatal("%s: '%s' doesn't have a value." % (url.geturl(), key))
90            elif len(values) > 1:
91                fatal("%s: '%s' has multiple values." % (url.geturl(), key))
92            else:
93                try:
94                    return key, literal_eval(values[0])
95                except ValueError:
96                    fatal("%s: %s isn't a valid Python literal" \
97                          % (url.geturl(), values[0]))
98
99        kwargs = dict([ parse_value(k, v) for k, v in qs.items() ])
100
101        try:
102            return func("%s%s" % (url.netloc, url.path), **kwargs)
103        except TypeError:
104            fatal("Illegal stat visitor parameter specified")
105
106    return wrapper
107
108@_url_factory
109def _textFactory(fn, desc=True):
110    """Output stats in text format.
111
112    Text stat files contain one stat per line with an optional
113    description. The description is enabled by default, but can be
114    disabled by setting the desc parameter to False.
115
116    Example: text://stats.txt?desc=False
117
118    """
119
120    return _m5.stats.initText(fn, desc)
121
122factories = {
123    # Default to the text factory if we're given a naked path
124    "" : _textFactory,
125    "file" : _textFactory,
126    "text" : _textFactory,
127}
128
129def addStatVisitor(url):
130    """Add a stat visitor specified using a URL string
131
132    Stat visitors are specified using URLs on the following format:
133    format://path[?param=value[;param=value]]
134
135    The available formats are listed in the factories list. Factories
136    are called with the path as the first positional parameter and the
137    parameters are keyword arguments. Parameter values must be valid
138    Python literals.
139
140    """
141
142    try:
143        from urllib.parse import urlsplit
144    except ImportError:
145        # Python 2 fallback
146        from urlparse import urlsplit
147
148    parsed = urlsplit(url)
149
150    try:
151        factory = factories[parsed.scheme]
152    except KeyError:
153        fatal("Illegal stat file type specified.")
154
155    outputList.append(factory(parsed))
156
157def initSimStats():
158    _m5.stats.initSimStats()
159    _m5.stats.registerPythonStatsHandlers()
160
161def _visit_groups(visitor, root=None):
162    if root is None:
163        root = Root.getInstance()
164    for group in root.getStatGroups().values():
165        visitor(group)
166        _visit_groups(visitor, root=group)
167
168def _visit_stats(visitor, root=None):
169    def for_each_stat(g):
170        for stat in g.getStats():
171            visitor(g, stat)
172    _visit_groups(for_each_stat, root=root)
173
174def _bindStatHierarchy(root):
175    def _bind_obj(name, obj):
176        if m5.SimObject.isSimObjectVector(obj):
177            for idx, obj in enumerate(obj):
178                _bind_obj("{}{}".format(name, idx), obj)
179        else:
180            root.addStatGroup(name, obj.getCCObject())
181            _bindStatHierarchy(obj)
182
183    for name, obj in root._children.items():
184        _bind_obj(name, obj)
185
186names = []
187stats_dict = {}
188stats_list = []
189def enable():
190    '''Enable the statistics package.  Before the statistics package is
191    enabled, all statistics must be created and initialized and once
192    the package is enabled, no more statistics can be created.'''
193
194    def check_stat(group, stat):
195        if not stat.check() or not stat.baseCheck():
196            fatal("statistic '%s' (%d) was not properly initialized " \
197                  "by a regStats() function\n", stat.name, stat.id)
198
199        if not (stat.flags & flags.display):
200            stat.name = "__Stat%06d" % stat.id
201
202
203    # Legacy stat
204    global stats_list
205    stats_list = list(_m5.stats.statsList())
206
207    for stat in stats_list:
208        check_stat(None, stat)
209
210    stats_list.sort(key=lambda s: s.name.split('.'))
211    for stat in stats_list:
212        stats_dict[stat.name] = stat
213        stat.enable()
214
215
216    # New stats
217    _visit_stats(check_stat)
218    _visit_stats(lambda g, s: s.enable())
219
220    _m5.stats.enable();
221
222def prepare():
223    '''Prepare all stats for data access.  This must be done before
224    dumping and serialization.'''
225
226    # Legacy stats
227    for stat in stats_list:
228        stat.prepare()
229
230    # New stats
231    _visit_stats(lambda g, s: s.prepare())
232
233def _dump_to_visitor(visitor, root=None):
234    # Legacy stats
235    if root is None:
236        for stat in stats_list:
237            stat.visit(visitor)
238
239    # New stats
240    def dump_group(group):
241        for stat in group.getStats():
242            stat.visit(visitor)
243
244        for n, g in group.getStatGroups().items():
245            visitor.beginGroup(n)
246            dump_group(g)
247            visitor.endGroup()
248
249    if root is not None:
250        for p in root.path_list():
251            visitor.beginGroup(p)
252    dump_group(root if root is not None else Root.getInstance())
253    if root is not None:
254        for p in reversed(root.path_list()):
255            visitor.endGroup()
256
257lastDump = 0
258
259def dump(root=None):
260    '''Dump all statistics data to the registered outputs'''
261
262    now = m5.curTick()
263    global lastDump
264    assert lastDump <= now
265    new_dump = lastDump != now
266    lastDump = now
267
268    # Don't allow multiple global stat dumps in the same tick. It's
269    # still possible to dump a multiple sub-trees.
270    if not new_dump and root is None:
271        return
272
273    # Only prepare stats the first time we dump them in the same tick.
274    if new_dump:
275        _m5.stats.processDumpQueue()
276        prepare()
277
278    for output in outputList:
279        if output.valid():
280            output.begin()
281            _dump_to_visitor(output, root=root)
282            output.end()
283
284def reset():
285    '''Reset all statistics to the base state'''
286
287    # call reset stats on all SimObjects
288    root = Root.getInstance()
289    if root:
290        root.resetStats()
291
292    # call any other registered legacy stats reset callbacks
293    for stat in stats_list:
294        stat.reset()
295
296    _m5.stats.processResetQueue()
297
298flags = attrdict({
299    'none'    : 0x0000,
300    'init'    : 0x0001,
301    'display' : 0x0002,
302    'total'   : 0x0010,
303    'pdf'     : 0x0020,
304    'cdf'     : 0x0040,
305    'dist'    : 0x0080,
306    'nozero'  : 0x0100,
307    'nonan'   : 0x0200,
308})
309