1 # Copyright (c) 2017-2020 ARM Limited
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.
13 # Copyright (c) 2007 The Regents of The University of Michigan
14 # Copyright (c) 2010 The Hewlett-Packard Development Company
15 # All rights reserved.
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.
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.
40 from __future__
import print_function
41 from __future__
import absolute_import
46 from m5
.objects
import Root
47 from m5
.params
import isNullPointer
48 from m5
.util
import attrdict
, fatal
51 from _m5
.stats
import schedStatEvent
as schedEvent
52 from _m5
.stats
import periodicStatDump
56 # Dictionary of stat visitor factories populated by the _url_factory
60 # List of all factories. Contains tuples of (factory, schemes,
64 def _url_factory(schemes
, enable
=True):
65 """Wrap a plain Python function with URL parsing helpers
67 Wrap a plain Python function f(fn, **kwargs) to expect a URL that
68 has been split using urlparse.urlsplit. First positional argument
69 is assumed to be a filename, this is created as the concatenation
70 of the netloc (~hostname) and path in the parsed URL. Keyword
71 arguments are derived from the query values in the URL.
74 schemes: A list of URL schemes to use for this function.
77 enable: Enable/disable this factory. Typically used when the
78 presence of a function depends on some runtime property.
81 wrapped_f(urlparse.urlsplit("text://stats.txt?desc=False")) ->
82 f("stats.txt", desc=False)
86 from functools
import wraps
92 from urllib
.parse
import parse_qs
95 from urlparse
import parse_qs
96 from ast
import literal_eval
98 qs
= parse_qs(url
.query
, keep_blank_values
=True)
100 # parse_qs returns a list of values for each parameter. Only
101 # use the last value since kwargs don't allow multiple values
102 # per parameter. Use literal_eval to transform string param
103 # values into proper Python types.
104 def parse_value(key
, values
):
105 if len(values
) == 0 or (len(values
) == 1 and not values
[0]):
106 fatal("%s: '%s' doesn't have a value." % (
108 elif len(values
) > 1:
109 fatal("%s: '%s' has multiple values." % (
113 return key
, literal_eval(values
[0])
115 fatal("%s: %s isn't a valid Python literal" \
116 % (url
.geturl(), values
[0]))
118 kwargs
= dict([ parse_value(k
, v
) for k
, v
in qs
.items() ])
121 return func("%s%s" % (url
.netloc
, url
.path
), **kwargs
)
123 fatal("Illegal stat visitor parameter specified")
125 all_factories
.append((wrapper
, schemes
, enable
))
126 for scheme
in schemes
:
127 assert scheme
not in factories
128 factories
[scheme
] = wrapper
if enable
else None
133 @_url_factory([ None, "", "text", "file", ])
134 def _textFactory(fn
, desc
=True, spaces
=True):
135 """Output stats in text format.
137 Text stat files contain one stat per line with an optional
138 description. The description is enabled by default, but can be
139 disabled by setting the desc parameter to False.
142 * desc (bool): Output stat descriptions (default: True)
143 * spaces (bool): Output alignment spaces (default: True)
146 text://stats.txt?desc=False;spaces=False
150 return _m5
.stats
.initText(fn
, desc
, spaces
)
152 @_url_factory([ "h5", ], enable
=hasattr(_m5
.stats
, "initHDF5"))
153 def _hdf5Factory(fn
, chunking
=10, desc
=True, formulas
=True):
154 """Output stats in HDF5 format.
156 The HDF5 file format is a structured binary file format. It has
157 the multiple benefits over traditional text stat files:
159 * Efficient storage of time series (multiple stat dumps)
160 * Fast lookup of stats
161 * Plenty of existing tooling (e.g., Python libraries and graphical
163 * File format can be used to store frame buffers together with
166 There are some drawbacks compared to the default text format:
167 * Large startup cost (single stat dump larger than text equivalent)
168 * Stat dumps are slower than text
172 * Distributions and histograms currently unsupported.
173 * No support for forking.
177 * chunking (unsigned): Number of time steps to pre-allocate (default: 10)
178 * desc (bool): Output stat descriptions (default: True)
179 * formulas (bool): Output derived stats (default: True)
182 h5://stats.h5?desc=False;chunking=100;formulas=False
186 return _m5
.stats
.initHDF5(fn
, chunking
, desc
, formulas
)
188 def addStatVisitor(url
):
189 """Add a stat visitor specified using a URL string
191 Stat visitors are specified using URLs on the following format:
192 format://path[?param=value[;param=value]]
194 The available formats are listed in the factories list. Factories
195 are called with the path as the first positional parameter and the
196 parameters are keyword arguments. Parameter values must be valid
202 from urllib
.parse
import urlsplit
205 from urlparse
import urlsplit
207 parsed
= urlsplit(url
)
210 factory
= factories
[parsed
.scheme
]
212 fatal("Illegal stat file type '%s' specified." % parsed
.scheme
)
215 fatal("Stat type '%s' disabled at compile time" % parsed
.scheme
)
217 outputList
.append(factory(parsed
))
219 def printStatVisitorTypes():
220 """List available stat visitors and their documentation"""
225 for line
in doc
.splitlines():
229 enabled_visitors
= [ x
for x
in all_factories
if x
[2] ]
230 for factory
, schemes
, _
in enabled_visitors
:
231 print("%s:" % ", ".join(filter(lambda x
: x
is not None, schemes
)))
233 # Try to extract the factory doc string
234 print_doc(inspect
.getdoc(factory
))
237 _m5
.stats
.initSimStats()
238 _m5
.stats
.registerPythonStatsHandlers()
240 def _visit_groups(visitor
, root
=None):
242 root
= Root
.getInstance()
243 for group
in root
.getStatGroups().values():
245 _visit_groups(visitor
, root
=group
)
247 def _visit_stats(visitor
, root
=None):
248 def for_each_stat(g
):
249 for stat
in g
.getStats():
251 _visit_groups(for_each_stat
, root
=root
)
253 def _bindStatHierarchy(root
):
254 def _bind_obj(name
, obj
):
255 if isNullPointer(obj
):
257 if m5
.SimObject
.isSimObjectVector(obj
):
259 _bind_obj(name
, obj
[0])
261 for idx
, obj
in enumerate(obj
):
262 _bind_obj("{}{}".format(name
, idx
), obj
)
264 # We need this check because not all obj.getCCObject() is an
265 # instance of Stat::Group. For example, sc_core::sc_module, the C++
266 # class of SystemC_ScModule, is not a subclass of Stat::Group. So
267 # it will cause a type error if obj is a SystemC_ScModule when
268 # calling addStatGroup().
269 if isinstance(obj
.getCCObject(), _m5
.stats
.Group
):
272 if hasattr(parent
, 'addStatGroup'):
273 parent
.addStatGroup(name
, obj
.getCCObject())
275 parent
= parent
.get_parent();
277 _bindStatHierarchy(obj
)
279 for name
, obj
in root
._children
.items():
286 '''Enable the statistics package. Before the statistics package is
287 enabled, all statistics must be created and initialized and once
288 the package is enabled, no more statistics can be created.'''
290 def check_stat(group
, stat
):
291 if not stat
.check() or not stat
.baseCheck():
292 fatal("statistic '%s' (%d) was not properly initialized " \
293 "by a regStats() function\n", stat
.name
, stat
.id)
295 if not (stat
.flags
& flags
.display
):
296 stat
.name
= "__Stat%06d" % stat
.id
301 stats_list
= list(_m5
.stats
.statsList())
303 for stat
in stats_list
:
304 check_stat(None, stat
)
306 stats_list
.sort(key
=lambda s
: s
.name
.split('.'))
307 for stat
in stats_list
:
308 stats_dict
[stat
.name
] = stat
313 _visit_stats(check_stat
)
314 _visit_stats(lambda g
, s
: s
.enable())
319 '''Prepare all stats for data access. This must be done before
320 dumping and serialization.'''
323 for stat
in stats_list
:
327 _visit_stats(lambda g
, s
: s
.prepare())
329 def _dump_to_visitor(visitor
, roots
=None):
331 def dump_group(group
):
332 for stat
in group
.getStats():
334 for n
, g
in group
.getStatGroups().items():
335 visitor
.beginGroup(n
)
340 # New stats from selected subroots.
342 for p
in root
.path_list():
343 visitor
.beginGroup(p
)
345 for p
in reversed(root
.path_list()):
349 for stat
in stats_list
:
352 # New stats starting from root.
353 dump_group(Root
.getInstance())
357 global_dump_roots
= []
359 def dump(roots
=None):
360 '''Dump all statistics data to the registered outputs'''
363 if roots
is not None:
364 all_roots
.extend(roots
)
365 global global_dump_roots
366 all_roots
.extend(global_dump_roots
)
370 assert lastDump
<= now
371 new_dump
= lastDump
!= now
374 # Don't allow multiple global stat dumps in the same tick. It's
375 # still possible to dump a multiple sub-trees.
376 if not new_dump
and not all_roots
:
379 # Only prepare stats the first time we dump them in the same tick.
381 _m5
.stats
.processDumpQueue()
382 # Notify new-style stats group that we are about to dump stats.
383 sim_root
= Root
.getInstance()
385 sim_root
.preDumpStats();
388 for output
in outputList
:
391 _dump_to_visitor(output
, roots
=all_roots
)
395 '''Reset all statistics to the base state'''
397 # call reset stats on all SimObjects
398 root
= Root
.getInstance()
402 # call any other registered legacy stats reset callbacks
403 for stat
in stats_list
:
406 _m5
.stats
.processResetQueue()