LXR qemu/scripts/qmp/qmp-shell

   1#!/usr/bin/python
   2#
   3# Low-level QEMU shell on top of QMP.
   4#
   5# Copyright (C) 2009, 2010 Red Hat Inc.
   6#
   7# Authors:
   8#  Luiz Capitulino <lcapitulino@redhat.com>
   9#
  10# This work is licensed under the terms of the GNU GPL, version 2.  See
  11# the COPYING file in the top-level directory.
  12#
  13# Usage:
  14#
  15# Start QEMU with:
  16#
  17# # qemu [...] -qmp unix:./qmp-sock,server
  18#
  19# Run the shell:
  20#
  21# $ qmp-shell ./qmp-sock
  22#
  23# Commands have the following format:
  24#
  25#    < command-name > [ arg-name1=arg1 ] ... [ arg-nameN=argN ]
  26#
  27# For example:
  28#
  29# (QEMU) device_add driver=e1000 id=net1
  30# {u'return': {}}
  31# (QEMU)
  32#
  33# key=value pairs also support Python or JSON object literal subset notations,
  34# without spaces. Dictionaries/objects {} are supported as are arrays [].
  35#
  36#    example-command arg-name1={'key':'value','obj'={'prop':"value"}}
  37#
  38# Both JSON and Python formatting should work, including both styles of
  39# string literal quotes. Both paradigms of literal values should work,
  40# including null/true/false for JSON and None/True/False for Python.
  41#
  42#
  43# Transactions have the following multi-line format:
  44#
  45#    transaction(
  46#    action-name1 [ arg-name1=arg1 ] ... [arg-nameN=argN ]
  47#    ...
  48#    action-nameN [ arg-name1=arg1 ] ... [arg-nameN=argN ]
  49#    )
  50#
  51# One line transactions are also supported:
  52#
  53#    transaction( action-name1 ... )
  54#
  55# For example:
  56#
  57#     (QEMU) transaction(
  58#     TRANS> block-dirty-bitmap-add node=drive0 name=bitmap1
  59#     TRANS> block-dirty-bitmap-clear node=drive0 name=bitmap0
  60#     TRANS> )
  61#     {"return": {}}
  62#     (QEMU)
  63#
  64# Use the -v and -p options to activate the verbose and pretty-print options,
  65# which will echo back the properly formatted JSON-compliant QMP that is being
  66# sent to QEMU, which is useful for debugging and documentation generation.
  67
  68import qmp
  69import json
  70import ast
  71import readline
  72import sys
  73
  74class QMPCompleter(list):
  75    def complete(self, text, state):
  76        for cmd in self:
  77            if cmd.startswith(text):
  78                if not state:
  79                    return cmd
  80                else:
  81                    state -= 1
  82
  83class QMPShellError(Exception):
  84    pass
  85
  86class QMPShellBadPort(QMPShellError):
  87    pass
  88
  89class FuzzyJSON(ast.NodeTransformer):
  90    '''This extension of ast.NodeTransformer filters literal "true/false/null"
  91    values in an AST and replaces them by proper "True/False/None" values that
  92    Python can properly evaluate.'''
  93    def visit_Name(self, node):
  94        if node.id == 'true':
  95            node.id = 'True'
  96        if node.id == 'false':
  97            node.id = 'False'
  98        if node.id == 'null':
  99            node.id = 'None'
 100        return node
 101
 102# TODO: QMPShell's interface is a bit ugly (eg. _fill_completion() and
 103#       _execute_cmd()). Let's design a better one.
 104class QMPShell(qmp.QEMUMonitorProtocol):
 105    def __init__(self, address, pretty=False):
 106        qmp.QEMUMonitorProtocol.__init__(self, self.__get_address(address))
 107        self._greeting = None
 108        self._completer = None
 109        self._pretty = pretty
 110        self._transmode = False
 111        self._actions = list()
 112
 113    def __get_address(self, arg):
 114        """
 115        Figure out if the argument is in the port:host form, if it's not it's
 116        probably a file path.
 117        """
 118        addr = arg.split(':')
 119        if len(addr) == 2:
 120            try:
 121                port = int(addr[1])
 122            except ValueError:
 123                raise QMPShellBadPort
 124            return ( addr[0], port )
 125        # socket path
 126        return arg
 127
 128    def _fill_completion(self):
 129        for cmd in self.cmd('query-commands')['return']:
 130            self._completer.append(cmd['name'])
 131
 132    def __completer_setup(self):
 133        self._completer = QMPCompleter()
 134        self._fill_completion()
 135        readline.set_completer(self._completer.complete)
 136        readline.parse_and_bind("tab: complete")
 137        # XXX: default delimiters conflict with some command names (eg. query-),
 138        # clearing everything as it doesn't seem to matter
 139        readline.set_completer_delims('')
 140
 141    def __parse_value(self, val):
 142        try:
 143            return int(val)
 144        except ValueError:
 145            pass
 146
 147        if val.lower() == 'true':
 148            return True
 149        if val.lower() == 'false':
 150            return False
 151        if val.startswith(('{', '[')):
 152            # Try first as pure JSON:
 153            try:
 154                return json.loads(val)
 155            except ValueError:
 156                pass
 157            # Try once again as FuzzyJSON:
 158            try:
 159                st = ast.parse(val, mode='eval')
 160                return ast.literal_eval(FuzzyJSON().visit(st))
 161            except SyntaxError:
 162                pass
 163            except ValueError:
 164                pass
 165        return val
 166
 167    def __cli_expr(self, tokens, parent):
 168        for arg in tokens:
 169            (key, _, val) = arg.partition('=')
 170            if not val:
 171                raise QMPShellError("Expected a key=value pair, got '%s'" % arg)
 172
 173            value = self.__parse_value(val)
 174            optpath = key.split('.')
 175            curpath = []
 176            for p in optpath[:-1]:
 177                curpath.append(p)
 178                d = parent.get(p, {})
 179                if type(d) is not dict:
 180                    raise QMPShellError('Cannot use "%s" as both leaf and non-leaf key' % '.'.join(curpath))
 181                parent[p] = d
 182                parent = d
 183            if optpath[-1] in parent:
 184                if type(parent[optpath[-1]]) is dict:
 185                    raise QMPShellError('Cannot use "%s" as both leaf and non-leaf key' % '.'.join(curpath))
 186                else:
 187                    raise QMPShellError('Cannot set "%s" multiple times' % key)
 188            parent[optpath[-1]] = value
 189
 190    def __build_cmd(self, cmdline):
 191        """
 192        Build a QMP input object from a user provided command-line in the
 193        following format:
 194
 195            < command-name > [ arg-name1=arg1 ] ... [ arg-nameN=argN ]
 196        """
 197        cmdargs = cmdline.split()
 198
 199        # Transactional CLI entry/exit:
 200        if cmdargs[0] == 'transaction(':
 201            self._transmode = True
 202            cmdargs.pop(0)
 203        elif cmdargs[0] == ')' and self._transmode:
 204            self._transmode = False
 205            if len(cmdargs) > 1:
 206                raise QMPShellError("Unexpected input after close of Transaction sub-shell")
 207            qmpcmd = { 'execute': 'transaction',
 208                       'arguments': { 'actions': self._actions } }
 209            self._actions = list()
 210            return qmpcmd
 211
 212        # Nothing to process?
 213        if not cmdargs:
 214            return None
 215
 216        # Parse and then cache this Transactional Action
 217        if self._transmode:
 218            finalize = False
 219            action = { 'type': cmdargs[0], 'data': {} }
 220            if cmdargs[-1] == ')':
 221                cmdargs.pop(-1)
 222                finalize = True
 223            self.__cli_expr(cmdargs[1:], action['data'])
 224            self._actions.append(action)
 225            return self.__build_cmd(')') if finalize else None
 226
 227        # Standard command: parse and return it to be executed.
 228        qmpcmd = { 'execute': cmdargs[0], 'arguments': {} }
 229        self.__cli_expr(cmdargs[1:], qmpcmd['arguments'])
 230        return qmpcmd
 231
 232    def _print(self, qmp):
 233        indent = None
 234        if self._pretty:
 235            indent = 4
 236        jsobj = json.dumps(qmp, indent=indent)
 237        print str(jsobj)
 238
 239    def _execute_cmd(self, cmdline):
 240        try:
 241            qmpcmd = self.__build_cmd(cmdline)
 242        except Exception as e:
 243            print 'Error while parsing command line: %s' % e
 244            print 'command format: <command-name> ',
 245            print '[arg-name1=arg1] ... [arg-nameN=argN]'
 246            return True
 247        # For transaction mode, we may have just cached the action:
 248        if qmpcmd is None:
 249            return True
 250        if self._verbose:
 251            self._print(qmpcmd)
 252        resp = self.cmd_obj(qmpcmd)
 253        if resp is None:
 254            print 'Disconnected'
 255            return False
 256        self._print(resp)
 257        return True
 258
 259    def connect(self):
 260        self._greeting = qmp.QEMUMonitorProtocol.connect(self)
 261        self.__completer_setup()
 262
 263    def show_banner(self, msg='Welcome to the QMP low-level shell!'):
 264        print msg
 265        version = self._greeting['QMP']['version']['qemu']
 266        print 'Connected to QEMU %d.%d.%d\n' % (version['major'],version['minor'],version['micro'])
 267
 268    def get_prompt(self):
 269        if self._transmode:
 270            return "TRANS> "
 271        return "(QEMU) "
 272
 273    def read_exec_command(self, prompt):
 274        """
 275        Read and execute a command.
 276
 277        @return True if execution was ok, return False if disconnected.
 278        """
 279        try:
 280            cmdline = raw_input(prompt)
 281        except EOFError:
 282            print
 283            return False
 284        if cmdline == '':
 285            for ev in self.get_events():
 286                print ev
 287            self.clear_events()
 288            return True
 289        else:
 290            return self._execute_cmd(cmdline)
 291
 292    def set_verbosity(self, verbose):
 293        self._verbose = verbose
 294
 295class HMPShell(QMPShell):
 296    def __init__(self, address):
 297        QMPShell.__init__(self, address)
 298        self.__cpu_index = 0
 299
 300    def __cmd_completion(self):
 301        for cmd in self.__cmd_passthrough('help')['return'].split('\r\n'):
 302            if cmd and cmd[0] != '[' and cmd[0] != '\t':
 303                name = cmd.split()[0] # drop help text
 304                if name == 'info':
 305                    continue
 306                if name.find('|') != -1:
 307                    # Command in the form 'foobar|f' or 'f|foobar', take the
 308                    # full name
 309                    opt = name.split('|')
 310                    if len(opt[0]) == 1:
 311                        name = opt[1]
 312                    else:
 313                        name = opt[0]
 314                self._completer.append(name)
 315                self._completer.append('help ' + name) # help completion
 316
 317    def __info_completion(self):
 318        for cmd in self.__cmd_passthrough('info')['return'].split('\r\n'):
 319            if cmd:
 320                self._completer.append('info ' + cmd.split()[1])
 321
 322    def __other_completion(self):
 323        # special cases
 324        self._completer.append('help info')
 325
 326    def _fill_completion(self):
 327        self.__cmd_completion()
 328        self.__info_completion()
 329        self.__other_completion()
 330
 331    def __cmd_passthrough(self, cmdline, cpu_index = 0):
 332        return self.cmd_obj({ 'execute': 'human-monitor-command', 'arguments':
 333                              { 'command-line': cmdline,
 334                                'cpu-index': cpu_index } })
 335
 336    def _execute_cmd(self, cmdline):
 337        if cmdline.split()[0] == "cpu":
 338            # trap the cpu command, it requires special setting
 339            try:
 340                idx = int(cmdline.split()[1])
 341                if not 'return' in self.__cmd_passthrough('info version', idx):
 342                    print 'bad CPU index'
 343                    return True
 344                self.__cpu_index = idx
 345            except ValueError:
 346                print 'cpu command takes an integer argument'
 347                return True
 348        resp = self.__cmd_passthrough(cmdline, self.__cpu_index)
 349        if resp is None:
 350            print 'Disconnected'
 351            return False
 352        assert 'return' in resp or 'error' in resp
 353        if 'return' in resp:
 354            # Success
 355            if len(resp['return']) > 0:
 356                print resp['return'],
 357        else:
 358            # Error
 359            print '%s: %s' % (resp['error']['class'], resp['error']['desc'])
 360        return True
 361
 362    def show_banner(self):
 363        QMPShell.show_banner(self, msg='Welcome to the HMP shell!')
 364
 365def die(msg):
 366    sys.stderr.write('ERROR: %s\n' % msg)
 367    sys.exit(1)
 368
 369def fail_cmdline(option=None):
 370    if option:
 371        sys.stderr.write('ERROR: bad command-line option \'%s\'\n' % option)
 372    sys.stderr.write('qemu-shell [ -v ] [ -p ] [ -H ] < UNIX socket path> | < TCP address:port >\n')
 373    sys.exit(1)
 374
 375def main():
 376    addr = ''
 377    qemu = None
 378    hmp = False
 379    pretty = False
 380    verbose = False
 381
 382    try:
 383        for arg in sys.argv[1:]:
 384            if arg == "-H":
 385                if qemu is not None:
 386                    fail_cmdline(arg)
 387                hmp = True
 388            elif arg == "-p":
 389                pretty = True
 390            elif arg == "-v":
 391                verbose = True
 392            else:
 393                if qemu is not None:
 394                    fail_cmdline(arg)
 395                if hmp:
 396                    qemu = HMPShell(arg)
 397                else:
 398                    qemu = QMPShell(arg, pretty)
 399                addr = arg
 400
 401        if qemu is None:
 402            fail_cmdline()
 403    except QMPShellBadPort:
 404        die('bad port number in command-line')
 405
 406    try:
 407        qemu.connect()
 408    except qmp.QMPConnectError:
 409        die('Didn\'t get QMP greeting message')
 410    except qmp.QMPCapabilitiesError:
 411        die('Could not negotiate capabilities')
 412    except qemu.error:
 413        die('Could not connect to %s' % addr)
 414
 415    qemu.show_banner()
 416    qemu.set_verbosity(verbose)
 417    while qemu.read_exec_command(qemu.get_prompt()):
 418        pass
 419    qemu.close()
 420
 421if __name__ == '__main__':
 422    main()
 423