python/qemu/machine.py

   1 """
   2 QEMU machine module:
   3
   4 The machine module primarily provides the QEMUMachine class,
   5 which 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
  20 import errno
  21 import logging
  22 import os
  23 import subprocess
  24 import shutil
  25 import socket
  26 import tempfile
  27 from typing import Optional, Type
  28 from types import TracebackType
  29 from qemu.console_socket import ConsoleSocket
  30
  31 from . import qmp
  32
  33 LOG = logging.getLogger(__name__)
  34
  35
  36 class QEMUMachineError(Exception):
  37     """
  38     Exception called when an error in QEMUMachine happens.
  39     """
  40
  41
  42 class QEMUMachineAddDeviceError(QEMUMachineError):
  43     """
  44     Exception raised when a request to add a device can not be fulfilled
  45
  46     The failures are caused by limitations, lack of information or conflicting
  47     requests on the QEMUMachine methods.  This exception does not represent
  48     failures reported by the QEMU binary itself.
  49     """
  50
  51
  52 class MonitorResponseError(qmp.QMPError):
  53     """
  54     Represents erroneous QMP monitor reply
  55     """
  56     def __init__(self, reply):
  57         try:
  58             desc = reply["error"]["desc"]
  59         except KeyError:
  60             desc = reply
  61         super().__init__(desc)
  62         self.reply = reply
  63
  64
  65 class QEMUMachine:
  66     """
  67     A QEMU VM
  68
  69     Use this object as a context manager to ensure
  70     the QEMU process terminates::
  71
  72         with VM(binary) as vm:
  73             ...
  74         # vm is guaranteed to be shut down here
  75     """
  76
  77     def __init__(self, binary, args=None, wrapper=None, name=None,
  78                  test_dir="/var/tmp", monitor_address=None,
  79                  socket_scm_helper=None, sock_dir=None,
  80                  drain_console=False, console_log=None):
  81         '''
  82         Initialize a QEMUMachine
  83
  84         @param binary: path to the qemu binary
  85         @param args: list of extra arguments
  86         @param wrapper: list of arguments used as prefix to qemu binary
  87         @param name: prefix for socket and log file names (default: qemu-PID)
  88         @param test_dir: where to create socket and log file
  89         @param monitor_address: address for QMP monitor
  90         @param socket_scm_helper: helper program, required for send_fd_scm()
  91         @param sock_dir: where to create socket (overrides test_dir for sock)
  92         @param console_log: (optional) path to console log file
  93         @param drain_console: (optional) True to drain console socket to buffer
  94         @note: Qemu process is not started until launch() is used.
  95         '''
  96         if args is None:
  97             args = []
  98         if wrapper is None:
  99             wrapper = []
 100         if name is None:
 101             name = "qemu-%d" % os.getpid()
 102         if sock_dir is None:
 103             sock_dir = test_dir
 104         self._name = name
 105         self._monitor_address = monitor_address
 106         self._vm_monitor = None
 107         self._qemu_log_path = None
 108         self._qemu_log_file = None
 109         self._popen = None
 110         self._binary = binary
 111         self._args = list(args)     # Force copy args in case we modify them
 112         self._wrapper = wrapper
 113         self._events = []
 114         self._iolog = None
 115         self._socket_scm_helper = socket_scm_helper
 116         self._qmp_set = True   # Enable QMP monitor by default.
 117         self._qmp = None
 118         self._qemu_full_args = None
 119         self._test_dir = test_dir
 120         self._temp_dir = None
 121         self._sock_dir = sock_dir
 122         self._launched = False
 123         self._machine = None
 124         self._console_index = 0
 125         self._console_set = False
 126         self._console_device_type = None
 127         self._console_address = None
 128         self._console_socket = None
 129         self._remove_files = []
 130         self._console_log_path = console_log
 131         if self._console_log_path:
 132             # In order to log the console, buffering needs to be enabled.
 133             self._drain_console = True
 134         else:
 135             self._drain_console = drain_console
 136
 137     def __enter__(self):
 138         return self
 139
 140     def __exit__(self,
 141                  exc_type: Optional[Type[BaseException]],
 142                  exc_val: Optional[BaseException],
 143                  exc_tb: Optional[TracebackType]) -> None:
 144         self.shutdown()
 145
 146     def add_monitor_null(self):
 147         """
 148         This can be used to add an unused monitor instance.
 149         """
 150         self._args.append('-monitor')
 151         self._args.append('null')
 152
 153     def add_fd(self, fd, fdset, opaque, opts=''):
 154         """
 155         Pass a file descriptor to the VM
 156         """
 157         options = ['fd=%d' % fd,
 158                    'set=%d' % fdset,
 159                    'opaque=%s' % opaque]
 160         if opts:
 161             options.append(opts)
 162
 163         # This did not exist before 3.4, but since then it is
 164         # mandatory for our purpose
 165         if hasattr(os, 'set_inheritable'):
 166             os.set_inheritable(fd, True)
 167
 168         self._args.append('-add-fd')
 169         self._args.append(','.join(options))
 170         return self
 171
 172     def send_fd_scm(self, fd=None, file_path=None):
 173         """
 174         Send an fd or file_path to socket_scm_helper.
 175
 176         Exactly one of fd and file_path must be given.
 177         If it is file_path, the helper will open that file and pass its own fd.
 178         """
 179         # In iotest.py, the qmp should always use unix socket.
 180         assert self._qmp.is_scm_available()
 181         if self._socket_scm_helper is None:
 182             raise QEMUMachineError("No path to socket_scm_helper set")
 183         if not os.path.exists(self._socket_scm_helper):
 184             raise QEMUMachineError("%s does not exist" %
 185                                    self._socket_scm_helper)
 186
 187         # This did not exist before 3.4, but since then it is
 188         # mandatory for our purpose
 189         if hasattr(os, 'set_inheritable'):
 190             os.set_inheritable(self._qmp.get_sock_fd(), True)
 191             if fd is not None:
 192                 os.set_inheritable(fd, True)
 193
 194         fd_param = ["%s" % self._socket_scm_helper,
 195                     "%d" % self._qmp.get_sock_fd()]
 196
 197         if file_path is not None:
 198             assert fd is None
 199             fd_param.append(file_path)
 200         else:
 201             assert fd is not None
 202             fd_param.append(str(fd))
 203
 204         devnull = open(os.path.devnull, 'rb')
 205         proc = subprocess.Popen(
 206             fd_param, stdin=devnull, stdout=subprocess.PIPE,
 207             stderr=subprocess.STDOUT, close_fds=False
 208         )
 209         output = proc.communicate()[0]
 210         if output:
 211             LOG.debug(output)
 212
 213         return proc.returncode
 214
 215     @staticmethod
 216     def _remove_if_exists(path):
 217         """
 218         Remove file object at path if it exists
 219         """
 220         try:
 221             os.remove(path)
 222         except OSError as exception:
 223             if exception.errno == errno.ENOENT:
 224                 return
 225             raise
 226
 227     def is_running(self):
 228         """Returns true if the VM is running."""
 229         return self._popen is not None and self._popen.poll() is None
 230
 231     def exitcode(self):
 232         """Returns the exit code if possible, or None."""
 233         if self._popen is None:
 234             return None
 235         return self._popen.poll()
 236
 237     def get_pid(self):
 238         """Returns the PID of the running process, or None."""
 239         if not self.is_running():
 240             return None
 241         return self._popen.pid
 242
 243     def _load_io_log(self):
 244         if self._qemu_log_path is not None:
 245             with open(self._qemu_log_path, "r") as iolog:
 246                 self._iolog = iolog.read()
 247
 248     def _base_args(self):
 249         args = ['-display', 'none', '-vga', 'none']
 250         if self._qmp_set:
 251             if isinstance(self._monitor_address, tuple):
 252                 moncdev = "socket,id=mon,host=%s,port=%s" % (
 253                     self._monitor_address[0],
 254                     self._monitor_address[1])
 255             else:
 256                 moncdev = 'socket,id=mon,path=%s' % self._vm_monitor
 257             args.extend(['-chardev', moncdev, '-mon',
 258                          'chardev=mon,mode=control'])
 259         if self._machine is not None:
 260             args.extend(['-machine', self._machine])
 261         for _ in range(self._console_index):
 262             args.extend(['-serial', 'null'])
 263         if self._console_set:
 264             self._console_address = os.path.join(self._sock_dir,
 265                                                  self._name + "-console.sock")
 266             self._remove_files.append(self._console_address)
 267             chardev = ('socket,id=console,path=%s,server,nowait' %
 268                        self._console_address)
 269             args.extend(['-chardev', chardev])
 270             if self._console_device_type is None:
 271                 args.extend(['-serial', 'chardev:console'])
 272             else:
 273                 device = '%s,chardev=console' % self._console_device_type
 274                 args.extend(['-device', device])
 275         return args
 276
 277     def _pre_launch(self):
 278         self._temp_dir = tempfile.mkdtemp(dir=self._test_dir)
 279         self._qemu_log_path = os.path.join(self._temp_dir, self._name + ".log")
 280         self._qemu_log_file = open(self._qemu_log_path, 'wb')
 281
 282         if self._qmp_set:
 283             if self._monitor_address is not None:
 284                 self._vm_monitor = self._monitor_address
 285             else:
 286                 self._vm_monitor = os.path.join(self._sock_dir,
 287                                                 self._name + "-monitor.sock")
 288                 self._remove_files.append(self._vm_monitor)
 289             self._qmp = qmp.QEMUMonitorProtocol(self._vm_monitor, server=True,
 290                                                 nickname=self._name)
 291
 292     def _post_launch(self):
 293         if self._qmp:
 294             self._qmp.accept()
 295
 296     def _post_shutdown(self):
 297         if self._qemu_log_file is not None:
 298             self._qemu_log_file.close()
 299             self._qemu_log_file = None
 300
 301         self._qemu_log_path = None
 302
 303         if self._temp_dir is not None:
 304             shutil.rmtree(self._temp_dir)
 305             self._temp_dir = None
 306
 307         while len(self._remove_files) > 0:
 308             self._remove_if_exists(self._remove_files.pop())
 309
 310     def launch(self):
 311         """
 312         Launch the VM and make sure we cleanup and expose the
 313         command line/output in case of exception
 314         """
 315
 316         if self._launched:
 317             raise QEMUMachineError('VM already launched')
 318
 319         self._iolog = None
 320         self._qemu_full_args = None
 321         try:
 322             self._launch()
 323             self._launched = True
 324         except:
 325             self.shutdown()
 326
 327             LOG.debug('Error launching VM')
 328             if self._qemu_full_args:
 329                 LOG.debug('Command: %r', ' '.join(self._qemu_full_args))
 330             if self._iolog:
 331                 LOG.debug('Output: %r', self._iolog)
 332             raise
 333
 334     def _launch(self):
 335         """
 336         Launch the VM and establish a QMP connection
 337         """
 338         devnull = open(os.path.devnull, 'rb')
 339         self._pre_launch()
 340         self._qemu_full_args = (self._wrapper + [self._binary] +
 341                                 self._base_args() + self._args)
 342         LOG.debug('VM launch command: %r', ' '.join(self._qemu_full_args))
 343         self._popen = subprocess.Popen(self._qemu_full_args,
 344                                        stdin=devnull,
 345                                        stdout=self._qemu_log_file,
 346                                        stderr=subprocess.STDOUT,
 347                                        shell=False,
 348                                        close_fds=False)
 349         self._post_launch()
 350
 351     def wait(self):
 352         """
 353         Wait for the VM to power off
 354         """
 355         self._popen.wait()
 356         if self._qmp:
 357             self._qmp.close()
 358         self._load_io_log()
 359         self._post_shutdown()
 360
 361     def shutdown(self, has_quit=False, hard=False):
 362         """
 363         Terminate the VM and clean up
 364         """
 365         # If we keep the console socket open, we may deadlock waiting
 366         # for QEMU to exit, while QEMU is waiting for the socket to
 367         # become writeable.
 368         if self._console_socket is not None:
 369             self._console_socket.close()
 370             self._console_socket = None
 371
 372         if self.is_running():
 373             if hard:
 374                 self._popen.kill()
 375             elif self._qmp:
 376                 try:
 377                     if not has_quit:
 378                         self._qmp.cmd('quit')
 379                     self._qmp.close()
 380                     self._popen.wait(timeout=3)
 381                 except:
 382                     self._popen.kill()
 383             self._popen.wait()
 384
 385         self._load_io_log()
 386         self._post_shutdown()
 387
 388         exitcode = self.exitcode()
 389         if exitcode is not None and exitcode < 0 and \
 390                 not (exitcode == -9 and hard):
 391             msg = 'qemu received signal %i: %s'
 392             if self._qemu_full_args:
 393                 command = ' '.join(self._qemu_full_args)
 394             else:
 395                 command = ''
 396             LOG.warning(msg, -int(exitcode), command)
 397
 398         self._launched = False
 399
 400     def kill(self):
 401         self.shutdown(hard=True)
 402
 403     def set_qmp_monitor(self, enabled=True):
 404         """
 405         Set the QMP monitor.
 406
 407         @param enabled: if False, qmp monitor options will be removed from
 408                         the base arguments of the resulting QEMU command
 409                         line. Default is True.
 410         @note: call this function before launch().
 411         """
 412         if enabled:
 413             self._qmp_set = True
 414         else:
 415             self._qmp_set = False
 416             self._qmp = None
 417
 418     def qmp(self, cmd, conv_keys=True, **args):
 419         """
 420         Invoke a QMP command and return the response dict
 421         """
 422         qmp_args = dict()
 423         for key, value in args.items():
 424             if conv_keys:
 425                 qmp_args[key.replace('_', '-')] = value
 426             else:
 427                 qmp_args[key] = value
 428
 429         return self._qmp.cmd(cmd, args=qmp_args)
 430
 431     def command(self, cmd, conv_keys=True, **args):
 432         """
 433         Invoke a QMP command.
 434         On success return the response dict.
 435         On failure raise an exception.
 436         """
 437         reply = self.qmp(cmd, conv_keys, **args)
 438         if reply is None:
 439             raise qmp.QMPError("Monitor is closed")
 440         if "error" in reply:
 441             raise MonitorResponseError(reply)
 442         return reply["return"]
 443
 444     def get_qmp_event(self, wait=False):
 445         """
 446         Poll for one queued QMP events and return it
 447         """
 448         if self._events:
 449             return self._events.pop(0)
 450         return self._qmp.pull_event(wait=wait)
 451
 452     def get_qmp_events(self, wait=False):
 453         """
 454         Poll for queued QMP events and return a list of dicts
 455         """
 456         events = self._qmp.get_events(wait=wait)
 457         events.extend(self._events)
 458         del self._events[:]
 459         self._qmp.clear_events()
 460         return events
 461
 462     @staticmethod
 463     def event_match(event, match=None):
 464         """
 465         Check if an event matches optional match criteria.
 466
 467         The match criteria takes the form of a matching subdict. The event is
 468         checked to be a superset of the subdict, recursively, with matching
 469         values whenever the subdict values are not None.
 470
 471         This has a limitation that you cannot explicitly check for None values.
 472
 473         Examples, with the subdict queries on the left:
 474          - None matches any object.
 475          - {"foo": None} matches {"foo": {"bar": 1}}
 476          - {"foo": None} matches {"foo": 5}
 477          - {"foo": {"abc": None}} does not match {"foo": {"bar": 1}}
 478          - {"foo": {"rab": 2}} matches {"foo": {"bar": 1, "rab": 2}}
 479         """
 480         if match is None:
 481             return True
 482
 483         try:
 484             for key in match:
 485                 if key in event:
 486                     if not QEMUMachine.event_match(event[key], match[key]):
 487                         return False
 488                 else:
 489                     return False
 490             return True
 491         except TypeError:
 492             # either match or event wasn't iterable (not a dict)
 493             return match == event
 494
 495     def event_wait(self, name, timeout=60.0, match=None):
 496         """
 497         event_wait waits for and returns a named event from QMP with a timeout.
 498
 499         name: The event to wait for.
 500         timeout: QEMUMonitorProtocol.pull_event timeout parameter.
 501         match: Optional match criteria. See event_match for details.
 502         """
 503         return self.events_wait([(name, match)], timeout)
 504
 505     def events_wait(self, events, timeout=60.0):
 506         """
 507         events_wait waits for and returns a named event
 508         from QMP with a timeout.
 509
 510         events: a sequence of (name, match_criteria) tuples.
 511                 The match criteria are optional and may be None.
 512                 See event_match for details.
 513         timeout: QEMUMonitorProtocol.pull_event timeout parameter.
 514         """
 515         def _match(event):
 516             for name, match in events:
 517                 if event['event'] == name and self.event_match(event, match):
 518                     return True
 519             return False
 520
 521         # Search cached events
 522         for event in self._events:
 523             if _match(event):
 524                 self._events.remove(event)
 525                 return event
 526
 527         # Poll for new events
 528         while True:
 529             event = self._qmp.pull_event(wait=timeout)
 530             if _match(event):
 531                 return event
 532             self._events.append(event)
 533
 534         return None
 535
 536     def get_log(self):
 537         """
 538         After self.shutdown or failed qemu execution, this returns the output
 539         of the qemu process.
 540         """
 541         return self._iolog
 542
 543     def add_args(self, *args):
 544         """
 545         Adds to the list of extra arguments to be given to the QEMU binary
 546         """
 547         self._args.extend(args)
 548
 549     def set_machine(self, machine_type):
 550         """
 551         Sets the machine type
 552
 553         If set, the machine type will be added to the base arguments
 554         of the resulting QEMU command line.
 555         """
 556         self._machine = machine_type
 557
 558     def set_console(self, device_type=None, console_index=0):
 559         """
 560         Sets the device type for a console device
 561
 562         If set, the console device and a backing character device will
 563         be added to the base arguments of the resulting QEMU command
 564         line.
 565
 566         This is a convenience method that will either use the provided
 567         device type, or default to a "-serial chardev:console" command
 568         line argument.
 569
 570         The actual setting of command line arguments will be be done at
 571         machine launch time, as it depends on the temporary directory
 572         to be created.
 573
 574         @param device_type: the device type, such as "isa-serial".  If
 575                             None is given (the default value) a "-serial
 576                             chardev:console" command line argument will
 577                             be used instead, resorting to the machine's
 578                             default device type.
 579         @param console_index: the index of the console device to use.
 580                               If not zero, the command line will create
 581                               'index - 1' consoles and connect them to
 582                               the 'null' backing character device.
 583         """
 584         self._console_set = True
 585         self._console_device_type = device_type
 586         self._console_index = console_index
 587
 588     @property
 589     def console_socket(self):
 590         """
 591         Returns a socket connected to the console
 592         """
 593         if self._console_socket is None:
 594             if self._drain_console:
 595                 self._console_socket = ConsoleSocket(self._console_address,
 596                                                     file=self._console_log_path)
 597             else:
 598                 self._console_socket = socket.socket(socket.AF_UNIX,
 599                                                      socket.SOCK_STREAM)
 600                 self._console_socket.connect(self._console_address)
 601         return self._console_socket