qemu-monitor.hx

   1 HXCOMM Use DEFHEADING() to define headings in both help text and texi
   2 HXCOMM Text between STEXI and ETEXI are copied to texi version and
   3 HXCOMM discarded from C version
   4 HXCOMM DEF(command, args, callback, arg_string, help) is used to construct
   5 HXCOMM monitor commands
   6 HXCOMM HXCOMM can be used for comments, discarded from both texi and C
   7
   8 STEXI
   9 @table @option
  10 ETEXI
  11
  12     { "help|?", "s?", help_cmd, "[cmd]", "show the help" },
  13 STEXI
  14 @item help or ? [@var{cmd}]
  15 Show the help for all commands or just for command @var{cmd}.
  16 ETEXI
  17
  18     { "commit", "s", do_commit,
  19       "device|all", "commit changes to the disk images (if -snapshot is used) or backing files" },
  20 STEXI
  21 @item commit
  22 Commit changes to the disk images (if -snapshot is used) or backing files.
  23 ETEXI
  24
  25     { "info", "s?", do_info,
  26       "[subcommand]", "show various information about the system state" },
  27 STEXI
  28 @item info @var{subcommand}
  29 Show various information about the system state.
  30
  31 @table @option
  32 @item info version
  33 show the version of QEMU
  34 @item info network
  35 show the various VLANs and the associated devices
  36 @item info chardev
  37 show the character devices
  38 @item info block
  39 show the block devices
  40 @item info block
  41 show block device statistics
  42 @item info registers
  43 show the cpu registers
  44 @item info cpus
  45 show infos for each CPU
  46 @item info history
  47 show the command line history
  48 @item info irq
  49 show the interrupts statistics (if available)
  50 @item info pic
  51 show i8259 (PIC) state
  52 @item info pci
  53 show emulated PCI device info
  54 @item info tlb
  55 show virtual to physical memory mappings (i386 only)
  56 @item info mem
  57 show the active virtual memory mappings (i386 only)
  58 @item info hpet
  59 show state of HPET (i386 only)
  60 @item info kqemu
  61 show KQEMU information
  62 @item info kvm
  63 show KVM information
  64 @item info usb
  65 show USB devices plugged on the virtual USB hub
  66 @item info usbhost
  67 show all USB host devices
  68 @item info profile
  69 show profiling information
  70 @item info capture
  71 show information about active capturing
  72 @item info snapshots
  73 show list of VM snapshots
  74 @item info status
  75 show the current VM status (running|paused)
  76 @item info pcmcia
  77 show guest PCMCIA status
  78 @item info mice
  79 show which guest mouse is receiving events
  80 @item info vnc
  81 show the vnc server status
  82 @item info name
  83 show the current VM name
  84 @item info uuid
  85 show the current VM UUID
  86 @item info cpustats
  87 show CPU statistics
  88 @item info slirp
  89 show SLIRP statistics (if available)
  90 @item info usernet
  91 show user network stack connection states
  92 @item info migrate
  93 show migration status
  94 @item info balloon
  95 show balloon information
  96 @item info qtree
  97 show device tree
  98 @end table
  99 ETEXI
 100
 101     { "q|quit", "", do_quit,
 102       "", "quit the emulator" },
 103 STEXI
 104 @item q or quit
 105 Quit the emulator.
 106 ETEXI
 107
 108     { "eject", "-fB", do_eject,
 109       "[-f] device", "eject a removable medium (use -f to force it)" },
 110 STEXI
 111 @item eject [-f] @var{device}
 112 Eject a removable medium (use -f to force it).
 113 ETEXI
 114
 115     { "change", "BFs?", do_change,
 116       "device filename [format]", "change a removable medium, optional format" },
 117 STEXI
 118 @item change @var{device} @var{setting}
 119
 120 Change the configuration of a device.
 121
 122 @table @option
 123 @item change @var{diskdevice} @var{filename} [@var{format}]
 124 Change the medium for a removable disk device to point to @var{filename}. eg
 125
 126 @example
 127 (qemu) change ide1-cd0 /path/to/some.iso
 128 @end example
 129
 130 @var{format} is optional.
 131
 132 @item change vnc @var{display},@var{options}
 133 Change the configuration of the VNC server. The valid syntax for @var{display}
 134 and @var{options} are described at @ref{sec_invocation}. eg
 135
 136 @example
 137 (qemu) change vnc localhost:1
 138 @end example
 139
 140 @item change vnc password [@var{password}]
 141
 142 Change the password associated with the VNC server. If the new password is not
 143 supplied, the monitor will prompt for it to be entered. VNC passwords are only
 144 significant up to 8 letters. eg
 145
 146 @example
 147 (qemu) change vnc password
 148 Password: ********
 149 @end example
 150
 151 @end table
 152 ETEXI
 153
 154     { "screendump", "F", do_screen_dump,
 155       "filename", "save screen into PPM image 'filename'" },
 156 STEXI
 157 @item screendump @var{filename}
 158 Save screen into PPM image @var{filename}.
 159 ETEXI
 160
 161     { "logfile", "F", do_logfile,
 162       "filename", "output logs to 'filename'" },
 163 STEXI
 164 @item logfile @var{filename}
 165 Output logs to @var{filename}.
 166 ETEXI
 167
 168     { "log", "s", do_log,
 169       "item1[,...]", "activate logging of the specified items to '/tmp/qemu.log'" },
 170 STEXI
 171 @item log @var{item1}[,...]
 172 Activate logging of the specified items to @file{/tmp/qemu.log}.
 173 ETEXI
 174
 175     { "savevm", "s?", do_savevm,
 176       "[tag|id]", "save a VM snapshot. If no tag or id are provided, a new snapshot is created" },
 177 STEXI
 178 @item savevm [@var{tag}|@var{id}]
 179 Create a snapshot of the whole virtual machine. If @var{tag} is
 180 provided, it is used as human readable identifier. If there is already
 181 a snapshot with the same tag or ID, it is replaced. More info at
 182 @ref{vm_snapshots}.
 183 ETEXI
 184
 185     { "loadvm", "s", do_loadvm,
 186       "tag|id", "restore a VM snapshot from its tag or id" },
 187 STEXI
 188 @item loadvm @var{tag}|@var{id}
 189 Set the whole virtual machine to the snapshot identified by the tag
 190 @var{tag} or the unique snapshot ID @var{id}.
 191 ETEXI
 192
 193     { "delvm", "s", do_delvm,
 194       "tag|id", "delete a VM snapshot from its tag or id" },
 195 STEXI
 196 @item delvm @var{tag}|@var{id}
 197 Delete the snapshot identified by @var{tag} or @var{id}.
 198 ETEXI
 199
 200     { "singlestep", "s?", do_singlestep,
 201       "[on|off]", "run emulation in singlestep mode or switch to normal mode", },
 202 STEXI
 203 @item singlestep [off]
 204 Run the emulation in single step mode.
 205 If called with option off, the emulation returns to normal mode.
 206 ETEXI
 207
 208     { "stop", "", do_stop,
 209       "", "stop emulation", },
 210 STEXI
 211 @item stop
 212 Stop emulation.
 213 ETEXI
 214
 215     { "c|cont", "", do_cont,
 216       "", "resume emulation", },
 217 STEXI
 218 @item c or cont
 219 Resume emulation.
 220 ETEXI
 221
 222     { "gdbserver", "s?", do_gdbserver,
 223       "[device]", "start gdbserver on given device (default 'tcp::1234'), stop with 'none'", },
 224 STEXI
 225 @item gdbserver [@var{port}]
 226 Start gdbserver session (default @var{port}=1234)
 227 ETEXI
 228
 229     { "x", "/l", do_memory_dump,
 230       "/fmt addr", "virtual memory dump starting at 'addr'", },
 231 STEXI
 232 @item x/fmt @var{addr}
 233 Virtual memory dump starting at @var{addr}.
 234 ETEXI
 235
 236     { "xp", "/l", do_physical_memory_dump,
 237       "/fmt addr", "physical memory dump starting at 'addr'", },
 238 STEXI
 239 @item xp /@var{fmt} @var{addr}
 240 Physical memory dump starting at @var{addr}.
 241
 242 @var{fmt} is a format which tells the command how to format the
 243 data. Its syntax is: @option{/@{count@}@{format@}@{size@}}
 244
 245 @table @var
 246 @item count
 247 is the number of items to be dumped.
 248
 249 @item format
 250 can be x (hex), d (signed decimal), u (unsigned decimal), o (octal),
 251 c (char) or i (asm instruction).
 252
 253 @item size
 254 can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
 255 @code{h} or @code{w} can be specified with the @code{i} format to
 256 respectively select 16 or 32 bit code instruction size.
 257
 258 @end table
 259
 260 Examples:
 261 @itemize
 262 @item
 263 Dump 10 instructions at the current instruction pointer:
 264 @example
 265 (qemu) x/10i $eip
 266 0x90107063:  ret
 267 0x90107064:  sti
 268 0x90107065:  lea    0x0(%esi,1),%esi
 269 0x90107069:  lea    0x0(%edi,1),%edi
 270 0x90107070:  ret
 271 0x90107071:  jmp    0x90107080
 272 0x90107073:  nop
 273 0x90107074:  nop
 274 0x90107075:  nop
 275 0x90107076:  nop
 276 @end example
 277
 278 @item
 279 Dump 80 16 bit values at the start of the video memory.
 280 @smallexample
 281 (qemu) xp/80hx 0xb8000
 282 0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
 283 0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
 284 0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
 285 0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
 286 0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
 287 0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
 288 0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
 289 0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
 290 0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
 291 0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
 292 @end smallexample
 293 @end itemize
 294 ETEXI
 295
 296     { "p|print", "/l", do_print,
 297       "/fmt expr", "print expression value (use $reg for CPU register access)", },
 298 STEXI
 299 @item p or print/@var{fmt} @var{expr}
 300
 301 Print expression value. Only the @var{format} part of @var{fmt} is
 302 used.
 303 ETEXI
 304
 305     { "i", "/ii.", do_ioport_read,
 306       "/fmt addr", "I/O port read" },
 307 STEXI
 308 Read I/O port.
 309 ETEXI
 310
 311
 312     { "sendkey", "si?", do_sendkey,
 313       "keys [hold_ms]", "send keys to the VM (e.g. 'sendkey ctrl-alt-f1', default hold time=100 ms)" },
 314 STEXI
 315 @item sendkey @var{keys}
 316
 317 Send @var{keys} to the emulator. @var{keys} could be the name of the
 318 key or @code{#} followed by the raw value in either decimal or hexadecimal
 319 format. Use @code{-} to press several keys simultaneously. Example:
 320 @example
 321 sendkey ctrl-alt-f1
 322 @end example
 323
 324 This command is useful to send keys that your graphical user interface
 325 intercepts at low level, such as @code{ctrl-alt-f1} in X Window.
 326 ETEXI
 327
 328     { "system_reset", "", do_system_reset,
 329       "", "reset the system" },
 330 STEXI
 331 @item system_reset
 332
 333 Reset the system.
 334 ETEXI
 335
 336     { "system_powerdown", "", do_system_powerdown,
 337       "", "send system power down event" },
 338 STEXI
 339 @item system_powerdown
 340
 341 Power down the system (if supported).
 342 ETEXI
 343
 344     { "sum", "ii", do_sum,
 345       "addr size", "compute the checksum of a memory region" },
 346 STEXI
 347 @item sum @var{addr} @var{size}
 348
 349 Compute the checksum of a memory region.
 350 ETEXI
 351
 352     { "usb_add", "s", do_usb_add,
 353       "device", "add USB device (e.g. 'host:bus.addr' or 'host:vendor_id:product_id')" },
 354 STEXI
 355 @item usb_add @var{devname}
 356
 357 Add the USB device @var{devname}.  For details of available devices see
 358 @ref{usb_devices}
 359 ETEXI
 360
 361     { "usb_del", "s", do_usb_del,
 362       "device", "remove USB device 'bus.addr'" },
 363 STEXI
 364 @item usb_del @var{devname}
 365
 366 Remove the USB device @var{devname} from the QEMU virtual USB
 367 hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor
 368 command @code{info usb} to see the devices you can remove.
 369 ETEXI
 370
 371     { "cpu", "i", do_cpu_set,
 372       "index", "set the default CPU" },
 373 STEXI
 374 Set the default CPU.
 375 ETEXI
 376
 377     { "mouse_move", "sss?", do_mouse_move,
 378       "dx dy [dz]", "send mouse move events" },
 379 STEXI
 380 @item mouse_move @var{dx} @var{dy} [@var{dz}]
 381 Move the active mouse to the specified coordinates @var{dx} @var{dy}
 382 with optional scroll axis @var{dz}.
 383 ETEXI
 384
 385     { "mouse_button", "i", do_mouse_button,
 386       "state", "change mouse button state (1=L, 2=M, 4=R)" },
 387 STEXI
 388 @item mouse_button @var{val}
 389 Change the active mouse button state @var{val} (1=L, 2=M, 4=R).
 390 ETEXI
 391
 392     { "mouse_set", "i", do_mouse_set,
 393       "index", "set which mouse device receives events" },
 394 STEXI
 395 @item mouse_set @var{index}
 396 Set which mouse device receives events at given @var{index}, index
 397 can be obtained with
 398 @example
 399 info mice
 400 @end example
 401 ETEXI
 402
 403 #ifdef HAS_AUDIO
 404     { "wavcapture", "si?i?i?", do_wav_capture,
 405       "path [frequency [bits [channels]]]",
 406       "capture audio to a wave file (default frequency=44100 bits=16 channels=2)" },
 407 #endif
 408 STEXI
 409 @item wavcapture @var{filename} [@var{frequency} [@var{bits} [@var{channels}]]]
 410 Capture audio into @var{filename}. Using sample rate @var{frequency}
 411 bits per sample @var{bits} and number of channels @var{channels}.
 412
 413 Defaults:
 414 @itemize @minus
 415 @item Sample rate = 44100 Hz - CD quality
 416 @item Bits = 16
 417 @item Number of channels = 2 - Stereo
 418 @end itemize
 419 ETEXI
 420
 421 #ifdef HAS_AUDIO
 422     { "stopcapture", "i", do_stop_capture,
 423       "capture index", "stop capture" },
 424 #endif
 425 STEXI
 426 @item stopcapture @var{index}
 427 Stop capture with a given @var{index}, index can be obtained with
 428 @example
 429 info capture
 430 @end example
 431 ETEXI
 432
 433     { "memsave", "lis", do_memory_save,
 434       "addr size file", "save to disk virtual memory dump starting at 'addr' of size 'size'", },
 435 STEXI
 436 @item memsave @var{addr} @var{size} @var{file}
 437 save to disk virtual memory dump starting at @var{addr} of size @var{size}.
 438 ETEXI
 439
 440     { "pmemsave", "lis", do_physical_memory_save,
 441       "addr size file", "save to disk physical memory dump starting at 'addr' of size 'size'", },
 442 STEXI
 443 @item pmemsave @var{addr} @var{size} @var{file}
 444 save to disk physical memory dump starting at @var{addr} of size @var{size}.
 445 ETEXI
 446
 447     { "boot_set", "s", do_boot_set,
 448       "bootdevice", "define new values for the boot device list" },
 449 STEXI
 450 @item boot_set @var{bootdevicelist}
 451
 452 Define new values for the boot device list. Those values will override
 453 the values specified on the command line through the @code{-boot} option.
 454
 455 The values that can be specified here depend on the machine type, but are
 456 the same that can be specified in the @code{-boot} command line option.
 457 ETEXI
 458
 459 #if defined(TARGET_I386)
 460     { "nmi", "i", do_inject_nmi,
 461       "cpu", "inject an NMI on the given CPU", },
 462 #endif
 463 STEXI
 464 @item nmi @var{cpu}
 465 Inject an NMI on the given CPU (x86 only).
 466 ETEXI
 467
 468     { "migrate", "-ds", do_migrate,
 469       "[-d] uri", "migrate to URI (using -d to not wait for completion)" },
 470 STEXI
 471 @item migrate [-d] @var{uri}
 472 Migrate to @var{uri} (using -d to not wait for completion).
 473 ETEXI
 474
 475     { "migrate_cancel", "", do_migrate_cancel,
 476       "", "cancel the current VM migration" },
 477 STEXI
 478 @item migrate_cancel
 479 Cancel the current VM migration.
 480 ETEXI
 481
 482     { "migrate_set_speed", "s", do_migrate_set_speed,
 483       "value", "set maximum speed (in bytes) for migrations" },
 484 STEXI
 485 @item migrate_set_speed @var{value}
 486 Set maximum speed to @var{value} (in bytes) for migrations.
 487 ETEXI
 488
 489     { "migrate_set_downtime", "s", do_migrate_set_downtime,
 490       "value", "set maximum tolerated downtime (in seconds) for migrations" },
 491
 492 STEXI
 493 @item migrate_set_downtime @var{second}
 494 Set maximum tolerated downtime (in seconds) for migration.
 495 ETEXI
 496
 497 #if defined(TARGET_I386)
 498     { "drive_add", "ss", drive_hot_add, "pci_addr=[[<domain>:]<bus>:]<slot>\n"
 499                                          "[file=file][,if=type][,bus=n]\n"
 500                                         "[,unit=m][,media=d][index=i]\n"
 501                                         "[,cyls=c,heads=h,secs=s[,trans=t]]\n"
 502                                         "[snapshot=on|off][,cache=on|off]",
 503                                         "add drive to PCI storage controller" },
 504 #endif
 505 STEXI
 506 @item drive_add
 507 Add drive to PCI storage controller.
 508 ETEXI
 509
 510 #if defined(TARGET_I386)
 511     { "pci_add", "sss", pci_device_hot_add, "pci_addr=auto|[[<domain>:]<bus>:]<slot> nic|storage [[vlan=n][,macaddr=addr][,model=type]] [file=file][,if=type][,bus=nr]...", "hot-add PCI device" },
 512 #endif
 513 STEXI
 514 @item pci_add
 515 Hot-add PCI device.
 516 ETEXI
 517
 518 #if defined(TARGET_I386)
 519     { "pci_del", "s", pci_device_hot_remove, "pci_addr=[[<domain>:]<bus>:]<slot>", "hot remove PCI device" },
 520 #endif
 521 STEXI
 522 @item pci_del
 523 Hot remove PCI device.
 524 ETEXI
 525
 526     { "host_net_add", "ss?", net_host_device_add,
 527       "tap|user|socket|vde|dump [options]", "add host VLAN client" },
 528 STEXI
 529 @item host_net_add
 530 Add host VLAN client.
 531 ETEXI
 532
 533     { "host_net_remove", "is", net_host_device_remove,
 534       "vlan_id name", "remove host VLAN client" },
 535 STEXI
 536 @item host_net_remove
 537 Remove host VLAN client.
 538 ETEXI
 539
 540 #ifdef CONFIG_SLIRP
 541     { "hostfwd_add", "s", net_slirp_hostfwd_add,
 542       "[tcp|udp]:[hostaddr]:hostport-[guestaddr]:guestport",
 543       "redirect TCP or UDP connections from host to guest (requires -net user)" },
 544     { "hostfwd_remove", "s", net_slirp_hostfwd_remove,
 545       "[tcp|udp]:[hostaddr]:hostport",
 546       "remove host-to-guest TCP or UDP redirection" },
 547 #endif
 548 STEXI
 549 @item host_net_redir
 550 Redirect TCP or UDP connections from host to guest (requires -net user).
 551 ETEXI
 552
 553     { "balloon", "i", do_balloon,
 554       "target", "request VM to change it's memory allocation (in MB)" },
 555 STEXI
 556 @item balloon @var{value}
 557 Request VM to change its memory allocation to @var{value} (in MB).
 558 ETEXI
 559
 560     { "set_link", "ss", do_set_link,
 561       "name up|down", "change the link status of a network adapter" },
 562 STEXI
 563 @item set_link @var{name} [up|down]
 564 Set link @var{name} up or down.
 565 ETEXI
 566
 567     { "watchdog_action", "s", do_watchdog_action,
 568       "[reset|shutdown|poweroff|pause|debug|none]", "change watchdog action" },
 569 STEXI
 570 @item watchdog_action
 571 Change watchdog action.
 572 ETEXI
 573
 574     { "acl", "sss?i?", do_acl, "<command> <aclname> [<match> [<index>]]\n",
 575                                "acl show vnc.username\n"
 576                                "acl policy vnc.username deny\n"
 577                                "acl allow vnc.username fred\n"
 578                                "acl deny vnc.username bob\n"
 579                                "acl reset vnc.username\n" },
 580 STEXI
 581 @item acl @var{subcommand} @var{aclname} @var{match} @var{index}
 582
 583 Manage access control lists for network services. There are currently
 584 two named access control lists, @var{vnc.x509dname} and @var{vnc.username}
 585 matching on the x509 client certificate distinguished name, and SASL
 586 username respectively.
 587
 588 @table @option
 589 @item acl show <aclname>
 590 list all the match rules in the access control list, and the default
 591 policy
 592 @item acl policy <aclname> @code{allow|deny}
 593 set the default access control list policy, used in the event that
 594 none of the explicit rules match. The default policy at startup is
 595 always @code{deny}
 596 @item acl allow <aclname> <match> [<index>]
 597 add a match to the access control list, allowing access. The match will
 598 normally be an exact username or x509 distinguished name, but can
 599 optionally include wildcard globs. eg @code{*@@EXAMPLE.COM} to allow
 600 all users in the @code{EXAMPLE.COM} kerberos realm. The match will
 601 normally be appended to the end of the ACL, but can be inserted
 602 earlier in the list if the optional @code{index} parameter is supplied.
 603 @item acl deny <aclname> <match> [<index>]
 604 add a match to the access control list, denying access. The match will
 605 normally be an exact username or x509 distinguished name, but can
 606 optionally include wildcard globs. eg @code{*@@EXAMPLE.COM} to allow
 607 all users in the @code{EXAMPLE.COM} kerberos realm. The match will
 608 normally be appended to the end of the ACL, but can be inserted
 609 earlier in the list if the optional @code{index} parameter is supplied.
 610 @item acl remove <aclname> <match>
 611 remove the specified match rule from the access control list.
 612 @item acl reset <aclname>
 613 remove all matches from the access control list, and set the default
 614 policy back to @code{deny}.
 615 @end table
 616 ETEXI
 617
 618 STEXI
 619 @end table
 620 ETEXI