1 # Copyright (c) 2017-2019 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):
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)
145 text://stats.txt?desc=False
149 return _m5
.stats
.initText(fn
, desc
)
151 @_url_factory([ "h5", ], enable
=hasattr(_m5
.stats
, "initHDF5"))
152 def _hdf5Factory(fn
, chunking
=10, desc
=True, formulas
=True):
153 """Output stats in HDF5 format.
155 The HDF5 file format is a structured binary file format. It has
156 the multiple benefits over traditional text stat files:
158 * Efficient storage of time series (multiple stat dumps)
159 * Fast lookup of stats
160 * Plenty of existing tooling (e.g., Python libraries and graphical
162 * File format can be used to store frame buffers together with
165 There are some drawbacks compared to the default text format:
166 * Large startup cost (single stat dump larger than text equivalent)
167 * Stat dumps are slower than text
171 * Distributions and histograms currently unsupported.
172 * No support for forking.
176 * chunking (unsigned): Number of time steps to pre-allocate (default: 10)
177 * desc (bool): Output stat descriptions (default: True)
178 * formulas (bool): Output derived stats (default: True)
181 h5://stats.h5?desc=False;chunking=100;formulas=False
185 return _m5
.stats
.initHDF5(fn
, chunking
, desc
, formulas
)
187 def addStatVisitor(url
):
188 """Add a stat visitor specified using a URL string
190 Stat visitors are specified using URLs on the following format:
191 format://path[?param=value[;param=value]]
193 The available formats are listed in the factories list. Factories
194 are called with the path as the first positional parameter and the
195 parameters are keyword arguments. Parameter values must be valid
201 from urllib
.parse
import urlsplit
204 from urlparse
import urlsplit
206 parsed
= urlsplit(url
)
209 factory
= factories
[parsed
.scheme
]
211 fatal("Illegal stat file type '%s' specified." % parsed
.scheme
)
214 fatal("Stat type '%s' disabled at compile time" % parsed
.scheme
)
216 outputList
.append(factory(parsed
))
218 def printStatVisitorTypes():
219 """List available stat visitors and their documentation"""
224 for line
in doc
.splitlines():
228 enabled_visitors
= [ x
for x
in all_factories
if x
[2] ]
229 for factory
, schemes
, _
in enabled_visitors
:
230 print("%s:" % ", ".join(filter(lambda x
: x
is not None, schemes
)))
232 # Try to extract the factory doc string
233 print_doc(inspect
.getdoc(factory
))
236 _m5
.stats
.initSimStats()
237 _m5
.stats
.registerPythonStatsHandlers()
239 def _visit_groups(visitor
, root
=None):
241 root
= Root
.getInstance()
242 for group
in root
.getStatGroups().values():
244 _visit_groups(visitor
, root
=group
)
246 def _visit_stats(visitor
, root
=None):
247 def for_each_stat(g
):
248 for stat
in g
.getStats():
250 _visit_groups(for_each_stat
, root
=root
)
252 def _bindStatHierarchy(root
):
253 def _bind_obj(name
, obj
):
254 if isNullPointer(obj
):
256 if m5
.SimObject
.isSimObjectVector(obj
):
258 _bind_obj(name
, obj
[0])
260 for idx
, obj
in enumerate(obj
):
261 _bind_obj("{}{}".format(name
, idx
), obj
)
263 # We need this check because not all obj.getCCObject() is an
264 # instance of Stat::Group. For example, sc_core::sc_module, the C++
265 # class of SystemC_ScModule, is not a subclass of Stat::Group. So
266 # it will cause a type error if obj is a SystemC_ScModule when
267 # calling addStatGroup().
268 if isinstance(obj
.getCCObject(), _m5
.stats
.Group
):
271 if hasattr(parent
, 'addStatGroup'):
272 parent
.addStatGroup(name
, obj
.getCCObject())
274 parent
= parent
.get_parent();
276 _bindStatHierarchy(obj
)
278 for name
, obj
in root
._children
.items():
285 '''Enable the statistics package. Before the statistics package is
286 enabled, all statistics must be created and initialized and once
287 the package is enabled, no more statistics can be created.'''
289 def check_stat(group
, stat
):
290 if not stat
.check() or not stat
.baseCheck():
291 fatal("statistic '%s' (%d) was not properly initialized " \
292 "by a regStats() function\n", stat
.name
, stat
.id)
294 if not (stat
.flags
& flags
.display
):
295 stat
.name
= "__Stat%06d" % stat
.id
300 stats_list
= list(_m5
.stats
.statsList())
302 for stat
in stats_list
:
303 check_stat(None, stat
)
305 stats_list
.sort(key
=lambda s
: s
.name
.split('.'))
306 for stat
in stats_list
:
307 stats_dict
[stat
.name
] = stat
312 _visit_stats(check_stat
)
313 _visit_stats(lambda g
, s
: s
.enable())
318 '''Prepare all stats for data access. This must be done before
319 dumping and serialization.'''
322 for stat
in stats_list
:
326 _visit_stats(lambda g
, s
: s
.prepare())
328 def _dump_to_visitor(visitor
, root
=None):
331 for stat
in stats_list
:
335 def dump_group(group
):
336 for stat
in group
.getStats():
339 for n
, g
in group
.getStatGroups().items():
340 visitor
.beginGroup(n
)
345 for p
in root
.path_list():
346 visitor
.beginGroup(p
)
347 dump_group(root
if root
is not None else Root
.getInstance())
349 for p
in reversed(root
.path_list()):
355 '''Dump all statistics data to the registered outputs'''
359 assert lastDump
<= now
360 new_dump
= lastDump
!= now
363 # Don't allow multiple global stat dumps in the same tick. It's
364 # still possible to dump a multiple sub-trees.
365 if not new_dump
and root
is None:
368 # Only prepare stats the first time we dump them in the same tick.
370 _m5
.stats
.processDumpQueue()
371 # Notify new-style stats group that we are about to dump stats.
372 sim_root
= Root
.getInstance()
374 sim_root
.preDumpStats();
377 for output
in outputList
:
380 _dump_to_visitor(output
, root
=root
)
384 '''Reset all statistics to the base state'''
386 # call reset stats on all SimObjects
387 root
= Root
.getInstance()
391 # call any other registered legacy stats reset callbacks
392 for stat
in stats_list
:
395 _m5
.stats
.processResetQueue()