scripts/tracetool/__init__.py

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