xref: /openbmc/qemu/scripts/tracetool/__init__.py (revision efade66d) 
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 re
16import sys
17import weakref
18
19import tracetool.format
20import tracetool.backend
21
22
23def error_write(*lines):
24    """Write a set of error lines."""
25    sys.stderr.writelines("\n".join(lines) + "\n")
26
27def error(*lines):
28    """Write a set of error lines and exit."""
29    error_write(*lines)
30    sys.exit(1)
31
32
33out_lineno = 1
34out_filename = '<none>'
35out_fobj = sys.stdout
36
37def out_open(filename):
38    global out_filename, out_fobj
39    out_filename = filename
40    out_fobj = open(filename, 'wt')
41
42def 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
68ALLOWED_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
91def validate_type(name):
92    bits = name.split(" ")
93    for bit in bits:
94        bit = re.sub(r"\*", "", 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
106class 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
193class 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(r"((?P<props>[\w\s]+)\s+)?"
214                      r"(?P<name>\w+)"
215                      r"\((?P<args>[^)]*)\)"
216                      r"\s*"
217                      r"(?:(?:(?P<fmt_trans>\".+),)?\s*(?P<fmt>\".+))?"
218                      r"\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(r"(%[\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
349def 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
383class TracetoolError (Exception):
384    """Exception for calls to generate."""
385    pass
386
387
388def 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
414def 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)
454