hw: qdev: fix error in comment
[qemu/kevin.git] / scripts / tracetool / __init__.py
blob0e3c9e146cc72e290ac80bd850762a881c8da781
1 #!/usr/bin/env python
2 # -*- coding: utf-8 -*-
4 """
5 Machinery for generating tracing-related intermediate files.
6 """
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"
12 __maintainer__ = "Stefan Hajnoczi"
13 __email__ = "stefanha@linux.vnet.ibm.com"
16 import re
17 import sys
18 import weakref
20 import tracetool.format
21 import tracetool.backend
22 import tracetool.transform
25 def error_write(*lines):
26 """Write a set of error lines."""
27 sys.stderr.writelines("\n".join(lines) + "\n")
29 def error(*lines):
30 """Write a set of error lines and exit."""
31 error_write(*lines)
32 sys.exit(1)
35 def out(*lines, **kwargs):
36 """Write a set of output lines.
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")
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",
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)
88 class Arguments:
89 """Event arguments description."""
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)
105 def copy(self):
106 """Create a new copy."""
107 return Arguments(list(self._args))
109 @staticmethod
110 def build(arg_str):
111 """Build and Arguments instance from an argument string.
113 Parameters
114 ----------
115 arg_str : str
116 String describing the event arguments.
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
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)
133 validate_type(arg_type)
134 res.append((arg_type, identifier))
135 return Arguments(res)
137 def __getitem__(self, index):
138 if isinstance(index, slice):
139 return Arguments(self._args[index])
140 else:
141 return self._args[index]
143 def __iter__(self):
144 """Iterate over the (type, name) pairs."""
145 return iter(self._args)
147 def __len__(self):
148 """Number of arguments."""
149 return len(self._args)
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 ])
158 def __repr__(self):
159 """Evaluable string representation for this object."""
160 return "Arguments(\"%s\")" % str(self)
162 def names(self):
163 """List of argument names."""
164 return [ name for _, name in self._args ]
166 def types(self):
167 """List of argument types."""
168 return [ type_ for type_, _ in self._args ]
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]
174 def transform(self, *trans):
175 """Return a new Arguments instance with transformed types.
177 The types in the resulting Arguments instance are transformed according
178 to tracetool.transform.transform_type.
180 res = []
181 for type_, name in self._args:
182 res.append((tracetool.transform.transform_type(type_, *trans),
183 name))
184 return Arguments(res)
187 class Event(object):
188 """Event description.
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.
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*")
210 _VALID_PROPS = set(["disable", "tcg", "tcg-trans", "tcg-exec", "vcpu"])
212 def __init__(self, name, props, fmt, args, orig=None,
213 event_trans=None, event_exec=None):
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).
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
240 if len(args) > 10:
241 raise ValueError("Event '%s' has more than maximum permitted "
242 "argument count" % name)
244 if orig is None:
245 self.original = weakref.ref(self)
246 else:
247 self.original = orig
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
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)
260 @staticmethod
261 def build(line_str):
262 """Build an Event instance from a string.
264 Parameters
265 ----------
266 line_str : str
267 Line describing the event.
269 m = Event._CRE.match(line_str)
270 assert m is not None
271 groups = m.groupdict('')
273 name = groups["name"]
274 props = groups["props"].split()
275 fmt = groups["fmt"]
276 fmt_trans = groups["fmt_trans"]
277 if len(fmt_trans) > 0:
278 fmt = [fmt_trans, fmt]
279 args = Arguments.build(groups["args"])
281 if "tcg-trans" in props:
282 raise ValueError("Invalid property 'tcg-trans'")
283 if "tcg-exec" in props:
284 raise ValueError("Invalid property 'tcg-exec'")
285 if "tcg" not in props and not isinstance(fmt, str):
286 raise ValueError("Only events with 'tcg' property can have two format strings")
287 if "tcg" in props and isinstance(fmt, str):
288 raise ValueError("Events with 'tcg' property must have two format strings")
290 event = Event(name, props, fmt, args)
292 # add implicit arguments when using the 'vcpu' property
293 import tracetool.vcpu
294 event = tracetool.vcpu.transform_event(event)
296 return event
298 def __repr__(self):
299 """Evaluable string representation for this object."""
300 if isinstance(self.fmt, str):
301 fmt = self.fmt
302 else:
303 fmt = "%s, %s" % (self.fmt[0], self.fmt[1])
304 return "Event('%s %s(%s) %s')" % (" ".join(self.properties),
305 self.name,
306 self.args,
307 fmt)
308 # Star matching on PRI is dangerous as one might have multiple
309 # arguments with that format, hence the non-greedy version of it.
310 _FMT = re.compile("(%[\d\.]*\w+|%.*?PRI\S+)")
312 def formats(self):
313 """List conversion specifiers in the argument print format string."""
314 assert not isinstance(self.fmt, list)
315 return self._FMT.findall(self.fmt)
317 QEMU_TRACE = "trace_%(name)s"
318 QEMU_TRACE_NOCHECK = "_nocheck__" + QEMU_TRACE
319 QEMU_TRACE_TCG = QEMU_TRACE + "_tcg"
320 QEMU_DSTATE = "_TRACE_%(NAME)s_DSTATE"
321 QEMU_BACKEND_DSTATE = "TRACE_%(NAME)s_BACKEND_DSTATE"
322 QEMU_EVENT = "_TRACE_%(NAME)s_EVENT"
324 def api(self, fmt=None):
325 if fmt is None:
326 fmt = Event.QEMU_TRACE
327 return fmt % {"name": self.name, "NAME": self.name.upper()}
329 def transform(self, *trans):
330 """Return a new Event with transformed Arguments."""
331 return Event(self.name,
332 list(self.properties),
333 self.fmt,
334 self.args.transform(*trans),
335 self)
338 def read_events(fobj, fname):
339 """Generate the output for the given (format, backends) pair.
341 Parameters
342 ----------
343 fobj : file
344 Event description file.
345 fname : str
346 Name of event file
348 Returns a list of Event objects
351 events = []
352 for lineno, line in enumerate(fobj, 1):
353 if not line.strip():
354 continue
355 if line.lstrip().startswith('#'):
356 continue
358 try:
359 event = Event.build(line)
360 except ValueError as e:
361 arg0 = 'Error at %s:%d: %s' % (fname, lineno, e.args[0])
362 e.args = (arg0,) + e.args[1:]
363 raise
365 # transform TCG-enabled events
366 if "tcg" not in event.properties:
367 events.append(event)
368 else:
369 event_trans = event.copy()
370 event_trans.name += "_trans"
371 event_trans.properties += ["tcg-trans"]
372 event_trans.fmt = event.fmt[0]
373 # ignore TCG arguments
374 args_trans = []
375 for atrans, aorig in zip(
376 event_trans.transform(tracetool.transform.TCG_2_HOST).args,
377 event.args):
378 if atrans == aorig:
379 args_trans.append(atrans)
380 event_trans.args = Arguments(args_trans)
382 event_exec = event.copy()
383 event_exec.name += "_exec"
384 event_exec.properties += ["tcg-exec"]
385 event_exec.fmt = event.fmt[1]
386 event_exec.args = event_exec.args.transform(tracetool.transform.TCG_2_HOST)
388 new_event = [event_trans, event_exec]
389 event.event_trans, event.event_exec = new_event
391 events.extend(new_event)
393 return events
396 class TracetoolError (Exception):
397 """Exception for calls to generate."""
398 pass
401 def try_import(mod_name, attr_name=None, attr_default=None):
402 """Try to import a module and get an attribute from it.
404 Parameters
405 ----------
406 mod_name : str
407 Module name.
408 attr_name : str, optional
409 Name of an attribute in the module.
410 attr_default : optional
411 Default value if the attribute does not exist in the module.
413 Returns
414 -------
415 A pair indicating whether the module could be imported and the module or
416 object or attribute value.
418 try:
419 module = __import__(mod_name, globals(), locals(), ["__package__"])
420 if attr_name is None:
421 return True, module
422 return True, getattr(module, str(attr_name), attr_default)
423 except ImportError:
424 return False, None
427 def generate(events, group, format, backends,
428 binary=None, probe_prefix=None):
429 """Generate the output for the given (format, backends) pair.
431 Parameters
432 ----------
433 events : list
434 list of Event objects to generate for
435 group: str
436 Name of the tracing group
437 format : str
438 Output format name.
439 backends : list
440 Output backend names.
441 binary : str or None
442 See tracetool.backend.dtrace.BINARY.
443 probe_prefix : str or None
444 See tracetool.backend.dtrace.PROBEPREFIX.
446 # fix strange python error (UnboundLocalError tracetool)
447 import tracetool
449 format = str(format)
450 if len(format) is 0:
451 raise TracetoolError("format not set")
452 if not tracetool.format.exists(format):
453 raise TracetoolError("unknown format: %s" % format)
455 if len(backends) is 0:
456 raise TracetoolError("no backends specified")
457 for backend in backends:
458 if not tracetool.backend.exists(backend):
459 raise TracetoolError("unknown backend: %s" % backend)
460 backend = tracetool.backend.Wrapper(backends, format)
462 import tracetool.backend.dtrace
463 tracetool.backend.dtrace.BINARY = binary
464 tracetool.backend.dtrace.PROBEPREFIX = probe_prefix
466 tracetool.format.generate(events, format, backend, group)