src/python/m5/stats/__init__.py

   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
  43 import m5
  44
  45 import _m5.stats
  46 from m5.objects import Root
  47 from m5.util import attrdict, fatal
  48
  49 # Stat exports
  50 from _m5.stats import schedStatEvent as schedEvent
  51 from _m5.stats import periodicStatDump
  52
  53 outputList = []
  54
  55 def _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
 109 def _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
 122 factories = {
 123     # Default to the text factory if we're given a naked path
 124     "" : _textFactory,
 125     "file" : _textFactory,
 126     "text" : _textFactory,
 127 }
 128
 129 def 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
 157 def initSimStats():
 158     _m5.stats.initSimStats()
 159     _m5.stats.registerPythonStatsHandlers()
 160
 161 def _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
 168 def _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
 174 def _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
 186 names = []
 187 stats_dict = {}
 188 stats_list = []
 189 def 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
 222 def 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
 233 def _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
 257 lastDump = 0
 258
 259 def 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
 284 def 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
 298 flags = 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 })