scripts/tracetool/__init__.py

   1 #!/usr/bin/env python
   2 # -*- coding: utf-8 -*-
   3
   4 """
   5 Machinery for generating tracing-related intermediate files.
   6 """
   7
   8 __author__     = "Lluís Vilanova <vilanova@ac.upc.edu>"
   9 __copyright__  = "Copyright 2012-2017, Lluís Vilanova <vilanova@ac.upc.edu>"
  10 __license__    = "GPL version 2 or (at your option) any later version"
  11
  12 __maintainer__ = "Stefan Hajnoczi"
  13 __email__      = "stefanha@linux.vnet.ibm.com"
  14
  15
  16 import re
  17 import sys
  18 import weakref
  19
  20 import tracetool.format
  21 import tracetool.backend
  22 import tracetool.transform
  23
  24
  25 def error_write(*lines):
  26     """Write a set of error lines."""
  27     sys.stderr.writelines("\n".join(lines) + "\n")
  28
  29 def error(*lines):
  30     """Write a set of error lines and exit."""
  31     error_write(*lines)
  32     sys.exit(1)
  33
  34
  35 def out(*lines, **kwargs):
  36     """Write a set of output lines.
  37
  38     You can use kwargs as a shorthand for mapping variables when formating all
  39     the strings in lines.
  40     """
  41     lines = [ l % kwargs for l in lines ]
  42     sys.stdout.writelines("\n".join(lines) + "\n")
  43
  44 # We only want to allow standard C types or fixed sized
  45 # integer types. We don't want QEMU specific types
  46 # as we can't assume trace backends can resolve all the
  47 # typedefs
  48 ALLOWED_TYPES = [
  49     "int",
  50     "long",
  51     "short",
  52     "char",
  53     "bool",
  54     "unsigned",
  55     "signed",
  56     "int8_t",
  57     "uint8_t",
  58     "int16_t",
  59     "uint16_t",
  60     "int32_t",
  61     "uint32_t",
  62     "int64_t",
  63     "uint64_t",
  64     "void",
  65     "size_t",
  66     "ssize_t",
  67     "uintptr_t",
  68     "ptrdiff_t",
  69     # Magic substitution is done by tracetool
  70     "TCGv",
  71 ]
  72
  73 def validate_type(name):
  74     bits = name.split(" ")
  75     for bit in bits:
  76         bit = re.sub("\*", "", bit)
  77         if bit == "":
  78             continue
  79         if bit == "const":
  80             continue
  81         if bit not in ALLOWED_TYPES:
  82             raise ValueError("Argument type '%s' is not in whitelist. "
  83                              "Only standard C types and fixed size integer "
  84                              "types should be used. struct, union, and "
  85                              "other complex pointer types should be "
  86                              "declared as 'void *'" % name)
  87
  88 class Arguments:
  89     """Event arguments description."""
  90
  91     def __init__(self, args):
  92         """
  93         Parameters
  94         ----------
  95         args :
  96             List of (type, name) tuples or Arguments objects.
  97         """
  98         self._args = []
  99         for arg in args:
 100             if isinstance(arg, Arguments):
 101                 self._args.extend(arg._args)
 102             else:
 103                 self._args.append(arg)
 104
 105     def copy(self):
 106         """Create a new copy."""
 107         return Arguments(list(self._args))
 108
 109     @staticmethod
 110     def build(arg_str):
 111         """Build and Arguments instance from an argument string.
 112
 113         Parameters
 114         ----------
 115         arg_str : str
 116             String describing the event arguments.
 117         """
 118         res = []
 119         for arg in arg_str.split(","):
 120             arg = arg.strip()
 121             if not arg:
 122                 raise ValueError("Empty argument (did you forget to use 'void'?)")
 123             if arg == 'void':
 124                 continue
 125
 126             if '*' in arg:
 127                 arg_type, identifier = arg.rsplit('*', 1)
 128                 arg_type += '*'
 129                 identifier = identifier.strip()
 130             else:
 131                 arg_type, identifier = arg.rsplit(None, 1)
 132
 133             validate_type(arg_type)
 134             res.append((arg_type, identifier))
 135         return Arguments(res)
 136
 137     def __getitem__(self, index):
 138         if isinstance(index, slice):
 139             return Arguments(self._args[index])
 140         else:
 141             return self._args[index]
 142
 143     def __iter__(self):
 144         """Iterate over the (type, name) pairs."""
 145         return iter(self._args)
 146
 147     def __len__(self):
 148         """Number of arguments."""
 149         return len(self._args)
 150
 151     def __str__(self):
 152         """String suitable for declaring function arguments."""
 153         if len(self._args) == 0:
 154             return "void"
 155         else:
 156             return ", ".join([ " ".join([t, n]) for t,n in self._args ])
 157
 158     def __repr__(self):
 159         """Evaluable string representation for this object."""
 160         return "Arguments(\"%s\")" % str(self)
 161
 162     def names(self):
 163         """List of argument names."""
 164         return [ name for _, name in self._args ]
 165
 166     def types(self):
 167         """List of argument types."""
 168         return [ type_ for type_, _ in self._args ]
 169
 170     def casted(self):
 171         """List of argument names casted to their type."""
 172         return ["(%s)%s" % (type_, name) for type_, name in self._args]
 173
 174     def transform(self, *trans):
 175         """Return a new Arguments instance with transformed types.
 176
 177         The types in the resulting Arguments instance are transformed according
 178         to tracetool.transform.transform_type.
 179         """
 180         res = []
 181         for type_, name in self._args:
 182             res.append((tracetool.transform.transform_type(type_, *trans),
 183                         name))
 184         return Arguments(res)
 185
 186
 187 class Event(object):
 188     """Event description.
 189
 190     Attributes
 191     ----------
 192     name : str
 193         The event name.
 194     fmt : str
 195         The event format string.
 196     properties : set(str)
 197         Properties of the event.
 198     args : Arguments
 199         The event arguments.
 200
 201     """
 202
 203     _CRE = re.compile("((?P<props>[\w\s]+)\s+)?"
 204                       "(?P<name>\w+)"
 205                       "\((?P<args>[^)]*)\)"
 206                       "\s*"
 207                       "(?:(?:(?P<fmt_trans>\".+),)?\s*(?P<fmt>\".+))?"
 208                       "\s*")
 209
 210     _VALID_PROPS = set(["disable", "tcg", "tcg-trans", "tcg-exec", "vcpu"])
 211
 212     def __init__(self, name, props, fmt, args, orig=None,
 213                  event_trans=None, event_exec=None):
 214         """
 215         Parameters
 216         ----------
 217         name : string
 218             Event name.
 219         props : list of str
 220             Property names.
 221         fmt : str, list of str
 222             Event printing format string(s).
 223         args : Arguments
 224             Event arguments.
 225         orig : Event or None
 226             Original Event before transformation/generation.
 227         event_trans : Event or None
 228             Generated translation-time event ("tcg" property).
 229         event_exec : Event or None
 230             Generated execution-time event ("tcg" property).
 231
 232         """
 233         self.name = name
 234         self.properties = props
 235         self.fmt = fmt
 236         self.args = args
 237         self.event_trans = event_trans
 238         self.event_exec = event_exec
 239
 240         if len(args) > 10:
 241             raise ValueError("Event '%s' has more than maximum permitted "
 242                              "argument count" % name)
 243
 244         if orig is None:
 245             self.original = weakref.ref(self)
 246         else:
 247             self.original = orig
 248
 249         unknown_props = set(self.properties) - self._VALID_PROPS
 250         if len(unknown_props) > 0:
 251             raise ValueError("Unknown properties: %s"
 252                              % ", ".join(unknown_props))
 253         assert isinstance(self.fmt, str) or len(self.fmt) == 2
 254
 255     def copy(self):
 256         """Create a new copy."""
 257         return Event(self.name, list(self.properties), self.fmt,
 258                      self.args.copy(), self, self.event_trans, self.event_exec)
 259
 260     @staticmethod
 261     def build(line_str):
 262         """Build an Event instance from a string.
 263
 264         Parameters
 265         ----------
 266         line_str : str
 267             Line describing the event.
 268         """
 269         m = Event._CRE.match(line_str)
 270         assert m is not None
 271         groups = m.groupdict('')
 272
 273         name = groups["name"]
 274         props = groups["props"].split()
 275         fmt = groups["fmt"]
 276         fmt_trans = groups["fmt_trans"]
 277         if fmt.find("%m") != -1 or fmt_trans.find("%m") != -1:
 278             raise ValueError("Event format '%m' is forbidden, pass the error "
 279                              "as an explicit trace argument")
 280
 281         if len(fmt_trans) > 0:
 282             fmt = [fmt_trans, fmt]
 283         args = Arguments.build(groups["args"])
 284
 285         if "tcg-trans" in props:
 286             raise ValueError("Invalid property 'tcg-trans'")
 287         if "tcg-exec" in props:
 288             raise ValueError("Invalid property 'tcg-exec'")
 289         if "tcg" not in props and not isinstance(fmt, str):
 290             raise ValueError("Only events with 'tcg' property can have two format strings")
 291         if "tcg" in props and isinstance(fmt, str):
 292             raise ValueError("Events with 'tcg' property must have two format strings")
 293
 294         event = Event(name, props, fmt, args)
 295
 296         # add implicit arguments when using the 'vcpu' property
 297         import tracetool.vcpu
 298         event = tracetool.vcpu.transform_event(event)
 299
 300         return event
 301
 302     def __repr__(self):
 303         """Evaluable string representation for this object."""
 304         if isinstance(self.fmt, str):
 305             fmt = self.fmt
 306         else:
 307             fmt = "%s, %s" % (self.fmt[0], self.fmt[1])
 308         return "Event('%s %s(%s) %s')" % (" ".join(self.properties),
 309                                           self.name,
 310                                           self.args,
 311                                           fmt)
 312     # Star matching on PRI is dangerous as one might have multiple
 313     # arguments with that format, hence the non-greedy version of it.
 314     _FMT = re.compile("(%[\d\.]*\w+|%.*?PRI\S+)")
 315
 316     def formats(self):
 317         """List conversion specifiers in the argument print format string."""
 318         assert not isinstance(self.fmt, list)
 319         return self._FMT.findall(self.fmt)
 320
 321     QEMU_TRACE               = "trace_%(name)s"
 322     QEMU_TRACE_NOCHECK       = "_nocheck__" + QEMU_TRACE
 323     QEMU_TRACE_TCG           = QEMU_TRACE + "_tcg"
 324     QEMU_DSTATE              = "_TRACE_%(NAME)s_DSTATE"
 325     QEMU_BACKEND_DSTATE      = "TRACE_%(NAME)s_BACKEND_DSTATE"
 326     QEMU_EVENT               = "_TRACE_%(NAME)s_EVENT"
 327
 328     def api(self, fmt=None):
 329         if fmt is None:
 330             fmt = Event.QEMU_TRACE
 331         return fmt % {"name": self.name, "NAME": self.name.upper()}
 332
 333     def transform(self, *trans):
 334         """Return a new Event with transformed Arguments."""
 335         return Event(self.name,
 336                      list(self.properties),
 337                      self.fmt,
 338                      self.args.transform(*trans),
 339                      self)
 340
 341
 342 def read_events(fobj, fname):
 343     """Generate the output for the given (format, backends) pair.
 344
 345     Parameters
 346     ----------
 347     fobj : file
 348         Event description file.
 349     fname : str
 350         Name of event file
 351
 352     Returns a list of Event objects
 353     """
 354
 355     events = []
 356     for lineno, line in enumerate(fobj, 1):
 357         if line[-1] != '\n':
 358             raise ValueError("%s does not end with a new line" % fname)
 359         if not line.strip():
 360             continue
 361         if line.lstrip().startswith('#'):
 362             continue
 363
 364         try:
 365             event = Event.build(line)
 366         except ValueError as e:
 367             arg0 = 'Error at %s:%d: %s' % (fname, lineno, e.args[0])
 368             e.args = (arg0,) + e.args[1:]
 369             raise
 370
 371         # transform TCG-enabled events
 372         if "tcg" not in event.properties:
 373             events.append(event)
 374         else:
 375             event_trans = event.copy()
 376             event_trans.name += "_trans"
 377             event_trans.properties += ["tcg-trans"]
 378             event_trans.fmt = event.fmt[0]
 379             # ignore TCG arguments
 380             args_trans = []
 381             for atrans, aorig in zip(
 382                     event_trans.transform(tracetool.transform.TCG_2_HOST).args,
 383                     event.args):
 384                 if atrans == aorig:
 385                     args_trans.append(atrans)
 386             event_trans.args = Arguments(args_trans)
 387
 388             event_exec = event.copy()
 389             event_exec.name += "_exec"
 390             event_exec.properties += ["tcg-exec"]
 391             event_exec.fmt = event.fmt[1]
 392             event_exec.args = event_exec.args.transform(tracetool.transform.TCG_2_HOST)
 393
 394             new_event = [event_trans, event_exec]
 395             event.event_trans, event.event_exec = new_event
 396
 397             events.extend(new_event)
 398
 399     return events
 400
 401
 402 class TracetoolError (Exception):
 403     """Exception for calls to generate."""
 404     pass
 405
 406
 407 def try_import(mod_name, attr_name=None, attr_default=None):
 408     """Try to import a module and get an attribute from it.
 409
 410     Parameters
 411     ----------
 412     mod_name : str
 413         Module name.
 414     attr_name : str, optional
 415         Name of an attribute in the module.
 416     attr_default : optional
 417         Default value if the attribute does not exist in the module.
 418
 419     Returns
 420     -------
 421     A pair indicating whether the module could be imported and the module or
 422     object or attribute value.
 423     """
 424     try:
 425         module = __import__(mod_name, globals(), locals(), ["__package__"])
 426         if attr_name is None:
 427             return True, module
 428         return True, getattr(module, str(attr_name), attr_default)
 429     except ImportError:
 430         return False, None
 431
 432
 433 def generate(events, group, format, backends,
 434              binary=None, probe_prefix=None):
 435     """Generate the output for the given (format, backends) pair.
 436
 437     Parameters
 438     ----------
 439     events : list
 440         list of Event objects to generate for
 441     group: str
 442         Name of the tracing group
 443     format : str
 444         Output format name.
 445     backends : list
 446         Output backend names.
 447     binary : str or None
 448         See tracetool.backend.dtrace.BINARY.
 449     probe_prefix : str or None
 450         See tracetool.backend.dtrace.PROBEPREFIX.
 451     """
 452     # fix strange python error (UnboundLocalError tracetool)
 453     import tracetool
 454
 455     format = str(format)
 456     if len(format) is 0:
 457         raise TracetoolError("format not set")
 458     if not tracetool.format.exists(format):
 459         raise TracetoolError("unknown format: %s" % format)
 460
 461     if len(backends) is 0:
 462         raise TracetoolError("no backends specified")
 463     for backend in backends:
 464         if not tracetool.backend.exists(backend):
 465             raise TracetoolError("unknown backend: %s" % backend)
 466     backend = tracetool.backend.Wrapper(backends, format)
 467
 468     import tracetool.backend.dtrace
 469     tracetool.backend.dtrace.BINARY = binary
 470     tracetool.backend.dtrace.PROBEPREFIX = probe_prefix
 471
 472     tracetool.format.generate(events, format, backend, group)