xref: /openbmc/qemu/python/qemu/machine/machine.py (revision 514d3035)
1"""
2QEMU machine module:
3
4The machine module primarily provides the QEMUMachine class,
5which provides facilities for managing the lifetime of a QEMU VM.
6"""
7
8# Copyright (C) 2015-2016 Red Hat Inc.
9# Copyright (C) 2012 IBM Corp.
10#
11# Authors:
12#  Fam Zheng <famz@redhat.com>
13#
14# This work is licensed under the terms of the GNU GPL, version 2.  See
15# the COPYING file in the top-level directory.
16#
17# Based on qmp.py.
18#
19
20import errno
21from itertools import chain
22import locale
23import logging
24import os
25import shutil
26import signal
27import socket
28import subprocess
29import tempfile
30from types import TracebackType
31from typing import (
32    Any,
33    BinaryIO,
34    Dict,
35    List,
36    Optional,
37    Sequence,
38    Tuple,
39    Type,
40    TypeVar,
41)
42
43from qemu.qmp import SocketAddrT
44from qemu.qmp.legacy import (
45    QEMUMonitorProtocol,
46    QMPMessage,
47    QMPReturnValue,
48)
49
50from . import console_socket
51
52
53LOG = logging.getLogger(__name__)
54
55
56class QEMUMachineError(Exception):
57    """
58    Exception called when an error in QEMUMachine happens.
59    """
60
61
62class QEMUMachineAddDeviceError(QEMUMachineError):
63    """
64    Exception raised when a request to add a device can not be fulfilled
65
66    The failures are caused by limitations, lack of information or conflicting
67    requests on the QEMUMachine methods.  This exception does not represent
68    failures reported by the QEMU binary itself.
69    """
70
71
72class VMLaunchFailure(QEMUMachineError):
73    """
74    Exception raised when a VM launch was attempted, but failed.
75    """
76    def __init__(self, exitcode: Optional[int],
77                 command: str, output: Optional[str]):
78        super().__init__(exitcode, command, output)
79        self.exitcode = exitcode
80        self.command = command
81        self.output = output
82
83    def __str__(self) -> str:
84        ret = ''
85        if self.__cause__ is not None:
86            name = type(self.__cause__).__name__
87            reason = str(self.__cause__)
88            if reason:
89                ret += f"{name}: {reason}"
90            else:
91                ret += f"{name}"
92        ret += '\n'
93
94        if self.exitcode is not None:
95            ret += f"\tExit code: {self.exitcode}\n"
96        ret += f"\tCommand: {self.command}\n"
97        ret += f"\tOutput: {self.output}\n"
98        return ret
99
100
101class AbnormalShutdown(QEMUMachineError):
102    """
103    Exception raised when a graceful shutdown was requested, but not performed.
104    """
105
106
107_T = TypeVar('_T', bound='QEMUMachine')
108
109
110class QEMUMachine:
111    """
112    A QEMU VM.
113
114    Use this object as a context manager to ensure
115    the QEMU process terminates::
116
117        with VM(binary) as vm:
118            ...
119        # vm is guaranteed to be shut down here
120    """
121    # pylint: disable=too-many-instance-attributes, too-many-public-methods
122
123    def __init__(self,
124                 binary: str,
125                 args: Sequence[str] = (),
126                 wrapper: Sequence[str] = (),
127                 name: Optional[str] = None,
128                 base_temp_dir: str = "/var/tmp",
129                 monitor_address: Optional[SocketAddrT] = None,
130                 drain_console: bool = False,
131                 console_log: Optional[str] = None,
132                 log_dir: Optional[str] = None,
133                 qmp_timer: Optional[float] = 30):
134        '''
135        Initialize a QEMUMachine
136
137        @param binary: path to the qemu binary
138        @param args: list of extra arguments
139        @param wrapper: list of arguments used as prefix to qemu binary
140        @param name: prefix for socket and log file names (default: qemu-PID)
141        @param base_temp_dir: default location where temp files are created
142        @param monitor_address: address for QMP monitor
143        @param drain_console: (optional) True to drain console socket to buffer
144        @param console_log: (optional) path to console log file
145        @param log_dir: where to create and keep log files
146        @param qmp_timer: (optional) default QMP socket timeout
147        @note: Qemu process is not started until launch() is used.
148        '''
149        # pylint: disable=too-many-arguments
150
151        # Direct user configuration
152
153        self._binary = binary
154        self._args = list(args)
155        self._wrapper = wrapper
156        self._qmp_timer = qmp_timer
157
158        self._name = name or f"{id(self):x}"
159        self._sock_pair: Optional[Tuple[socket.socket, socket.socket]] = None
160        self._cons_sock_pair: Optional[
161            Tuple[socket.socket, socket.socket]] = None
162        self._temp_dir: Optional[str] = None
163        self._base_temp_dir = base_temp_dir
164        self._log_dir = log_dir
165
166        self._monitor_address = monitor_address
167
168        self._console_log_path = console_log
169        if self._console_log_path:
170            # In order to log the console, buffering needs to be enabled.
171            self._drain_console = True
172        else:
173            self._drain_console = drain_console
174
175        # Runstate
176        self._qemu_log_path: Optional[str] = None
177        self._qemu_log_file: Optional[BinaryIO] = None
178        self._popen: Optional['subprocess.Popen[bytes]'] = None
179        self._events: List[QMPMessage] = []
180        self._iolog: Optional[str] = None
181        self._qmp_set = True   # Enable QMP monitor by default.
182        self._qmp_connection: Optional[QEMUMonitorProtocol] = None
183        self._qemu_full_args: Tuple[str, ...] = ()
184        self._launched = False
185        self._machine: Optional[str] = None
186        self._console_index = 0
187        self._console_set = False
188        self._console_device_type: Optional[str] = None
189        self._console_socket: Optional[socket.socket] = None
190        self._console_file: Optional[socket.SocketIO] = None
191        self._remove_files: List[str] = []
192        self._user_killed = False
193        self._quit_issued = False
194
195    def __enter__(self: _T) -> _T:
196        return self
197
198    def __exit__(self,
199                 exc_type: Optional[Type[BaseException]],
200                 exc_val: Optional[BaseException],
201                 exc_tb: Optional[TracebackType]) -> None:
202        self.shutdown()
203
204    def add_monitor_null(self) -> None:
205        """
206        This can be used to add an unused monitor instance.
207        """
208        self._args.append('-monitor')
209        self._args.append('null')
210
211    def add_fd(self: _T, fd: int, fdset: int,
212               opaque: str, opts: str = '') -> _T:
213        """
214        Pass a file descriptor to the VM
215        """
216        options = ['fd=%d' % fd,
217                   'set=%d' % fdset,
218                   'opaque=%s' % opaque]
219        if opts:
220            options.append(opts)
221
222        # This did not exist before 3.4, but since then it is
223        # mandatory for our purpose
224        if hasattr(os, 'set_inheritable'):
225            os.set_inheritable(fd, True)
226
227        self._args.append('-add-fd')
228        self._args.append(','.join(options))
229        return self
230
231    def send_fd_scm(self, fd: Optional[int] = None,
232                    file_path: Optional[str] = None) -> int:
233        """
234        Send an fd or file_path to the remote via SCM_RIGHTS.
235
236        Exactly one of fd and file_path must be given.  If it is
237        file_path, the file will be opened read-only and the new file
238        descriptor will be sent to the remote.
239        """
240        if file_path is not None:
241            assert fd is None
242            with open(file_path, "rb") as passfile:
243                fd = passfile.fileno()
244                self._qmp.send_fd_scm(fd)
245        else:
246            assert fd is not None
247            self._qmp.send_fd_scm(fd)
248
249        return 0
250
251    @staticmethod
252    def _remove_if_exists(path: str) -> None:
253        """
254        Remove file object at path if it exists
255        """
256        try:
257            os.remove(path)
258        except OSError as exception:
259            if exception.errno == errno.ENOENT:
260                return
261            raise
262
263    def is_running(self) -> bool:
264        """Returns true if the VM is running."""
265        return self._popen is not None and self._popen.poll() is None
266
267    @property
268    def _subp(self) -> 'subprocess.Popen[bytes]':
269        if self._popen is None:
270            raise QEMUMachineError('Subprocess pipe not present')
271        return self._popen
272
273    def exitcode(self) -> Optional[int]:
274        """Returns the exit code if possible, or None."""
275        if self._popen is None:
276            return None
277        return self._popen.poll()
278
279    def get_pid(self) -> Optional[int]:
280        """Returns the PID of the running process, or None."""
281        if not self.is_running():
282            return None
283        return self._subp.pid
284
285    def _load_io_log(self) -> None:
286        # Assume that the output encoding of QEMU's terminal output is
287        # defined by our locale. If indeterminate, allow open() to fall
288        # back to the platform default.
289        _, encoding = locale.getlocale()
290        if self._qemu_log_path is not None:
291            with open(self._qemu_log_path, "r", encoding=encoding) as iolog:
292                self._iolog = iolog.read()
293
294    @property
295    def _base_args(self) -> List[str]:
296        args = ['-display', 'none', '-vga', 'none']
297
298        if self._qmp_set:
299            if self._sock_pair:
300                moncdev = f"socket,id=mon,fd={self._sock_pair[0].fileno()}"
301            elif isinstance(self._monitor_address, tuple):
302                moncdev = "socket,id=mon,host={},port={}".format(
303                    *self._monitor_address
304                )
305            else:
306                moncdev = f"socket,id=mon,path={self._monitor_address}"
307            args.extend(['-chardev', moncdev, '-mon',
308                         'chardev=mon,mode=control'])
309
310        if self._machine is not None:
311            args.extend(['-machine', self._machine])
312        for _ in range(self._console_index):
313            args.extend(['-serial', 'null'])
314        if self._console_set:
315            assert self._cons_sock_pair is not None
316            fd = self._cons_sock_pair[0].fileno()
317            chardev = f"socket,id=console,fd={fd}"
318            args.extend(['-chardev', chardev])
319            if self._console_device_type is None:
320                args.extend(['-serial', 'chardev:console'])
321            else:
322                device = '%s,chardev=console' % self._console_device_type
323                args.extend(['-device', device])
324        return args
325
326    @property
327    def args(self) -> List[str]:
328        """Returns the list of arguments given to the QEMU binary."""
329        return self._args
330
331    @property
332    def binary(self) -> str:
333        """Returns path to the QEMU binary"""
334        return self._binary
335
336    def _pre_launch(self) -> None:
337        if self._qmp_set:
338            sock = None
339            if self._monitor_address is None:
340                self._sock_pair = socket.socketpair()
341                os.set_inheritable(self._sock_pair[0].fileno(), True)
342                sock = self._sock_pair[1]
343            if isinstance(self._monitor_address, str):
344                self._remove_files.append(self._monitor_address)
345
346            sock_or_addr = self._monitor_address or sock
347            assert sock_or_addr is not None
348
349            self._qmp_connection = QEMUMonitorProtocol(
350                sock_or_addr,
351                server=bool(self._monitor_address),
352                nickname=self._name
353            )
354
355        if self._console_set:
356            self._cons_sock_pair = socket.socketpair()
357            os.set_inheritable(self._cons_sock_pair[0].fileno(), True)
358
359        # NOTE: Make sure any opened resources are *definitely* freed in
360        # _post_shutdown()!
361        # pylint: disable=consider-using-with
362        self._qemu_log_path = os.path.join(self.log_dir, self._name + ".log")
363        self._qemu_log_file = open(self._qemu_log_path, 'wb')
364
365        self._iolog = None
366        self._qemu_full_args = tuple(chain(
367            self._wrapper,
368            [self._binary],
369            self._base_args,
370            self._args
371        ))
372
373    def _post_launch(self) -> None:
374        if self._sock_pair:
375            self._sock_pair[0].close()
376        if self._cons_sock_pair:
377            self._cons_sock_pair[0].close()
378
379        if self._qmp_connection:
380            if self._sock_pair:
381                self._qmp.connect()
382            else:
383                self._qmp.accept(self._qmp_timer)
384
385    def _close_qemu_log_file(self) -> None:
386        if self._qemu_log_file is not None:
387            self._qemu_log_file.close()
388            self._qemu_log_file = None
389
390    def _post_shutdown(self) -> None:
391        """
392        Called to cleanup the VM instance after the process has exited.
393        May also be called after a failed launch.
394        """
395        LOG.debug("Cleaning up after VM process")
396        try:
397            self._close_qmp_connection()
398        except Exception as err:  # pylint: disable=broad-except
399            LOG.warning(
400                "Exception closing QMP connection: %s",
401                str(err) if str(err) else type(err).__name__
402            )
403        finally:
404            assert self._qmp_connection is None
405
406        if self._sock_pair:
407            self._sock_pair[0].close()
408            self._sock_pair[1].close()
409            self._sock_pair = None
410
411        self._close_qemu_log_file()
412
413        self._load_io_log()
414
415        self._qemu_log_path = None
416
417        if self._temp_dir is not None:
418            shutil.rmtree(self._temp_dir)
419            self._temp_dir = None
420
421        while len(self._remove_files) > 0:
422            self._remove_if_exists(self._remove_files.pop())
423
424        exitcode = self.exitcode()
425        if (exitcode is not None and exitcode < 0
426                and not (self._user_killed and exitcode == -signal.SIGKILL)):
427            msg = 'qemu received signal %i; command: "%s"'
428            if self._qemu_full_args:
429                command = ' '.join(self._qemu_full_args)
430            else:
431                command = ''
432            LOG.warning(msg, -int(exitcode), command)
433
434        self._quit_issued = False
435        self._user_killed = False
436        self._launched = False
437
438    def launch(self) -> None:
439        """
440        Launch the VM and make sure we cleanup and expose the
441        command line/output in case of exception
442        """
443
444        if self._launched:
445            raise QEMUMachineError('VM already launched')
446
447        try:
448            self._launch()
449        except BaseException as exc:
450            # We may have launched the process but it may
451            # have exited before we could connect via QMP.
452            # Assume the VM didn't launch or is exiting.
453            # If we don't wait for the process, exitcode() may still be
454            # 'None' by the time control is ceded back to the caller.
455            if self._launched:
456                self.wait()
457            else:
458                self._post_shutdown()
459
460            if isinstance(exc, Exception):
461                raise VMLaunchFailure(
462                    exitcode=self.exitcode(),
463                    command=' '.join(self._qemu_full_args),
464                    output=self._iolog
465                ) from exc
466
467            # Don't wrap 'BaseException'; doing so would downgrade
468            # that exception. However, we still want to clean up.
469            raise
470
471    def _launch(self) -> None:
472        """
473        Launch the VM and establish a QMP connection
474        """
475        self._pre_launch()
476        LOG.debug('VM launch command: %r', ' '.join(self._qemu_full_args))
477
478        # Cleaning up of this subprocess is guaranteed by _do_shutdown.
479        # pylint: disable=consider-using-with
480        self._popen = subprocess.Popen(self._qemu_full_args,
481                                       stdin=subprocess.DEVNULL,
482                                       stdout=self._qemu_log_file,
483                                       stderr=subprocess.STDOUT,
484                                       shell=False,
485                                       close_fds=False)
486        self._launched = True
487        self._post_launch()
488
489    def _close_qmp_connection(self) -> None:
490        """
491        Close the underlying QMP connection, if any.
492
493        Dutifully report errors that occurred while closing, but assume
494        that any error encountered indicates an abnormal termination
495        process and not a failure to close.
496        """
497        if self._qmp_connection is None:
498            return
499
500        try:
501            self._qmp.close()
502        except EOFError:
503            # EOF can occur as an Exception here when using the Async
504            # QMP backend. It indicates that the server closed the
505            # stream. If we successfully issued 'quit' at any point,
506            # then this was expected. If the remote went away without
507            # our permission, it's worth reporting that as an abnormal
508            # shutdown case.
509            if not (self._user_killed or self._quit_issued):
510                raise
511        finally:
512            self._qmp_connection = None
513
514    def _early_cleanup(self) -> None:
515        """
516        Perform any cleanup that needs to happen before the VM exits.
517
518        This method may be called twice upon shutdown, once each by soft
519        and hard shutdown in failover scenarios.
520        """
521        # If we keep the console socket open, we may deadlock waiting
522        # for QEMU to exit, while QEMU is waiting for the socket to
523        # become writable.
524        if self._console_file is not None:
525            LOG.debug("Closing console file")
526            self._console_file.close()
527            self._console_file = None
528
529        if self._console_socket is not None:
530            LOG.debug("Closing console socket")
531            self._console_socket.close()
532            self._console_socket = None
533
534        if self._cons_sock_pair:
535            self._cons_sock_pair[0].close()
536            self._cons_sock_pair[1].close()
537            self._cons_sock_pair = None
538
539    def _hard_shutdown(self) -> None:
540        """
541        Perform early cleanup, kill the VM, and wait for it to terminate.
542
543        :raise subprocess.Timeout: When timeout is exceeds 60 seconds
544            waiting for the QEMU process to terminate.
545        """
546        LOG.debug("Performing hard shutdown")
547        self._early_cleanup()
548        self._subp.kill()
549        self._subp.wait(timeout=60)
550
551    def _soft_shutdown(self, timeout: Optional[int]) -> None:
552        """
553        Perform early cleanup, attempt to gracefully shut down the VM, and wait
554        for it to terminate.
555
556        :param timeout: Timeout in seconds for graceful shutdown.
557                        A value of None is an infinite wait.
558
559        :raise ConnectionReset: On QMP communication errors
560        :raise subprocess.TimeoutExpired: When timeout is exceeded waiting for
561            the QEMU process to terminate.
562        """
563        LOG.debug("Attempting graceful termination")
564
565        self._early_cleanup()
566
567        if self._quit_issued:
568            LOG.debug(
569                "Anticipating QEMU termination due to prior 'quit' command, "
570                "or explicit call to wait()"
571            )
572        else:
573            LOG.debug("Politely asking QEMU to terminate")
574
575        if self._qmp_connection:
576            try:
577                if not self._quit_issued:
578                    # May raise ExecInterruptedError or StateError if the
579                    # connection dies or has *already* died.
580                    self.qmp('quit')
581            finally:
582                # Regardless, we want to quiesce the connection.
583                self._close_qmp_connection()
584        elif not self._quit_issued:
585            LOG.debug(
586                "Not anticipating QEMU quit and no QMP connection present, "
587                "issuing SIGTERM"
588            )
589            self._subp.terminate()
590
591        # May raise subprocess.TimeoutExpired
592        LOG.debug(
593            "Waiting (timeout=%s) for QEMU process (pid=%s) to terminate",
594            timeout, self._subp.pid
595        )
596        self._subp.wait(timeout=timeout)
597
598    def _do_shutdown(self, timeout: Optional[int]) -> None:
599        """
600        Attempt to shutdown the VM gracefully; fallback to a hard shutdown.
601
602        :param timeout: Timeout in seconds for graceful shutdown.
603                        A value of None is an infinite wait.
604
605        :raise AbnormalShutdown: When the VM could not be shut down gracefully.
606            The inner exception will likely be ConnectionReset or
607            subprocess.TimeoutExpired. In rare cases, non-graceful termination
608            may result in its own exceptions, likely subprocess.TimeoutExpired.
609        """
610        try:
611            self._soft_shutdown(timeout)
612        except Exception as exc:
613            if isinstance(exc, subprocess.TimeoutExpired):
614                LOG.debug("Timed out waiting for QEMU process to exit")
615            LOG.debug("Graceful shutdown failed", exc_info=True)
616            LOG.debug("Falling back to hard shutdown")
617            self._hard_shutdown()
618            raise AbnormalShutdown("Could not perform graceful shutdown") \
619                from exc
620
621    def shutdown(self,
622                 hard: bool = False,
623                 timeout: Optional[int] = 30) -> None:
624        """
625        Terminate the VM (gracefully if possible) and perform cleanup.
626        Cleanup will always be performed.
627
628        If the VM has not yet been launched, or shutdown(), wait(), or kill()
629        have already been called, this method does nothing.
630
631        :param hard: When true, do not attempt graceful shutdown, and
632                     suppress the SIGKILL warning log message.
633        :param timeout: Optional timeout in seconds for graceful shutdown.
634                        Default 30 seconds, A `None` value is an infinite wait.
635        """
636        if not self._launched:
637            return
638
639        LOG.debug("Shutting down VM appliance; timeout=%s", timeout)
640        if hard:
641            LOG.debug("Caller requests immediate termination of QEMU process.")
642
643        try:
644            if hard:
645                self._user_killed = True
646                self._hard_shutdown()
647            else:
648                self._do_shutdown(timeout)
649        finally:
650            self._post_shutdown()
651
652    def kill(self) -> None:
653        """
654        Terminate the VM forcefully, wait for it to exit, and perform cleanup.
655        """
656        self.shutdown(hard=True)
657
658    def wait(self, timeout: Optional[int] = 30) -> None:
659        """
660        Wait for the VM to power off and perform post-shutdown cleanup.
661
662        :param timeout: Optional timeout in seconds. Default 30 seconds.
663                        A value of `None` is an infinite wait.
664        """
665        self._quit_issued = True
666        self.shutdown(timeout=timeout)
667
668    def set_qmp_monitor(self, enabled: bool = True) -> None:
669        """
670        Set the QMP monitor.
671
672        @param enabled: if False, qmp monitor options will be removed from
673                        the base arguments of the resulting QEMU command
674                        line. Default is True.
675
676        .. note:: Call this function before launch().
677        """
678        self._qmp_set = enabled
679
680    @property
681    def _qmp(self) -> QEMUMonitorProtocol:
682        if self._qmp_connection is None:
683            raise QEMUMachineError("Attempt to access QMP with no connection")
684        return self._qmp_connection
685
686    @classmethod
687    def _qmp_args(cls, conv_keys: bool,
688                  args: Dict[str, Any]) -> Dict[str, object]:
689        if conv_keys:
690            return {k.replace('_', '-'): v for k, v in args.items()}
691
692        return args
693
694    def qmp(self, cmd: str,
695            args_dict: Optional[Dict[str, object]] = None,
696            conv_keys: Optional[bool] = None,
697            **args: Any) -> QMPMessage:
698        """
699        Invoke a QMP command and return the response dict
700        """
701        if args_dict is not None:
702            assert not args
703            assert conv_keys is None
704            args = args_dict
705            conv_keys = False
706
707        if conv_keys is None:
708            conv_keys = True
709
710        qmp_args = self._qmp_args(conv_keys, args)
711        ret = self._qmp.cmd_raw(cmd, args=qmp_args)
712        if cmd == 'quit' and 'error' not in ret and 'return' in ret:
713            self._quit_issued = True
714        return ret
715
716    def cmd(self, cmd: str,
717            args_dict: Optional[Dict[str, object]] = None,
718            conv_keys: Optional[bool] = None,
719            **args: Any) -> QMPReturnValue:
720        """
721        Invoke a QMP command.
722        On success return the response dict.
723        On failure raise an exception.
724        """
725        if args_dict is not None:
726            assert not args
727            assert conv_keys is None
728            args = args_dict
729            conv_keys = False
730
731        if conv_keys is None:
732            conv_keys = True
733
734        qmp_args = self._qmp_args(conv_keys, args)
735        ret = self._qmp.cmd(cmd, **qmp_args)
736        if cmd == 'quit':
737            self._quit_issued = True
738        return ret
739
740    def get_qmp_event(self, wait: bool = False) -> Optional[QMPMessage]:
741        """
742        Poll for one queued QMP events and return it
743        """
744        if self._events:
745            return self._events.pop(0)
746        return self._qmp.pull_event(wait=wait)
747
748    def get_qmp_events(self, wait: bool = False) -> List[QMPMessage]:
749        """
750        Poll for queued QMP events and return a list of dicts
751        """
752        events = self._qmp.get_events(wait=wait)
753        events.extend(self._events)
754        del self._events[:]
755        return events
756
757    @staticmethod
758    def event_match(event: Any, match: Optional[Any]) -> bool:
759        """
760        Check if an event matches optional match criteria.
761
762        The match criteria takes the form of a matching subdict. The event is
763        checked to be a superset of the subdict, recursively, with matching
764        values whenever the subdict values are not None.
765
766        This has a limitation that you cannot explicitly check for None values.
767
768        Examples, with the subdict queries on the left:
769         - None matches any object.
770         - {"foo": None} matches {"foo": {"bar": 1}}
771         - {"foo": None} matches {"foo": 5}
772         - {"foo": {"abc": None}} does not match {"foo": {"bar": 1}}
773         - {"foo": {"rab": 2}} matches {"foo": {"bar": 1, "rab": 2}}
774        """
775        if match is None:
776            return True
777
778        try:
779            for key in match:
780                if key in event:
781                    if not QEMUMachine.event_match(event[key], match[key]):
782                        return False
783                else:
784                    return False
785            return True
786        except TypeError:
787            # either match or event wasn't iterable (not a dict)
788            return bool(match == event)
789
790    def event_wait(self, name: str,
791                   timeout: float = 60.0,
792                   match: Optional[QMPMessage] = None) -> Optional[QMPMessage]:
793        """
794        event_wait waits for and returns a named event from QMP with a timeout.
795
796        name: The event to wait for.
797        timeout: QEMUMonitorProtocol.pull_event timeout parameter.
798        match: Optional match criteria. See event_match for details.
799        """
800        return self.events_wait([(name, match)], timeout)
801
802    def events_wait(self,
803                    events: Sequence[Tuple[str, Any]],
804                    timeout: float = 60.0) -> Optional[QMPMessage]:
805        """
806        events_wait waits for and returns a single named event from QMP.
807        In the case of multiple qualifying events, this function returns the
808        first one.
809
810        :param events: A sequence of (name, match_criteria) tuples.
811                       The match criteria are optional and may be None.
812                       See event_match for details.
813        :param timeout: Optional timeout, in seconds.
814                        See QEMUMonitorProtocol.pull_event.
815
816        :raise asyncio.TimeoutError:
817            If timeout was non-zero and no matching events were found.
818
819        :return: A QMP event matching the filter criteria.
820                 If timeout was 0 and no event matched, None.
821        """
822        def _match(event: QMPMessage) -> bool:
823            for name, match in events:
824                if event['event'] == name and self.event_match(event, match):
825                    return True
826            return False
827
828        event: Optional[QMPMessage]
829
830        # Search cached events
831        for event in self._events:
832            if _match(event):
833                self._events.remove(event)
834                return event
835
836        # Poll for new events
837        while True:
838            event = self._qmp.pull_event(wait=timeout)
839            if event is None:
840                # NB: None is only returned when timeout is false-ish.
841                # Timeouts raise asyncio.TimeoutError instead!
842                break
843            if _match(event):
844                return event
845            self._events.append(event)
846
847        return None
848
849    def get_log(self) -> Optional[str]:
850        """
851        After self.shutdown or failed qemu execution, this returns the output
852        of the qemu process.
853        """
854        return self._iolog
855
856    def add_args(self, *args: str) -> None:
857        """
858        Adds to the list of extra arguments to be given to the QEMU binary
859        """
860        self._args.extend(args)
861
862    def set_machine(self, machine_type: str) -> None:
863        """
864        Sets the machine type
865
866        If set, the machine type will be added to the base arguments
867        of the resulting QEMU command line.
868        """
869        self._machine = machine_type
870
871    def set_console(self,
872                    device_type: Optional[str] = None,
873                    console_index: int = 0) -> None:
874        """
875        Sets the device type for a console device
876
877        If set, the console device and a backing character device will
878        be added to the base arguments of the resulting QEMU command
879        line.
880
881        This is a convenience method that will either use the provided
882        device type, or default to a "-serial chardev:console" command
883        line argument.
884
885        The actual setting of command line arguments will be be done at
886        machine launch time, as it depends on the temporary directory
887        to be created.
888
889        @param device_type: the device type, such as "isa-serial".  If
890                            None is given (the default value) a "-serial
891                            chardev:console" command line argument will
892                            be used instead, resorting to the machine's
893                            default device type.
894        @param console_index: the index of the console device to use.
895                              If not zero, the command line will create
896                              'index - 1' consoles and connect them to
897                              the 'null' backing character device.
898        """
899        self._console_set = True
900        self._console_device_type = device_type
901        self._console_index = console_index
902
903    @property
904    def console_socket(self) -> socket.socket:
905        """
906        Returns a socket connected to the console
907        """
908        if self._console_socket is None:
909            LOG.debug("Opening console socket")
910            if not self._console_set:
911                raise QEMUMachineError(
912                    "Attempt to access console socket with no connection")
913            assert self._cons_sock_pair is not None
914            # os.dup() is used here for sock_fd because otherwise we'd
915            # have two rich python socket objects that would each try to
916            # close the same underlying fd when either one gets garbage
917            # collected.
918            self._console_socket = console_socket.ConsoleSocket(
919                sock_fd=os.dup(self._cons_sock_pair[1].fileno()),
920                file=self._console_log_path,
921                drain=self._drain_console)
922            self._cons_sock_pair[1].close()
923        return self._console_socket
924
925    @property
926    def console_file(self) -> socket.SocketIO:
927        """
928        Returns a file associated with the console socket
929        """
930        if self._console_file is None:
931            LOG.debug("Opening console file")
932            self._console_file = self.console_socket.makefile(mode='rb',
933                                                              buffering=0,
934                                                              encoding='utf-8')
935        return self._console_file
936
937    @property
938    def temp_dir(self) -> str:
939        """
940        Returns a temporary directory to be used for this machine
941        """
942        if self._temp_dir is None:
943            self._temp_dir = tempfile.mkdtemp(prefix="qemu-machine-",
944                                              dir=self._base_temp_dir)
945        return self._temp_dir
946
947    @property
948    def log_dir(self) -> str:
949        """
950        Returns a directory to be used for writing logs
951        """
952        if self._log_dir is None:
953            return self.temp_dir
954        return self._log_dir
955