3 # Low-level QEMU shell on top of QMP.
5 # Copyright (C) 2009, 2010 Red Hat Inc.
8 # Luiz Capitulino <lcapitulino@redhat.com>
10 # This work is licensed under the terms of the GNU GPL, version 2. See
11 # the COPYING file in the top-level directory.
17 # # qemu [...] -qmp unix:./qmp-sock,server
21 # $ qmp-shell ./qmp-sock
23 # Commands have the following format:
25 # < command-name > [ arg-name1=arg1 ] ... [ arg-nameN=argN ]
29 # (QEMU) device_add driver=e1000 id=net1
33 # key=value pairs also support Python or JSON object literal subset notations,
34 # without spaces. Dictionaries/objects {} are supported as are arrays [].
36 # example-command arg-name1={'key':'value','obj'={'prop':"value"}}
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.
43 # Transactions have the following multi-line format:
46 # action-name1 [ arg-name1=arg1 ] ... [arg-nameN=argN ]
48 # action-nameN [ arg-name1=arg1 ] ... [arg-nameN=argN ]
51 # One line transactions are also supported:
53 # transaction( action-name1 ... )
58 # TRANS> block-dirty-bitmap-add node=drive0 name=bitmap1
59 # TRANS> block-dirty-bitmap-clear node=drive0 name=bitmap0
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.
68 from __future__
import print_function
78 sys
.path
.append(os
.path
.join(os
.path
.dirname(__file__
), '..', '..', 'python'))
81 if sys
.version_info
[0] == 2:
84 class QMPCompleter(list):
85 def complete(self
, text
, state
):
87 if cmd
.startswith(text
):
93 class QMPShellError(Exception):
96 class QMPShellBadPort(QMPShellError
):
99 class FuzzyJSON(ast
.NodeTransformer
):
100 '''This extension of ast.NodeTransformer filters literal "true/false/null"
101 values in an AST and replaces them by proper "True/False/None" values that
102 Python can properly evaluate.'''
103 def visit_Name(self
, node
):
104 if node
.id == 'true':
106 if node
.id == 'false':
108 if node
.id == 'null':
112 # TODO: QMPShell's interface is a bit ugly (eg. _fill_completion() and
113 # _execute_cmd()). Let's design a better one.
114 class QMPShell(qmp
.QEMUMonitorProtocol
):
115 def __init__(self
, address
, pretty
=False):
116 super(QMPShell
, self
).__init
__(self
.__get
_address
(address
))
117 self
._greeting
= None
118 self
._completer
= None
119 self
._pretty
= pretty
120 self
._transmode
= False
121 self
._actions
= list()
122 self
._histfile
= os
.path
.join(os
.path
.expanduser('~'),
123 '.qmp-shell_history')
125 def __get_address(self
, arg
):
127 Figure out if the argument is in the port:host form, if it's not it's
128 probably a file path.
130 addr
= arg
.split(':')
135 raise QMPShellBadPort
136 return ( addr
[0], port
)
140 def _fill_completion(self
):
141 cmds
= self
.cmd('query-commands')
144 for cmd
in cmds
['return']:
145 self
._completer
.append(cmd
['name'])
147 def __completer_setup(self
):
148 self
._completer
= QMPCompleter()
149 self
._fill
_completion
()
150 readline
.set_history_length(1024)
151 readline
.set_completer(self
._completer
.complete
)
152 readline
.parse_and_bind("tab: complete")
153 # XXX: default delimiters conflict with some command names (eg. query-),
154 # clearing everything as it doesn't seem to matter
155 readline
.set_completer_delims('')
157 readline
.read_history_file(self
._histfile
)
158 except Exception as e
:
159 if isinstance(e
, IOError) and e
.errno
== errno
.ENOENT
:
160 # File not found. No problem.
163 print("Failed to read history '%s'; %s" % (self
._histfile
, e
))
164 atexit
.register(self
.__save
_history
)
166 def __save_history(self
):
168 readline
.write_history_file(self
._histfile
)
169 except Exception as e
:
170 print("Failed to save history file '%s'; %s" % (self
._histfile
, e
))
172 def __parse_value(self
, val
):
178 if val
.lower() == 'true':
180 if val
.lower() == 'false':
182 if val
.startswith(('{', '[')):
183 # Try first as pure JSON:
185 return json
.loads(val
)
188 # Try once again as FuzzyJSON:
190 st
= ast
.parse(val
, mode
='eval')
191 return ast
.literal_eval(FuzzyJSON().visit(st
))
198 def __cli_expr(self
, tokens
, parent
):
200 (key
, sep
, val
) = arg
.partition('=')
202 raise QMPShellError("Expected a key=value pair, got '%s'" % arg
)
204 value
= self
.__parse
_value
(val
)
205 optpath
= key
.split('.')
207 for p
in optpath
[:-1]:
209 d
= parent
.get(p
, {})
210 if type(d
) is not dict:
211 raise QMPShellError('Cannot use "%s" as both leaf and non-leaf key' % '.'.join(curpath
))
214 if optpath
[-1] in parent
:
215 if type(parent
[optpath
[-1]]) is dict:
216 raise QMPShellError('Cannot use "%s" as both leaf and non-leaf key' % '.'.join(curpath
))
218 raise QMPShellError('Cannot set "%s" multiple times' % key
)
219 parent
[optpath
[-1]] = value
221 def __build_cmd(self
, cmdline
):
223 Build a QMP input object from a user provided command-line in the
226 < command-name > [ arg-name1=arg1 ] ... [ arg-nameN=argN ]
228 cmdargs
= re
.findall(r
'''(?:[^\s"']|"(?:\\.|[^"])*"|'(?:\\.|[^'])*')+''', cmdline
)
230 # Transactional CLI entry/exit:
231 if cmdargs
[0] == 'transaction(':
232 self
._transmode
= True
234 elif cmdargs
[0] == ')' and self
._transmode
:
235 self
._transmode
= False
237 raise QMPShellError("Unexpected input after close of Transaction sub-shell")
238 qmpcmd
= { 'execute': 'transaction',
239 'arguments': { 'actions': self
._actions
} }
240 self
._actions
= list()
243 # Nothing to process?
247 # Parse and then cache this Transactional Action
250 action
= { 'type': cmdargs
[0], 'data': {} }
251 if cmdargs
[-1] == ')':
254 self
.__cli
_expr
(cmdargs
[1:], action
['data'])
255 self
._actions
.append(action
)
256 return self
.__build
_cmd
(')') if finalize
else None
258 # Standard command: parse and return it to be executed.
259 qmpcmd
= { 'execute': cmdargs
[0], 'arguments': {} }
260 self
.__cli
_expr
(cmdargs
[1:], qmpcmd
['arguments'])
263 def _print(self
, qmp
):
267 jsobj
= json
.dumps(qmp
, indent
=indent
)
270 def _execute_cmd(self
, cmdline
):
272 qmpcmd
= self
.__build
_cmd
(cmdline
)
273 except Exception as e
:
274 print('Error while parsing command line: %s' % e
)
275 print('command format: <command-name> ', end
=' ')
276 print('[arg-name1=arg1] ... [arg-nameN=argN]')
278 # For transaction mode, we may have just cached the action:
283 resp
= self
.cmd_obj(qmpcmd
)
285 print('Disconnected')
290 def connect(self
, negotiate
):
291 self
._greeting
= super(QMPShell
, self
).connect(negotiate
)
292 self
.__completer
_setup
()
294 def show_banner(self
, msg
='Welcome to the QMP low-level shell!'):
296 if not self
._greeting
:
299 version
= self
._greeting
['QMP']['version']['qemu']
300 print('Connected to QEMU %d.%d.%d\n' % (version
['major'],version
['minor'],version
['micro']))
302 def get_prompt(self
):
307 def read_exec_command(self
, prompt
):
309 Read and execute a command.
311 @return True if execution was ok, return False if disconnected.
314 cmdline
= input(prompt
)
319 for ev
in self
.get_events():
324 return self
._execute
_cmd
(cmdline
)
326 def set_verbosity(self
, verbose
):
327 self
._verbose
= verbose
329 class HMPShell(QMPShell
):
330 def __init__(self
, address
):
331 QMPShell
.__init
__(self
, address
)
334 def __cmd_completion(self
):
335 for cmd
in self
.__cmd
_passthrough
('help')['return'].split('\r\n'):
336 if cmd
and cmd
[0] != '[' and cmd
[0] != '\t':
337 name
= cmd
.split()[0] # drop help text
340 if name
.find('|') != -1:
341 # Command in the form 'foobar|f' or 'f|foobar', take the
343 opt
= name
.split('|')
348 self
._completer
.append(name
)
349 self
._completer
.append('help ' + name
) # help completion
351 def __info_completion(self
):
352 for cmd
in self
.__cmd
_passthrough
('info')['return'].split('\r\n'):
354 self
._completer
.append('info ' + cmd
.split()[1])
356 def __other_completion(self
):
358 self
._completer
.append('help info')
360 def _fill_completion(self
):
361 self
.__cmd
_completion
()
362 self
.__info
_completion
()
363 self
.__other
_completion
()
365 def __cmd_passthrough(self
, cmdline
, cpu_index
= 0):
366 return self
.cmd_obj({ 'execute': 'human-monitor-command', 'arguments':
367 { 'command-line': cmdline
,
368 'cpu-index': cpu_index
} })
370 def _execute_cmd(self
, cmdline
):
371 if cmdline
.split()[0] == "cpu":
372 # trap the cpu command, it requires special setting
374 idx
= int(cmdline
.split()[1])
375 if not 'return' in self
.__cmd
_passthrough
('info version', idx
):
376 print('bad CPU index')
378 self
.__cpu
_index
= idx
380 print('cpu command takes an integer argument')
382 resp
= self
.__cmd
_passthrough
(cmdline
, self
.__cpu
_index
)
384 print('Disconnected')
386 assert 'return' in resp
or 'error' in resp
389 if len(resp
['return']) > 0:
390 print(resp
['return'], end
=' ')
393 print('%s: %s' % (resp
['error']['class'], resp
['error']['desc']))
396 def show_banner(self
):
397 QMPShell
.show_banner(self
, msg
='Welcome to the HMP shell!')
400 sys
.stderr
.write('ERROR: %s\n' % msg
)
403 def fail_cmdline(option
=None):
405 sys
.stderr
.write('ERROR: bad command-line option \'%s\'\n' % option
)
406 sys
.stderr
.write('qmp-shell [ -v ] [ -p ] [ -H ] [ -N ] < UNIX socket path> | < TCP address:port >\n')
407 sys
.stderr
.write(' -v Verbose (echo command sent and received)\n')
408 sys
.stderr
.write(' -p Pretty-print JSON\n')
409 sys
.stderr
.write(' -H Use HMP interface\n')
410 sys
.stderr
.write(' -N Skip negotiate (for qemu-ga)\n')
422 for arg
in sys
.argv
[1:]:
439 qemu
= QMPShell(arg
, pretty
)
444 except QMPShellBadPort
:
445 die('bad port number in command-line')
448 qemu
.connect(negotiate
)
449 except qmp
.QMPConnectError
:
450 die('Didn\'t get QMP greeting message')
451 except qmp
.QMPCapabilitiesError
:
452 die('Could not negotiate capabilities')
454 die('Could not connect to %s' % addr
)
457 qemu
.set_verbosity(verbose
)
458 while qemu
.read_exec_command(qemu
.get_prompt()):
462 if __name__
== '__main__':