xref: /openbmc/qemu/scripts/tracetool/__init__.py (revision ab9056ff) 
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    "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
73def 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
88class 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
187class 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        if fmt.endswith(r'\n"'):
281            raise ValueError("Event format must not end with a newline "
282                             "character")
283
284        if len(fmt_trans) > 0:
285            fmt = [fmt_trans, fmt]
286        args = Arguments.build(groups["args"])
287
288        if "tcg-trans" in props:
289            raise ValueError("Invalid property 'tcg-trans'")
290        if "tcg-exec" in props:
291            raise ValueError("Invalid property 'tcg-exec'")
292        if "tcg" not in props and not isinstance(fmt, str):
293            raise ValueError("Only events with 'tcg' property can have two format strings")
294        if "tcg" in props and isinstance(fmt, str):
295            raise ValueError("Events with 'tcg' property must have two format strings")
296
297        event = Event(name, props, fmt, args)
298
299        # add implicit arguments when using the 'vcpu' property
300        import tracetool.vcpu
301        event = tracetool.vcpu.transform_event(event)
302
303        return event
304
305    def __repr__(self):
306        """Evaluable string representation for this object."""
307        if isinstance(self.fmt, str):
308            fmt = self.fmt
309        else:
310            fmt = "%s, %s" % (self.fmt[0], self.fmt[1])
311        return "Event('%s %s(%s) %s')" % (" ".join(self.properties),
312                                          self.name,
313                                          self.args,
314                                          fmt)
315    # Star matching on PRI is dangerous as one might have multiple
316    # arguments with that format, hence the non-greedy version of it.
317    _FMT = re.compile("(%[\d\.]*\w+|%.*?PRI\S+)")
318
319    def formats(self):
320        """List conversion specifiers in the argument print format string."""
321        assert not isinstance(self.fmt, list)
322        return self._FMT.findall(self.fmt)
323
324    QEMU_TRACE               = "trace_%(name)s"
325    QEMU_TRACE_NOCHECK       = "_nocheck__" + QEMU_TRACE
326    QEMU_TRACE_TCG           = QEMU_TRACE + "_tcg"
327    QEMU_DSTATE              = "_TRACE_%(NAME)s_DSTATE"
328    QEMU_BACKEND_DSTATE      = "TRACE_%(NAME)s_BACKEND_DSTATE"
329    QEMU_EVENT               = "_TRACE_%(NAME)s_EVENT"
330
331    def api(self, fmt=None):
332        if fmt is None:
333            fmt = Event.QEMU_TRACE
334        return fmt % {"name": self.name, "NAME": self.name.upper()}
335
336    def transform(self, *trans):
337        """Return a new Event with transformed Arguments."""
338        return Event(self.name,
339                     list(self.properties),
340                     self.fmt,
341                     self.args.transform(*trans),
342                     self)
343
344
345def read_events(fobj, fname):
346    """Generate the output for the given (format, backends) pair.
347
348    Parameters
349    ----------
350    fobj : file
351        Event description file.
352    fname : str
353        Name of event file
354
355    Returns a list of Event objects
356    """
357
358    events = []
359    for lineno, line in enumerate(fobj, 1):
360        if line[-1] != '\n':
361            raise ValueError("%s does not end with a new line" % fname)
362        if not line.strip():
363            continue
364        if line.lstrip().startswith('#'):
365            continue
366
367        try:
368            event = Event.build(line)
369        except ValueError as e:
370            arg0 = 'Error at %s:%d: %s' % (fname, lineno, e.args[0])
371            e.args = (arg0,) + e.args[1:]
372            raise
373
374        # transform TCG-enabled events
375        if "tcg" not in event.properties:
376            events.append(event)
377        else:
378            event_trans = event.copy()
379            event_trans.name += "_trans"
380            event_trans.properties += ["tcg-trans"]
381            event_trans.fmt = event.fmt[0]
382            # ignore TCG arguments
383            args_trans = []
384            for atrans, aorig in zip(
385                    event_trans.transform(tracetool.transform.TCG_2_HOST).args,
386                    event.args):
387                if atrans == aorig:
388                    args_trans.append(atrans)
389            event_trans.args = Arguments(args_trans)
390
391            event_exec = event.copy()
392            event_exec.name += "_exec"
393            event_exec.properties += ["tcg-exec"]
394            event_exec.fmt = event.fmt[1]
395            event_exec.args = event_exec.args.transform(tracetool.transform.TCG_2_HOST)
396
397            new_event = [event_trans, event_exec]
398            event.event_trans, event.event_exec = new_event
399
400            events.extend(new_event)
401
402    return events
403
404
405class TracetoolError (Exception):
406    """Exception for calls to generate."""
407    pass
408
409
410def try_import(mod_name, attr_name=None, attr_default=None):
411    """Try to import a module and get an attribute from it.
412
413    Parameters
414    ----------
415    mod_name : str
416        Module name.
417    attr_name : str, optional
418        Name of an attribute in the module.
419    attr_default : optional
420        Default value if the attribute does not exist in the module.
421
422    Returns
423    -------
424    A pair indicating whether the module could be imported and the module or
425    object or attribute value.
426    """
427    try:
428        module = __import__(mod_name, globals(), locals(), ["__package__"])
429        if attr_name is None:
430            return True, module
431        return True, getattr(module, str(attr_name), attr_default)
432    except ImportError:
433        return False, None
434
435
436def generate(events, group, format, backends,
437             binary=None, probe_prefix=None):
438    """Generate the output for the given (format, backends) pair.
439
440    Parameters
441    ----------
442    events : list
443        list of Event objects to generate for
444    group: str
445        Name of the tracing group
446    format : str
447        Output format name.
448    backends : list
449        Output backend names.
450    binary : str or None
451        See tracetool.backend.dtrace.BINARY.
452    probe_prefix : str or None
453        See tracetool.backend.dtrace.PROBEPREFIX.
454    """
455    # fix strange python error (UnboundLocalError tracetool)
456    import tracetool
457
458    format = str(format)
459    if len(format) == 0:
460        raise TracetoolError("format not set")
461    if not tracetool.format.exists(format):
462        raise TracetoolError("unknown format: %s" % format)
463
464    if len(backends) == 0:
465        raise TracetoolError("no backends specified")
466    for backend in backends:
467        if not tracetool.backend.exists(backend):
468            raise TracetoolError("unknown backend: %s" % backend)
469    backend = tracetool.backend.Wrapper(backends, format)
470
471    import tracetool.backend.dtrace
472    tracetool.backend.dtrace.BINARY = binary
473    tracetool.backend.dtrace.PROBEPREFIX = probe_prefix
474
475    tracetool.format.generate(events, format, backend, group)
476