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