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